In this example there are two contracts that are compiled separately, and the tests deploy one with the other.
Run the Example
First go through the Setup process to get your development environment configured, then clone themain branch of soroban-examples repository:
deployer/deployer directory, and use cargo test.
Code
deployer/deployer/src/lib.rs
How it Works
Contracts can deploy other contracts using the SDKdeployer() method.
The contract address of the deployed contract is deterministic and is derived from the address of the deployer. The deployment also has to be authorized by the deployer.
Open the deployer/deployer/src/lib.rs file to follow along.
Contract Wasm Upload
Before deploying the new contract instances, the Wasm code needs to be uploaded on-chain. Then it can be used to deploy an arbitrary number of contract instances. The upload should typically happen outside of the deployer contract, as it needs to happen just once. However, it is possible to useenv.deployer().upload_contract_wasm() function to upload Wasm from a contract as well.
See the tests for an example of uploading the contract code programmatically. For the actual on-chain installation see the general deployment tutorial.
Authorization
For introduction to Soroban authorization see the auth tutorial.
deploy function with any arguments, which may not always be desirable (however, there are contracts where it’s perfectly fine to have permissionless deployments).
deployer().with_address() performs authorization as well. However, as we deploy on behalf of the current contract, the call is considered to have been implicitly authorized.
See more details on the actual authorization payloads in tests.
env.deployer()
The env.deployer() SDK function comes with a few deployment-related utilities. Here we use the most generic deployer kind, with_address(env.current_contract_address(), salt).
with_address() accepts the deployer address and salt. Both are used to derive the address of the deployed contract deterministically. It is not possible to re-deploy an already existing contract.
The deploy_contract() function performs the actual deployment using the provided executable, here ContractExecutable::Wasm(wasm_hash). The implementation of the new contract is defined by the Wasm file uploaded under wasm_hash. constructor_args are the arguments that will be passed to the constructor of the contract that is being deployed. If the deployed contract has no constructor, empty argument vector should be passed.
Tests
Open thedeployer/deployer/src/test.rs file to follow along.
Contract to deploy
Start by importing the test contract Wasm to be deployed.deployer/deployer/src/test.rs
deployer/contract/src/lib.rs
Test code
deployer/deployer/src/test.rs
Env, which is the Soroban environment that the contract will run in.
contractimport! and get the hash of the uploaded Wasm code.
deploy function. The contract will deploy the test contract using the hash of its Wasm code and pass a single 5u32 argument to its constructor. We also need the salt to pass into the call in order to generate a unique identifier of the output contract.
deploy function.
deploy_contract function is performed on behalf of the deployer contract and is implicit. This can be verified in the test by examining env.auths().
Build the Contracts
To build the contract into a.wasm file, use the stellar contract build command. Build both the deployer contract and the test contract.
.wasm files should be found in both contract target directories after building both contracts:
Run the Contract
If you havestellar-cli installed, you can invoke the contract function to deploy the test contract.
Before deploying the test contract with the deployer, install the test contract Wasm using the install command. The install command will print out the hash derived from the Wasm file (it’s not just the hash of the Wasm file itself though) which should be used by the deployer.
7792a624b562b3d9414792f5fb5d72f53b9838fef2ed9a901471253970bc3b15.
We also need to deploy the Deployer contract:
CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM.
Then the deployer contract may be invoked with the Wasm hash value above.
- macOS/Linux
- Windows (PowerShell)
- macOS/Linux
- Windows (PowerShell)