Cross Contract Call

This example performs the simplest cross-contract call possible: it calls our Hello NEAR example to set and retrieve a greeting. It is one of the simplest examples on making a cross-contract call, and the perfect gateway to the world of interoperative contracts.

Advanced Cross-Contract Calls The final part of this tutorial shows how to perform cross-contract calls in batches and in parallel.

Clone the Example

You have two options to start the project:

You can use the app through Github Codespaces, which will open a web-based interactive environment.
Clone the repository locally and use it from your computer.

Codespaces	Clone locally
	🌐 `https://github.com/near-examples/cross-contract-calls`

Structure of the Example

The smart contract is written in Rust and has the following structure:

┌── tests # sandbox testing
│    ├── hello-near
│    │    └── hello-near.wasm
│    └── tests.rs
├── src # contract's code
│    ├── external.rs
│    └── lib.rs
├── Cargo.toml # package manager
├── README.md
└── rust-toolchain.toml

Smart Contract

The contract exposes methods to query the greeting and change it. These methods do nothing but calling get_greeting and set_greeting in the hello-near example.

Querying for the Greeting

The contract performs a cross-contract call to hello.near-example.testnet to get the greeting message, and then handles the response in a callback function.

🦀 Rust (low level)
🦀 Rust (high level)

Callback Function

The callback function processes the result of the cross-contract call. In this case, it simply returns the greeting message obtained from the hello-near contract. Notice that the callback function is marked as private, meaning it can only be called by the contract itself.

Testing the Contract

The contract readily includes a set of unit and sandbox testing to validate its functionality. To execute the tests, run the following commands:

cd contract-simple-rs
cargo test

The integration tests use a sandbox to create NEAR users and simulate interactions with the contract.

In this project in particular, the integration tests first deploy the hello-near contract. Then, they test that the cross-contract call correctly sets and retrieves the message. You will find the integration tests in tests/.

Deploying the Contract to the NEAR network

In order to deploy the contract you will need to create a NEAR account.

Short
Full

# Create a new account pre-funded by a faucet
near create-account <accountId> --useFaucet

# Create a new account pre-funded by a faucet
near account create-account sponsor-by-faucet-service <my-new-dev-account>.testnet autogenerate-new-keypair save-to-keychain network-config testnet create

Go into the directory containing the smart contract (cd contract-simple-rs), build and deploy it:

cargo near deploy build-non-reproducible-wasm <accountId> with-init-call new json-args '{"hello_account":"hello.near-example.testnet"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' network-config testnet sign-with-keychain send

CLI: Interacting with the Contract

To interact with the contract through the console, you can use the following commands:

Short
Full

# Get message from the hello-near contract
# Replace <accountId> with your account ID
near call <accountId> query_greeting --useAccount <accountId>

# Set a new message for the hello-near contract
# Replace <accountId> with your account ID
near call <accountId> change_greeting '{"new_greeting":"XCC Hi"}' --useAccount <accountId>

# Get message from the hello-near contract
# Replace <accountId> with your account ID
near contract call-function as-transaction <accountId> query_greeting json-args '{}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' sign-as <accountId> network-config testnet sign-with-keychain send

# Set a new message for the hello-near contract
# Replace <accountId> with your account ID
near contract call-function as-transaction <accountId> change_greeting json-args '{"new_greeting":"XCC Hi"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' sign-as <accountId> network-config testnet sign-with-keychain send

Moving Forward

A nice way to learn is by trying to expand a contract. Modify the cross contract example to use the guest-book contract!. In this way, you can try to make a cross-contract call that attaches money. Remember to correctly handle the callback, and to return the money to the user in case of error.

Advanced cross-contract calls

Your contract can combine promises to execute several actions sequentially or call several contracts in parallel. The advanced examples live in the same cross-contract-calls repository, under contract-advanced-rs.

Batch actions

You can combine several actions for the same contract into a batch. The actions execute sequentially, and if one fails, they are all reverted. The callback receives the value returned by the final action in the chain:

Call multiple contracts in parallel

A contract can call several contracts in parallel. If one call fails, the other calls are not reverted. The callback receives one result for each promise and must handle successes and failures independently: If every call returns the same type, you can iterate over the promise results directly:

Test and deploy the advanced contract

Run its unit and Sandbox tests locally:

cd contract-advanced-rs
cargo test

Build, deploy, and initialize the contract with the accounts it will call:

cargo near deploy build-non-reproducible-wasm <account-id> with-init-call new json-args '{"hello_account":"hello.near-example.testnet","guestbook_account":"guestbook_account.near-example.testnet","counter_account":"counter_account.near-example.testnet"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' network-config testnet sign-with-keychain send

Call the examples with enough prepaid gas for their child calls and callbacks:

near contract call-function as-transaction <account-id> batch_actions json-args '{}' prepaid-gas '300.0 Tgas' attached-deposit '0 NEAR' sign-as <account-id> network-config testnet sign-with-keychain send

near contract call-function as-transaction <account-id> multiple_contracts json-args '{}' prepaid-gas '300.0 Tgas' attached-deposit '0 NEAR' sign-as <account-id> network-config testnet sign-with-keychain send

near contract call-function as-transaction <account-id> similar_contracts json-args '{}' prepaid-gas '300.0 Tgas' attached-deposit '0 NEAR' sign-as <account-id> network-config testnet sign-with-keychain send

If a call reports Exceeded the prepaid gas, review the gas attached to the child calls and callbacks before increasing the gas on the initiating transaction.

Versioning for this articleAt the time of this writing, this example works with the following versions:

near-cli: 4.0.13
node: 18.19.1
rustc: 1.77.0

Building Smart Contracts

DevKit

Tutorials

Cross Contract Call

Clone the Example

Structure of the Example

Smart Contract

Querying for the Greeting

Callback Function

Testing the Contract

Deploying the Contract to the NEAR network

CLI: Interacting with the Contract

Moving Forward

Advanced cross-contract calls

Batch actions

Call multiple contracts in parallel

Test and deploy the advanced contract

​Clone the Example

​Structure of the Example

​Smart Contract

​Querying for the Greeting

​Callback Function

​Testing the Contract

​Deploying the Contract to the NEAR network

​CLI: Interacting with the Contract

​Moving Forward

​Advanced cross-contract calls

​Batch actions

​Call multiple contracts in parallel

​Test and deploy the advanced contract

Clone the Example

Structure of the Example

Smart Contract

Querying for the Greeting

Callback Function

Testing the Contract

Deploying the Contract to the NEAR network

CLI: Interacting with the Contract

Moving Forward

Advanced cross-contract calls

Batch actions

Call multiple contracts in parallel

Test and deploy the advanced contract