soroban-rs 0.1.0

A collection of helpers for writing tests for Soroban contracts
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# soroban-rs

`soroban-rs` is a Rust library designed to interact with the Soroban smart contract platform on the Stellar network. It provides tools for managing accounts, signing transactions, deploying and invoking smart contracts, and handling cryptographic operations.

## Features

- **Provider**: Connects to the Soroban network using RPC and manages network configurations.
- **Signer**: Handles transaction signing using Ed25519 keys.
- **TransactionBuilder**: Constructs and simulates transactions.
- **Contract**: Manages smart contract deployment and invocation.
- **AccountManager**: Retrieves account details and manages transaction sequences.
- **Crypto Utilities**: Provides cryptographic functions like hashing and salt generation.

## Installation

Add the following to your `Cargo.toml`:

```toml
[dependencies]
soroban-rs = "0.1.0"
```

## Usage

### Example: Deploying and Invoking a Contract

Here's a basic example of how to deploy and invoke a contract using `soroban-rs`:

```rust
use soroban_rs::{
    Contract, Provider, ProviderConfigs, Signer,
    xdr::{ScAddress, ScVal},
};
use std::{env, path::Path};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let private_key =
        env::var("SOROBAN_PRIVATE_KEY").expect("SOROBAN_PRIVATE_KEY must be set");

    let configs = ProviderConfigs {
        rpc_url: "https://soroban-testnet.stellar.org".to_string(),
        network_passphrase: "Test SDF Network ; September 2015".to_string(),
    };
    let provider = Provider::new(configs)?;

    let signer = Signer::new(&private_key)?;
    let contract = Contract::new(
        "path/to/contract.wasm",
    )?;

    // Deploy contract with constructor argument (u32 value of 42)
    let constructor_args = Some(vec![ScVal::U32(42)]);
    let contract_id = contract
        .deploy(&provider, &signer, constructor_args)
        .await?;

    println!("Contract deployed successfully with ID: {:?}", contract_id);

    let alice = ScVal::Address(ScAddress::Account(signer.account_id()));
    let bob = ScVal::Address(ScAddress::Account(signer.account_id()));

    let invoke_res = contract
        .invoke(&contract_id, "send", vec![alice, bob], &provider, &signer)
        .await?;

    println!("Contract invoked successfully with result {:?}", invoke_res);
    Ok(())
}
```

## Error Handling

The library uses a custom error type `SorobanHelperError` to handle various errors such as transaction failures, network request failures, and XDR encoding issues.

## Contributing

We welcome contributions from the community! Here's how you can get involved:

1. [Fork the repository](https://github.com/OpenZeppelin/soroban-helpers/fork)
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

If you are looking for a good place to start, find a good first issue [here](https://github.com/OpenZeppelin/soroban-helpers/issues?q=is%3Aissue%20is%3Aopen%20label%3Agood-first-issue).

You can open an issue for a [bug report](https://github.com/OpenZeppelin/soroban-helpers/issues/new?assignees=&labels=T-bug%2CS-needs-triage&projects=&template=bug.yml), [feature request](https://github.com/OpenZeppelin/soroban-helpers/issues/new?assignees=&labels=T-feature%2CS-needs-triage&projects=&template=feature.yml), or [documentation request](https://github.com/OpenZeppelin/soroban-helpers/issues/new?assignees=&labels=T-documentation%2CS-needs-triage&projects=&template=docs.yml).

You can find more details in our [Contributing](CONTRIBUTING.md) guide.

Please read our [Code of Conduct](CODE_OF_CONDUCT.md) and check the [Security Policy](SECURITY.md) for reporting vulnerabilities.

## License

This project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

## Security

If you discover a security vulnerability within this project, please see [SECURITY.md](SECURITY.md) for instructions on responsible disclosure.

## Maintainers

See [CODEOWNERS](CODEOWNERS) file for the list of project maintainers.