Skip to main content

Cross Shard Contract Call Connector

The Cross Shard Contract Call Connector facilitates cross-shard calls with callbacks through the Calimero bridge. This means that contracts on Calimero can call contracts on NEAR and receive callbacks, and vice versa.

To install the bridge and fulfill its prerequisites, refer to the Running a Bridge section.

Assuming that a bridge between NEAR Testnet and a Calimero shard is set up, follow the steps below to utilize the Cross Shard Contract Call Connector:

Setting up the xsc_connectors​

On the xsc_connector, the contract owner must set the locker account, which corresponds to the xsc_connector contract on the other chain. This information is necessary for verifying transactions/receipts that occurred on the other network and ensuring they are associated with the appropriate xsc_connector contract.

Executing a cross-shard contract call​

To execute a call into a contract on another chain, the DApp needs to invoke the cross_call method on the xsc_connector (shorthand for cross-shard connector contract). Here's the method signature:

pub fn cross_call(
  &mut self,
  destination_contract_id: String,
  destination_contract_method: String,
  destination_contract_args: String,
  destination_gas: Gas,
  destination_deposit: Balance,
  source_callback_method: String,
)
  • destination_contract_id: The contract ID on the other chain where the call is intended.
  • destination_contract_method: The method to be called on the destination contract.
  • destination_contract_args: The arguments provided to the method in serialized JSON format.
  • destination_gas: The amount of gas allocated for the call on the other network.
  • destination_deposit: The deposit amount for the destination contract.
  • source_callback_method: The name of the callback method inside the contract from which the cross-call originates.

When the cross_call is executed, it emits a CALIMERO_EVENT_CROSS_CALL event with all the given input parameters appended to the event.

After the event is emitted, the indexer detects it and populates the message queue. Both the relayer and the bridge service subscribe to Calimero events in the message queue. Simultaneously, both components receive this event from the message queue. The relayer sends a block from the source chain to the light client contract on the destination chain, along with the latest light client block. Meanwhile, the bridge service fetches the RPC for the EXPERIMENTAL_light_client_proof and obtains the latest block height from the light client contract. Using the proof data and the block height, the bridge service calls the xsc_connector on the other network, specifically the cross_call_execute method. If it can be proven that a cross_call was initiated on the other network, the xsc_connector executes the specified method on the contract on the other chain.

Callback execution​

Once the cross_call_execute method executes the call on the contract on the other chain, a CALIMERO_EVENT_CROSS_RESPONSE event is emitted on that chain.

The event contains the following appended parameters: source_contract_id, source_contract_method, and the base64-encoded execution_result.

Through the bridge service, this event is verified on the originating chain, and the callback arguments are provided to the original smart contract that initiated the cross-call.

With this process, a full circle is completed: a contract on Chain A calls a method on a contract on Chain B, receives a callback with the result from executing the contract method on Chain B, and brings the result back to Chain A.