This guide is intended for developers who want to understand the technical implementation of the bridge mechanism. For user-friendly instructions, see Deposit Tokens.
Moving between two large-scale blockchain networks requires a secure and robust cross-chain bridge. Shibarium achieves this by utilizing both Plasma and PoS security to create a trustless and bi-directional transaction environment between Shibarium and Ethereum. This enables you to transfer tokens between the two networks without any third-party risks or impact on market liquidity. The network bridge is designed to be fast, cost-effective, and flexible, and also serves as a scaling solution.
The bridge utilizes a dual consensus architecture (Plasma + PoS platform) to prioritize speed and decentralization, with deliberate enabling of arbitrary state transitions on its sidechains along with EVM support.

​
How State Sync Works

To natively read Ethereum data from the Shibarium EVM chain, the mechanism utilized is known as ‘State Sync’. This process facilitates the transfer of arbitrary data from the Ethereum chain to the Shibarium chain. The essential steps involve validators on the Heimdall layer listening for a specific event called ‘StateSynced’ from a Sender contract. Once this event is detected, the associated data is written to the Receiver contract.
1

Deploy Sender Contract

Deploy the Sender contract on Sepolia (Ethereum testnet). The Sender contract’s primary function is to call the syncState function on the StateSender contract.
// Sender.sol
pragma solidity ^0.5.11;

contract IStateSender {
    function syncState(address receiver, bytes calldata data) external;
    function register(address sender, address receiver) public;
}

contract sender {
    address public stateSenderContract = 0x3a122785bC4d951D132B2CAD31FC187D6DC7A21C;
    address public receiver = 0x83bB46B64b311c89bEF813A534291e155459579e;
    uint public states = 0;
    
    function sendState(bytes calldata data) external {
        states = states + 1;
        IStateSender(stateSenderContract).syncState(receiver, data);
    }
}
Use Remix to deploy the contract and note the address and ABI for later use.
2

Deploy Receiver Contract

Deploy the Receiver contract on Puppynet (Shibarium’s testnet). The Receiver contract is invoked by a Validator when the ‘StateSynced’ event is emitted.
// receiver.sol
pragma solidity ^0.5.11;

// IStateReceiver represents interface to receive state
interface IStateReceiver {
    function onStateReceive(uint256 stateId, bytes calldata data) external;
}

contract receiver {
    uint public lastStateId;
    bytes public lastChildData;
    
    function onStateReceive(uint256 stateId, bytes calldata data) external {
        lastStateId = stateId;
        lastChildData = data;
    }
}
3

Map Sender and Receiver

Use the deployed addresses or deploy custom contracts and request a mapping through the Shibarium bridge interface.
The StateSender.sol contract must be aware of each sender and receiver, and a mapping request should be initiated.
4

Send and Receive Data

Write a node script to send arbitrary hex bytes, receive them on Puppynet, and interpret the data.
const Web3 = require('web3');

// Connect to Sepolia
const web3 = new Web3('YOUR_SEPOLIA_RPC_URL');

// Sender contract ABI and address
const senderABI = [/* Your ABI here */];
const senderAddress = 'YOUR_SENDER_CONTRACT_ADDRESS';

const senderContract = new web3.eth.Contract(senderABI, senderAddress);

// Send arbitrary data
const data = web3.utils.toHex('Hello from Ethereum!');

async function sendData() {
    try {
        const result = await senderContract.methods.sendState(data).send({
            from: 'YOUR_WALLET_ADDRESS',
            gas: 200000
        });
        console.log('Transaction hash:', result.transactionHash);
    } catch (error) {
        console.error('Error sending data:', error);
    }
}

sendData();

​
Contract Addresses

​
StateSender Contract Addresses

NetworkAddress
Sepolia0x0844c0ca42F24972e89233F476B033F763C2355a
Ethereum Mainnet0x3a122785bC4d951D132B2CAD31FC187D6DC7A21C

​
Token Transfer Process

When your token crosses the bridge, it does not change its circulating supply:
  1. Token leaves Ethereum: Shibarium mints the same number of tokens (1:1) as a pegged token
  2. Token returns to Ethereum: Tokens are burned on the Shibarium network and unlocked on the Ethereum network
This 1:1 ratio ensures that the total circulating supply remains constant across both networks.

​
Security Considerations

Always verify contract addresses and ensure you’re interacting with the official Shibarium bridge contracts.
  • The bridge utilizes both Plasma and PoS security mechanisms
  • Validators on the Heimdall layer ensure data integrity
  • State Sync events are validated before processing
  • Contract mappings must be approved through official channels

​
Troubleshooting

​
Next Steps