soroban-contracts

A collection of Soroban contract implementations and interface clients.

Safety

This is experimental software and is provided on an "as is" and "as available" basis.

We do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

Usage

Add this to your Cargo.toml:

[dependencies]
soroban-contracts = "<desired version>"

Using a Client

Contract clients are generated from a Rust trait using the soroban-sdk. They can be imported and used as follows:

use stellar_sdk::{BytesN, Env};
use soroban_contracts::token::{TokenClient};

let env = Env::default();
let usdc_address =  BytesN::from_array(&env, &[u8; 0]);
let usdc = TokenClient::new(&env, BytesN::from_array(&env, &usdc_address));

// perform an action against the usdc contract...

For each function defined in the trait like balance, the client contains a standard balance function that obeys the interface and a try_balance that wraps the returned value in a Result to allow the calling contract to gracefully handle errors if required.

Implementing a Trait

Traits can be implemented for a contract through a Rust impl tag and a contractimpl attribute.

use soroban_sdk::{contractimpl};
use soroban_contracts::token::{Token};

pub struct MyContract;

#[contractimpl]
impl Token for MyContract {
    // implement the Token trait based on your contract's needs
}

Deploying a Contact

Implemented contracts expose their optimized WASM bundle. This bundle can be used to deploy to networks or used in tests as shown below:

use soroban_sdk::{testutils::{BytesN as _}, BytesN, Env};
use soroban_contracts::token::{TokenWASM, TokenClient};

let e = Env::default();
let contract_id = BytesN::<32>::random(&e);
e.register_contract_wasm(&contract_id, TokenWASM);
let token_client = TokenClient::new(e, &contract_id);

// perform an action against the newly deployed token contract...

Supported Contracts

This library only supports contracts that have been agreed upon by the community via a SEP or CAP.

Current:

• token - A standardized token defined by CAP-0046-06

If there are any missing contracts - please file an issue.

Acknowledgements

This library was inspired by or directly modified from many sources, primary:

• OpenZeppelin

WASM

The WASM target wasm32-unknown-unknown is supported.

Contributions

Contributions are welcome. Please check out the contribution guide (TODO)!

License

This library is released under the MIT License.