IBC Precompile
The IBC precompile and inbound EVM hooks ship in v1.21.0 and are available on Testnet from v1.21.0-beta. See the Chain Portal for mainnet activation status.
0x0000000000000000000000000000000000000069.
It allows EVM callers on Injective to initiate ICS-20 token transfers, and inbound ICS-20 transfers with appropriate memo instructions to invoke an EVM receiver contract.
Both transfer directions use the MultiVM Token Standard to resolve assets. Outbound transfers debit the immediate caller’s native bank balance. Inbound hooks receive the token address and amount after the ICS-20 receiver is credited.
Quick reference
How an outbound transfer works
Steps 1 to 6 run inside the calling transaction. The precompile resolves the token to a bank denom, builds an ICS-20MsgTransfer with the caller as sender, and hands it to the transfer module, which escrows or burns the amount and commits the packet. The returned sequence identifies the packet. If the enclosing EVM execution reverts after the call, the debit, the packet commitment and the sequence update are all rolled back with it.
Steps 7 to 10 happen later, in other transactions. A relayer carries the packet, the counterparty acknowledges it or lets it time out, and the transfer module processes the result. A successful call to transfer means the packet was dispatched. It does not mean the receiver was credited. On an error acknowledgement or a timeout, the escrowed amount returns to the sender, which is the calling contract, not the account that called the contract.
Interface
The precompile declares no events. The transfer module emits the standard ICS-20 events for the packet.
Token resolution
See the ERC20 module for token pair queries.
Who pays and who is refunded
The ICS-20 sender is the bech32 form ofmsg.sender, the account or contract that calls 0x69 directly. The amount is debited from that account’s bank balance synchronously. A user calling a router that calls the precompile does not become the sender. The router is the sender, the router’s balance is debited, and any refund after a timeout or an error acknowledgement lands on the router. A contract that forwards transfers for users needs its own accounting for refunds and a way to sweep them.
No ERC20 approve is involved. Only the caller’s own balance can be sent. The method is not payable and reverts with the IBC precompile does not accept value transfers if value is attached.
Gas
The call charges an upfront floor of 200,000 gas plus a per byte cost on the calldata. Native work performed by the transfer module beyond that floor is charged to the EVM frame at a rate of 10 native gas units per EVM gas unit. If the native work exhausts the gas available to the frame, the call fails with an EVM out of gas error. The entire ABI encoded call is limited to 36 KiB, which accommodates the maximum memo and receiver sizes.Failure behavior
The call reverts, with no native or EVM state change, when the token cannot be resolved, the amount is zero or above the caller’s spendable balance, the channel does not exist or is closed, the timeout configuration is rejected by IBC, the receiver or memo fail ICS-20 validation, or escrow, burn or packet commitment fails. The revert reason carries the underlying message, prefixed withinvalid IBC transfer: for validation failures and IBC transfer failed: for transfer module failures. Static calls revert with the transfer method is not readonly.
Channel discovery
Choose your network to list open ICS-20 transfer channels and their counterparties.- Testnet
- Mainnet
next_key is present, set PAGE_KEY to that value and rerun the same command to see the next page. Use channel_id when sending from Injective and counterparty.channel_id when sending back. Confirm both light clients are active and a relayer serves the route.
Inbound EVM hooks
An ICS-20 packet arriving on Injective can call a contract after the transfer settles. The sending side puts anevm object in the packet memo:
Funds settle to the ICS-20 receiver first, through the normal transfer path. Only then does the hooks middleware read the memo and call the contract. A hook that reverts, a target address without code, return data above 4,096 bytes, or a
gas_limit above the cap each produce an error acknowledgement. The counterparty processes that acknowledgement and refunds the original sender there. A relayer that supplies too little gas for the hook causes the relay transaction itself to fail, which is retryable and does not produce an acknowledgement.
The success acknowledgement is a JSON object with two fields: contract_result, the hook’s return data, and ibc_ack, the underlying ICS-20 acknowledgement.
Hook contract requirements
ImplementonIBCTransfer(string,string,address,uint256,address,bytes) with a bytes return value. The implementation must check that msg.sender is 0x0000000000000000000000000000000000000069.
The call always comes from
0x0000000000000000000000000000000000000069, with a zero gas price. The require on msg.sender is what prevents any other account from invoking the hook with forged parameters. Without it, anyone can call onIBCTransfer directly.
The hook contract does not receive the funds unless receiver is the contract itself. The ICS-20 receiver is set by the sender on the counterparty chain, so a flow that wants the contract to hold the funds sets the receiver to the contract’s Injective address and names the same contract in the memo.
Token resolution for inbound packets
An IBC denom arriving on Injective for the first time has no token pair. Pair creation for IBC denoms is permissionless under the MultiVM Token Standard, and the pair must exist before a hook can deliver that token. See MultiVM Token Standard.
Hook gas cap
The cap is the smaller of the txfeesMaxGasWantedPerTx parameter and the block gas limit, minus a 5,000,000 gas reserve for the rest of the relay transaction. On mainnet this works out to 70,000,000. A gas_limit above the cap is rejected before any execution with IBC hook gas limit N exceeds the cap of M, as an error acknowledgement.
Observing hook calls through the EVM gateway
The chain emitsinjective.evm.v1.EventIBCHookCall for every attempted hook call, with the destination port and channel, packet sequence, contract, ABI encoded input, success flag and return data. The EVM gateway virtualizes this event into a synthetic transaction, receipt and logs, so eth_getTransactionReceipt and eth_getLogs show hook executions alongside ordinary EVM transactions. The receipt carries the contract’s own logs followed by one summary log emitted from the reserved pseudo address 0x0000000000000000000000000000000000000800 with the topic IBCHookCall(string,string,uint64,address,bool,bytes,string,uint256). The pseudo address differs from the hook caller 0x69 so that summary logs are distinguishable from logs emitted by contracts.
Your RPC provider must run a gateway release that supports IBC hook event virtualization and enable event virtualization on the gateway. Confirm both before relying on synthetic receipts and logs. The Chain LCD provides packet commitments at
/ibc/core/channel/v1/channels/{channel}/ports/transfer/packet_commitments and acknowledgements at /ibc/core/channel/v1/channels/{channel}/ports/transfer/packet_acks/{sequence} regardless of the gateway configuration.Known limitations
- A returned sequence means the packet was dispatched. Delivery and the acknowledgement are asynchronous.
- Refunds after a timeout or error acknowledgement land on the calling contract, not on the account that called the contract.
- The precompile emits no EVM events. Observe the transfer through the ICS-20 events and the packet sequence.
- EVM contracts receive no callback for acknowledgements or timeouts of their outbound transfers. The
ibc_callbackmemo path is for Wasm senders only and is rejected here. - The hook delivers tokens only when the received denom resolves to an EVM address. Unpaired denoms produce an error acknowledgement and a refund.
packetSenderis unauthenticated packet data.- Synthetic receipts and logs for hook calls depend on the gateway version your RPC provider runs.
- The method is not available in Foundry’s simulated EVM.
