From 1dffc11746b317769404970255d77d1f73edc718 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Thu, 10 Nov 2022 20:38:34 -0800 Subject: [PATCH 01/22] Update Examples, SDK and CLI v0.2.1 --- docs/examples/auth-advanced.mdx | 26 +++++++++++++------------- docs/examples/auth.mdx | 12 ++++++------ docs/examples/cross-contract-call.mdx | 10 +++++----- docs/examples/custom-types.mdx | 10 +++++----- docs/examples/deployer.mdx | 10 +++++----- docs/examples/errors.mdx | 14 +++++++------- docs/examples/events.mdx | 10 +++++----- docs/examples/hello-world.mdx | 10 +++++----- docs/examples/liquidity-pool.mdx | 6 +++--- docs/examples/logging.mdx | 10 +++++----- docs/examples/multisig-wallet.mdx | 4 ++-- docs/examples/single-offer-sale.mdx | 6 +++--- docs/examples/storing-data.mdx | 10 +++++----- docs/examples/timelock.mdx | 4 ++-- docs/getting-started/quick-start.mdx | 6 +++--- docs/getting-started/setup.mdx | 7 ++++--- docs/sdks/rust-auth.mdx | 8 ++++---- docs/sdks/rust.mdx | 4 ++-- docs/tutorials/create-a-project.mdx | 10 +++++----- 19 files changed, 89 insertions(+), 88 deletions(-) diff --git a/docs/examples/auth-advanced.mdx b/docs/examples/auth-advanced.mdx index 786f0b92..35f88448 100644 --- a/docs/examples/auth-advanced.mdx +++ b/docs/examples/auth-advanced.mdx @@ -7,7 +7,7 @@ The [advanced auth example] demonstrates how to write a contract that supports multiple forms of authentication using the [soroban-auth] crate. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 The example supports authentication by: - Being the invoker, as a transaction source account or a contract. @@ -60,17 +60,17 @@ is appropriate for themselves. [soroban-auth]: ../SDKs/rust-auth [auth example]: auth.mdx -[advanced auth example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/auth_advanced +[advanced auth example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/auth_advanced ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -105,12 +105,12 @@ The example uses the Soroban auth SDK, and has the following dependencies in its ```toml title="authorization/src/Cargo.toml [dependencies] -soroban-sdk = "0.1.0" -soroban-auth = "0.1.0" +soroban-sdk = "0.2.1" +soroban-auth = "0.2.1" [dev_dependencies] -soroban-sdk = { version = "0.1.0", features = ["testutils"] } -soroban-auth = { version = "0.1.0", features = ["testutils"] } +soroban-sdk = { version = "0.2.1", features = ["testutils"] } +soroban-auth = { version = "0.2.1", features = ["testutils"] } ``` ## Code @@ -173,13 +173,13 @@ fn verify_and_consume_nonce(env: &Env, sig: &Signature, nonce: &BigInt) { match sig { Signature::Invoker => { if BigInt::zero(env) != nonce { - panic_error!(env, Error::IncorrectNonceForInvoker); + panic_with_error!(env, Error::IncorrectNonceForInvoker); } } Signature::Ed25519(_) | Signature::Account(_) => { let id = sig.identifier(env); if nonce != &get_nonce(env, &id) { - panic_error!(env, Error::IncorrectNonce); + panic_with_error!(env, Error::IncorrectNonce); } set_nonce(env, &id, nonce + 1); } @@ -200,7 +200,7 @@ fn set_nonce(env: &Env, id: &Identifier, nonce: BigInt) { } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/auth_advanced +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/auth_advanced ## How it Works @@ -421,13 +421,13 @@ fn verify_and_consume_nonce(env: &Env, sig: &Signature, nonce: &BigInt) { match sig { Signature::Invoker => { if BigInt::zero(env) != nonce { - panic_error!(env, Error::IncorrectNonceForInvoker); + panic_with_error!(env, Error::IncorrectNonceForInvoker); } } Signature::Ed25519(_) | Signature::Account(_) => { let id = sig.identifier(env); if nonce != &get_nonce(env, &id) { - panic_error!(env, Error::IncorrectNonce); + panic_with_error!(env, Error::IncorrectNonce); } set_nonce(env, &id, nonce + 1); } diff --git a/docs/examples/auth.mdx b/docs/examples/auth.mdx index 8450e758..9ea0c11a 100644 --- a/docs/examples/auth.mdx +++ b/docs/examples/auth.mdx @@ -8,9 +8,9 @@ verify that a contract has been invoked by an account or contract. This example is an extension of the [storing data example]. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 -[events example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/events +[events example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/events [storing data example]: storing-data.mdx The participant who invoked a contract is an `Address` containing one-of a: @@ -26,18 +26,18 @@ invocations, or ed25519 keys independent of accounts and contracts, see the [advanced auth example]. ::: -[auth example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/auth +[auth example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/auth [advanced auth example]: auth-advanced.mdx ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -95,7 +95,7 @@ impl IncrementContract { } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/auth +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/auth ## How it Works diff --git a/docs/examples/cross-contract-call.mdx b/docs/examples/cross-contract-call.mdx index 2497a69d..44742726 100644 --- a/docs/examples/cross-contract-call.mdx +++ b/docs/examples/cross-contract-call.mdx @@ -7,7 +7,7 @@ The [cross contract call example] demonstrates how to call a contract from another contract. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 :::info In this example there are two contracts that are compiled separately, deployed @@ -17,17 +17,17 @@ tooling is still building out the tools to support these workflows. Feedback appreciated [here](https://github.com/stellar/rs-soroban-sdk/issues/new/choose). ::: -[cross contract call example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/cross_contract_calls +[cross contract call example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/cross_contract_calls ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -76,7 +76,7 @@ impl ContractB { } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/cross_contract +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/cross_contract ## How it Works diff --git a/docs/examples/custom-types.mdx b/docs/examples/custom-types.mdx index d24581e4..ab3f3b39 100644 --- a/docs/examples/custom-types.mdx +++ b/docs/examples/custom-types.mdx @@ -8,20 +8,20 @@ that can be stored on the ledger, or used as inputs and outputs to contract invocations. This example is an extension of the [storing data example]. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 -[custom types example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/custom_types +[custom types example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/custom_types [storing data example]: storing-data.mdx ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -73,7 +73,7 @@ impl IncrementContract { } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/custom_types +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/custom_types ## How it Works diff --git a/docs/examples/deployer.mdx b/docs/examples/deployer.mdx index 0c8aaa01..1bdaa973 100644 --- a/docs/examples/deployer.mdx +++ b/docs/examples/deployer.mdx @@ -6,24 +6,24 @@ title: Deployer The [deployer example] demonstrates how to deploy contracts using a contract. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 :::info In this example there are two contracts that are compiled separately, and the tests deploy one with the other. ::: -[deployer example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/deployer +[deployer example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/deployer ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -65,7 +65,7 @@ impl Deployer { } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/deployer +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/deployer ## How it Works diff --git a/docs/examples/errors.mdx b/docs/examples/errors.mdx index 078ee7d8..78682736 100644 --- a/docs/examples/errors.mdx +++ b/docs/examples/errors.mdx @@ -8,20 +8,20 @@ contract that invokers of the contract can understand and handle. This example is an extension of the [storing data example]. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 -[errors example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/errors +[errors example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/errors [storing data example]: storing-data.mdx ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -96,7 +96,7 @@ impl IncrementContract { } } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/errors +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/errors ## How it Works @@ -156,7 +156,7 @@ pub fn increment(env: Env) -> Result { Errors can also be panicked instead of being returned from the function. The increment function could also be written as follows with a `u32` return -value. The error can be passed to the environment using the `panic_error!` +value. The error can be passed to the environment using the `panic_with_error!` macro. ```rust @@ -167,7 +167,7 @@ pub fn increment(env: Env) -> u32 { count } else { // ... - panic_error!(&env, Error::LimitReached) + panic_with_error!(&env, Error::LimitReached) } } ``` diff --git a/docs/examples/events.mdx b/docs/examples/events.mdx index 9a101783..af9dd0a7 100644 --- a/docs/examples/events.mdx +++ b/docs/examples/events.mdx @@ -7,20 +7,20 @@ The [events example] demonstrates how to publish events from a contract. This example is an extension of the [storing data example]. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 -[events example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/events +[events example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/events [storing data example]: storing-data.mdx ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -61,7 +61,7 @@ impl IncrementContract { } } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/events +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/events ## How it Works diff --git a/docs/examples/hello-world.mdx b/docs/examples/hello-world.mdx index fce8c2c1..f609ee43 100644 --- a/docs/examples/hello-world.mdx +++ b/docs/examples/hello-world.mdx @@ -7,19 +7,19 @@ The [hello world example] demonstrates how to write a simple contract, with a single function that takes one input and returns it as an output. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 -[hello world example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/hello_world +[hello world example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/hello_world ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -53,7 +53,7 @@ impl HelloContract { } } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/hello_world +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/hello_world ## How it Works diff --git a/docs/examples/liquidity-pool.mdx b/docs/examples/liquidity-pool.mdx index 7958cc9a..12695f34 100644 --- a/docs/examples/liquidity-pool.mdx +++ b/docs/examples/liquidity-pool.mdx @@ -8,7 +8,7 @@ liquidity pool contract. The comments in the [source code] explain how the contr be used. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 -[liquidity pool example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/liquidity_pool -[source code]: https://github.com/stellar/soroban-examples/blob/v0.1.0/liquidity_pool/src/lib.rs#L143 +[liquidity pool example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/liquidity_pool +[source code]: https://github.com/stellar/soroban-examples/blob/v0.2.1/liquidity_pool/src/lib.rs#L143 diff --git a/docs/examples/logging.mdx b/docs/examples/logging.mdx index cbdc3f48..c2f40d79 100644 --- a/docs/examples/logging.mdx +++ b/docs/examples/logging.mdx @@ -6,13 +6,13 @@ title: Logging The [logging example] demonstrates how to log for the purpose of debugging. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 Logs in contracts are only visible in tests, or when executing contracts using [`soroban-cli`]. Logs are only compiled into the contract if the `debug-assertions` Rust compiler option is enabled. -[logging example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/hello_world +[logging example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/hello_world :::tip Logs are no a substitute for step-through debugging. Rust tests for Soroban can @@ -31,12 +31,12 @@ example] for how to produce structured events. ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -78,7 +78,7 @@ impl Contract { } } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/logging +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/logging ## How it Works diff --git a/docs/examples/multisig-wallet.mdx b/docs/examples/multisig-wallet.mdx index 7f1baaaf..0d72656b 100644 --- a/docs/examples/multisig-wallet.mdx +++ b/docs/examples/multisig-wallet.mdx @@ -7,12 +7,12 @@ The [multisig wallet example] demonstrates a complex auth scheme with multiple signers that authorizes payments either immediately or in a delayed async fashion. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 :::tip Stellar supports [multisig accounts] natively, and multisig accounts may be simpler to manage than a contract driven multisig wallet. ::: -[multisig wallet example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/wallet +[multisig wallet example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/wallet [multisig accounts]: https://developers.stellar.org/docs/encyclopedia/signatures-multisig diff --git a/docs/examples/single-offer-sale.mdx b/docs/examples/single-offer-sale.mdx index 1adaca37..769770b4 100644 --- a/docs/examples/single-offer-sale.mdx +++ b/docs/examples/single-offer-sale.mdx @@ -8,7 +8,7 @@ a seller to set up an offer to sell token A for token B. The comments in the [source code] explain how the contract should be used. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 -[single offer sale example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/single_offer -[source code]: https://github.com/stellar/soroban-examples/blob/v0.1.0/single_offer/src/lib.rs#L131 +[single offer sale example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/single_offer +[source code]: https://github.com/stellar/soroban-examples/blob/v0.2.1/single_offer/src/lib.rs#L131 diff --git a/docs/examples/storing-data.mdx b/docs/examples/storing-data.mdx index e402a207..1fbb6762 100644 --- a/docs/examples/storing-data.mdx +++ b/docs/examples/storing-data.mdx @@ -8,19 +8,19 @@ data, with a single function that increments an internal counter and returns the value. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 -[increment example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/increment +[increment example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/increment ## Run the Example First go through the [Setup] process to get your development environment -configured, then clone the `v0.1.1` tag of `soroban-examples` repository: +configured, then clone the `v0.2.1` tag of `soroban-examples` repository: [Setup]: ../getting-started/setup.mdx ``` -git clone -b v0.1.1 https://github.com/stellar/soroban-examples +git clone -b v0.2.1 https://github.com/stellar/soroban-examples ``` Or, skip the development environment setup and open this example in [Gitpod][oigp]. @@ -64,7 +64,7 @@ impl IncrementContract { } } ``` -Ref: https://github.com/stellar/soroban-examples/tree/v0.1.1/increment +Ref: https://github.com/stellar/soroban-examples/tree/v0.2.1/increment ## How it Works diff --git a/docs/examples/timelock.mdx b/docs/examples/timelock.mdx index 7ae2bf5c..16fef0c2 100644 --- a/docs/examples/timelock.mdx +++ b/docs/examples/timelock.mdx @@ -8,10 +8,10 @@ greatly simplified claimable balance similar to the [claimable balance] feature available on Stellar. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] -[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.1.1 +[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.2.1 The contract accepts deposits of an amount of a token, and allows other accounts to claim it before or after a time point. -[timelock example]: https://github.com/stellar/soroban-examples/tree/v0.1.1/timelock +[timelock example]: https://github.com/stellar/soroban-examples/tree/v0.2.1/timelock [claimable balance]: https://developers.stellar.org/docs/glossary/claimable-balance diff --git a/docs/getting-started/quick-start.mdx b/docs/getting-started/quick-start.mdx index 6adda801..39d40172 100644 --- a/docs/getting-started/quick-start.mdx +++ b/docs/getting-started/quick-start.mdx @@ -21,7 +21,7 @@ Open the `Cargo.toml`, it should look something like this: ```toml title="Cargo.toml" [package] name = "first-project" -version = "0.1.0" +version = "0.2.1" edition = "2021" ``` @@ -42,10 +42,10 @@ crate-type = ["cdylib"] testutils = ["soroban-sdk/testutils"] [dependencies] -soroban-sdk = "0.1.0" +soroban-sdk = "0.2.1" [dev_dependencies] -soroban-sdk = { version = "0.1.0", features = ["testutils"] } +soroban-sdk = { version = "0.2.1", features = ["testutils"] } [profile.release] opt-level = "z" diff --git a/docs/getting-started/setup.mdx b/docs/getting-started/setup.mdx index dc6697f3..e8353dc3 100644 --- a/docs/getting-started/setup.mdx +++ b/docs/getting-started/setup.mdx @@ -54,7 +54,7 @@ contract will execute on network, however in a local sandbox. Install the Soroban CLI using `cargo install`. ```sh -cargo install --locked --version 0.1.2 soroban-cli +cargo install --locked --version 0.2.1 soroban-cli ``` :::info @@ -71,8 +71,8 @@ soroban ``` ``` -❯ soroban -h -soroban 0.1.2 +❯ soroban +soroban 0.2.1 https://soroban.stellar.org USAGE: @@ -84,6 +84,7 @@ OPTIONS: SUBCOMMANDS: invoke Invoke a contract function in a WASM file inspect Inspect a WASM file listing contract functions, meta, etc + optimize Optimize a WASM file read Print the current value of a contract-data ledger entry serve Run a local webserver for web app development and testing token Wrap, create, and manage token contracts diff --git a/docs/sdks/rust-auth.mdx b/docs/sdks/rust-auth.mdx index 9b2f79a5..4671ed12 100644 --- a/docs/sdks/rust-auth.mdx +++ b/docs/sdks/rust-auth.mdx @@ -59,10 +59,10 @@ Add the following sections to the `Cargo.toml` to import `soroban-auth`. testutils = ["soroban-auth/testutils"] [dependencies] -soroban-sdk = "0.1.0" -soroban-auth = "0.1.0" +soroban-sdk = "0.2.1" +soroban-auth = "0.2.1" [dev_dependencies] -soroban-sdk = { version = "0.1.0", features = ["testutils"] } -soroban-auth = { version = "0.1.0", features = ["testutils"] } +soroban-sdk = { version = "0.2.1", features = ["testutils"] } +soroban-auth = { version = "0.2.1", features = ["testutils"] } ``` diff --git a/docs/sdks/rust.mdx b/docs/sdks/rust.mdx index 1870fc96..d8bf0cd9 100644 --- a/docs/sdks/rust.mdx +++ b/docs/sdks/rust.mdx @@ -29,8 +29,8 @@ Add the following sections to the `Cargo.toml` to import the `soroban-sdk`. testutils = ["soroban-sdk/testutils"] [dependencies] -soroban-sdk = "0.1.0" +soroban-sdk = "0.2.1" [dev_dependencies] -soroban-sdk = { version = "0.1.0", features = ["testutils"] } +soroban-sdk = { version = "0.2.1", features = ["testutils"] } ``` diff --git a/docs/tutorials/create-a-project.mdx b/docs/tutorials/create-a-project.mdx index 052fce36..995e4bc2 100644 --- a/docs/tutorials/create-a-project.mdx +++ b/docs/tutorials/create-a-project.mdx @@ -19,7 +19,7 @@ Open the `Cargo.toml`, it should look something like this: ```toml title="Cargo.toml" [package] name = "project-name" -version = "0.1.0" +version = "0.2.1" edition = "2021" ``` @@ -44,10 +44,10 @@ The `soroban-sdk` is in early development. Report issues ```toml [dependencies] -soroban-sdk = "0.1.0" +soroban-sdk = "0.2.1" [dev_dependencies] -soroban-sdk = { version = "0.1.0", features = ["testutils"] } +soroban-sdk = { version = "0.2.1", features = ["testutils"] } [features] testutils = ["soroban-sdk/testutils"] @@ -117,10 +117,10 @@ crate-type = ["cdylib"] testutils = ["soroban-sdk/testutils"] [dependencies] -soroban-sdk = "0.1.0" +soroban-sdk = "0.2.1" [dev_dependencies] -soroban-sdk = { version = "0.1.0", features = ["testutils"] } +soroban-sdk = { version = "0.2.1", features = ["testutils"] } [profile.release] opt-level = "z" From c9928a22b41edc31617bfebe3e13ba1f56895870 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Thu, 10 Nov 2022 21:00:59 -0800 Subject: [PATCH 02/22] Pin docker image --- docs/tutorials/deploy-to-futurenet.mdx | 2 +- docs/tutorials/deploy-to-local-network.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/deploy-to-futurenet.mdx b/docs/tutorials/deploy-to-futurenet.mdx index 274d0a4d..ff4d4a79 100644 --- a/docs/tutorials/deploy-to-futurenet.mdx +++ b/docs/tutorials/deploy-to-futurenet.mdx @@ -22,7 +22,7 @@ docker run --rm -it \ --platform linux/amd64 \ -p 8000:8000 \ --name stellar \ - stellar/quickstart:soroban-dev \ + stellar/quickstart:soroban-dev@sha256:0993d3350148af6ffeab5dc8f0b835236b28dade6dcae77ff8a09317162f768d \ --futurenet \ --enable-soroban-rpc ``` diff --git a/docs/tutorials/deploy-to-local-network.mdx b/docs/tutorials/deploy-to-local-network.mdx index e64441a8..58e39b5f 100644 --- a/docs/tutorials/deploy-to-local-network.mdx +++ b/docs/tutorials/deploy-to-local-network.mdx @@ -29,7 +29,7 @@ docker run --rm -it \ --platform linux/amd64 \ -p 8000:8000 \ --name stellar \ - stellar/quickstart:soroban-dev \ + stellar/quickstart:soroban-dev@sha256:0993d3350148af6ffeab5dc8f0b835236b28dade6dcae77ff8a09317162f768d \ --standalone \ --enable-soroban-rpc ``` From a2c8c1e264e7ff8ad984ac214c536894fe725104 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Fri, 2 Dec 2022 12:44:41 -0800 Subject: [PATCH 03/22] Add release notes (#234) --- docs/index.mdx | 2 +- docs/releases.mdx | 156 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 docs/releases.mdx diff --git a/docs/index.mdx b/docs/index.mdx index 2c7b365f..8e331af5 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -11,7 +11,7 @@ Soroban is a pre-release. Breaking changes may occur. While it works well with Stellar, a blockchain that shares its values of scale and sensibility, it doesn't depend on or require Stellar at all, and can be used by any transaction processor, including other blockchains, L2s, and permissioned ledgers. -Currently, Soroban is a preview release that includes initial versions of the smart contracts environment, a Rust SDK, A CLI, and an RPC server. Developers can write and test contracts on their local machine or deploy them to a special test network dubbed FutureNet. +Currently, Soroban is a preview release that includes initial versions of the smart contracts environment, a Rust SDK, A CLI, and an RPC server. Developers can write and test contracts on their local machine or deploy them to a special test network dubbed Futurenet. ## What "preview release" means We’re releasing this very early version of Soroban because we believe it’s important to share the development process, and we want Stellar ecosystem developers and smart contract developers from other ecosystems to have a chance to experiment and provide feedback. diff --git a/docs/releases.mdx b/docs/releases.mdx new file mode 100644 index 00000000..bbdea132 --- /dev/null +++ b/docs/releases.mdx @@ -0,0 +1,156 @@ +--- +sidebar_position: 1 +title: Preview Releases +--- + +The following Soroban releases are preview releases. + +We’re releasing early versions of Soroban because we believe it’s important to +share the development process, and we want Stellar ecosystem developers and +smart contract developers from other ecosystems to have a chance to experiment +and provide feedback. + +:::caution +Preview releases are software releases that are also released to the [Futurenet] +test network. Software releases may occur between Futurenet releases. If you're +interacting with Futurenet the recommended software versions to use in +development are below. Releases to Futurenet may include network resets and +network passphrase changes. +::: + +[Futurenet]: networks/futurenet + +## Preview 5 (December 6th, 2022) + +### Software + +| Software | Version | +| -------- | ------- | +| XDR | https://github.com/stellar/stellar-xdr/tree/026c9cd074bdb28ddde8ee52f2a4502d9e518a09 | +| Soroban Environment | `v0.0.10` | +| Stellar Core | `stellar-core_19.5.1-1137.b3a6bc281.focal~soroban` | +| Soroban Rust SDK | `` | +| Soroban CLI | `` | +| Soroban RPC | `` | +| Stellar Horizon | `stellar-horizon:2.22.0~soroban-318` | +| Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:...` | +| Futurenet Network Passphrase | `Test SDF Future Network ; October 2022` | + +### Changelog + +#### XDR + +* ... + +#### Soroban Environment + +* ... + +See https://github.com/stellar/rs-soroban-env/releases v... for more details. + +#### Soroban Rust SDK + +* ... + +See https://github.com/stellar/rs-soroban-sdk/releases v... for more details. + +#### Soroban RPC + +* ... + +See https://github.com/stellar/soroban-tools/releases v... for more details. + +#### Soroban CLI + +* ... + +See https://github.com/stellar/soroban-tools/releases v... for more details. + +## Preview 4 (November 15th, 2022) + +### Software + +| Software | Version | +| -------- | ------- | +| XDR | https://github.com/stellar/stellar-xdr-next/tree/48d5e17ae63bba0aa9725cd9d18d7438f44c07b1 | +| Soroban Environment | `v0.0.9` | +| Stellar Core | `19.5.1-1111.eba1d3de9.focal~soroban` | +| Soroban Rust SDK | `v0.2.1` | +| Soroban CLI | `v0.2.1` | +| Soroban RPC | ??? | +| Stellar Horizon | `2.22.0~soroban-304` | +| Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:0993d3350148af6ffeab5dc8f0b835236b28dade6dcae77ff8a09317162f768d` | +| Futurenet Network Passphrase | `Test SDF Future Network ; October 2022` | + +### Changelog + +#### XDR + +* Trivial whitespace changes + +#### Soroban Environment + +* Vm tuning +* Add token events +* Catch panics from native contracts in try_call +* Improved built-in token error reporting +* Add missing conversion from Status->ScStatus for the ContractError variant +* Capture user panic-strings in native builds, avoid spurious NoContractRunning error +* Few small fixes to error debug events + +See https://github.com/stellar/rs-soroban-env/releases v0.0.7, v0.0.8, v0.0.9 for more details. + +#### Soroban Rust SDK + +* Add Logger::print in testutils +* Add conversion from Address to Identifier +* Remove deprecated functions +* Remove panic-catching and fix tests that use newly-working native try_call +* Reintroduce an optimized aborting unwrap +* Add assert_with_error! macro +* Rename panic_error! to panic_with_error! + +See https://github.com/stellar/rs-soroban-sdk/releases v0.2.0, v0.2.1 for more details. + +#### Soroban RPC + +* Initial Release + +#### Soroban CLI + +* Strings and symbols are rendered as text in JSON output +* Bytes are rendered as hex in JSON output +* Accounts in invocations are created in sandbox +* Add optimize sub-command that optimizes contracts +* Fix the bin name in the completion command +* Fix jsonrpc compliance issue + +See https://github.com/stellar/soroban-cli/releases v0.2.0, v0.2.1 for more details. + +## Preview 3 (October 11th, 2022) + +### Software + +| Software | Version | +| -------- | ------- | +| XDR | https://github.com/stellar/stellar-xdr-next/tree/161e2e5b64425a49f9ccfef7f732ae742ed5eec4 | +| Soroban Environment | `v0.0.6` | +| Stellar Core | `19.4.1-1097.4e813f20e.focal~soroban` | +| Soroban Rust SDK | `v0.1.1` | +| Soroban CLI | `v0.1.2` | +| Soroban RPC | ??? | +| Stellar Horizon | `2.22.0~soroban-304` | +| Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:e58d83f92a61f43406087f488dd1cba110a92646dca85f14b3a416163609e853` | +| Futurenet Network Passphrase | `Test SDF Future Network ; October 2022` | + +### Changelog + +See https://www.stellar.org/blog/soroban-a-new-smart-contract-standard. + +## Preview 2 (September 13th, 2022) + +See https://www.stellar.org/developers-blog/soroban-preview-release-2. + +## Preview 1 (August 1st, 2022) + +See https://www.stellar.org/blog/project-jump-cannon-soroban-preview-release. From 88d2c4ae4f026113f68dd9cf252bce8d3ca5f4b8 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Fri, 2 Dec 2022 16:50:09 -0800 Subject: [PATCH 04/22] Update version of SDK (#236) --- docs/examples/auth-advanced.mdx | 8 ++++---- docs/getting-started/quick-start.mdx | 6 +++--- docs/releases.mdx | 2 +- docs/sdks/rust-auth.mdx | 8 ++++---- docs/sdks/rust.mdx | 4 ++-- docs/tutorials/create-a-project.mdx | 10 +++++----- 6 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/examples/auth-advanced.mdx b/docs/examples/auth-advanced.mdx index 42487ecb..3b558125 100644 --- a/docs/examples/auth-advanced.mdx +++ b/docs/examples/auth-advanced.mdx @@ -105,12 +105,12 @@ The example uses the Soroban auth SDK, and has the following dependencies in its ```toml title="authorization/src/Cargo.toml [dependencies] -soroban-sdk = "0.2.1" -soroban-auth = "0.2.1" +soroban-sdk = "0.3.1" +soroban-auth = "0.3.1" [dev_dependencies] -soroban-sdk = { version = "0.2.1", features = ["testutils"] } -soroban-auth = { version = "0.2.1", features = ["testutils"] } +soroban-sdk = { version = "0.3.1", features = ["testutils"] } +soroban-auth = { version = "0.3.1", features = ["testutils"] } ``` ## Code diff --git a/docs/getting-started/quick-start.mdx b/docs/getting-started/quick-start.mdx index 39d40172..735d3e66 100644 --- a/docs/getting-started/quick-start.mdx +++ b/docs/getting-started/quick-start.mdx @@ -21,7 +21,7 @@ Open the `Cargo.toml`, it should look something like this: ```toml title="Cargo.toml" [package] name = "first-project" -version = "0.2.1" +version = "0.1.0" edition = "2021" ``` @@ -42,10 +42,10 @@ crate-type = ["cdylib"] testutils = ["soroban-sdk/testutils"] [dependencies] -soroban-sdk = "0.2.1" +soroban-sdk = "0.3.1" [dev_dependencies] -soroban-sdk = { version = "0.2.1", features = ["testutils"] } +soroban-sdk = { version = "0.3.1", features = ["testutils"] } [profile.release] opt-level = "z" diff --git a/docs/releases.mdx b/docs/releases.mdx index bbdea132..ea88384b 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -29,7 +29,7 @@ network passphrase changes. | XDR | https://github.com/stellar/stellar-xdr/tree/026c9cd074bdb28ddde8ee52f2a4502d9e518a09 | | Soroban Environment | `v0.0.10` | | Stellar Core | `stellar-core_19.5.1-1137.b3a6bc281.focal~soroban` | -| Soroban Rust SDK | `` | +| Soroban Rust SDK | `v0.3.1` | | Soroban CLI | `` | | Soroban RPC | `` | | Stellar Horizon | `stellar-horizon:2.22.0~soroban-318` | diff --git a/docs/sdks/rust-auth.mdx b/docs/sdks/rust-auth.mdx index 4671ed12..4f70e071 100644 --- a/docs/sdks/rust-auth.mdx +++ b/docs/sdks/rust-auth.mdx @@ -59,10 +59,10 @@ Add the following sections to the `Cargo.toml` to import `soroban-auth`. testutils = ["soroban-auth/testutils"] [dependencies] -soroban-sdk = "0.2.1" -soroban-auth = "0.2.1" +soroban-sdk = "0.3.1" +soroban-auth = "0.3.1" [dev_dependencies] -soroban-sdk = { version = "0.2.1", features = ["testutils"] } -soroban-auth = { version = "0.2.1", features = ["testutils"] } +soroban-sdk = { version = "0.3.1", features = ["testutils"] } +soroban-auth = { version = "0.3.1", features = ["testutils"] } ``` diff --git a/docs/sdks/rust.mdx b/docs/sdks/rust.mdx index d8bf0cd9..a086c32b 100644 --- a/docs/sdks/rust.mdx +++ b/docs/sdks/rust.mdx @@ -29,8 +29,8 @@ Add the following sections to the `Cargo.toml` to import the `soroban-sdk`. testutils = ["soroban-sdk/testutils"] [dependencies] -soroban-sdk = "0.2.1" +soroban-sdk = "0.3.1" [dev_dependencies] -soroban-sdk = { version = "0.2.1", features = ["testutils"] } +soroban-sdk = { version = "0.3.1", features = ["testutils"] } ``` diff --git a/docs/tutorials/create-a-project.mdx b/docs/tutorials/create-a-project.mdx index 995e4bc2..6068a88c 100644 --- a/docs/tutorials/create-a-project.mdx +++ b/docs/tutorials/create-a-project.mdx @@ -19,7 +19,7 @@ Open the `Cargo.toml`, it should look something like this: ```toml title="Cargo.toml" [package] name = "project-name" -version = "0.2.1" +version = "0.1.0" edition = "2021" ``` @@ -44,10 +44,10 @@ The `soroban-sdk` is in early development. Report issues ```toml [dependencies] -soroban-sdk = "0.2.1" +soroban-sdk = "0.3.1" [dev_dependencies] -soroban-sdk = { version = "0.2.1", features = ["testutils"] } +soroban-sdk = { version = "0.3.1", features = ["testutils"] } [features] testutils = ["soroban-sdk/testutils"] @@ -117,10 +117,10 @@ crate-type = ["cdylib"] testutils = ["soroban-sdk/testutils"] [dependencies] -soroban-sdk = "0.2.1" +soroban-sdk = "0.3.1" [dev_dependencies] -soroban-sdk = { version = "0.2.1", features = ["testutils"] } +soroban-sdk = { version = "0.3.1", features = ["testutils"] } [profile.release] opt-level = "z" From 52c7ba4f0ec73f1210bfafae4d168aad7c65dd86 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Fri, 2 Dec 2022 17:06:40 -0800 Subject: [PATCH 05/22] Remove BigInt and replace with i128 (#237) --- docs/built-in-contracts/token.mdx | 36 +++++++++++----------- docs/common-interfaces/token.mdx | 32 +++++++++---------- docs/examples/auth-advanced.mdx | 48 +++++++++++++---------------- docs/examples/hello-world.mdx | 4 +-- docs/learn/built-in-types.mdx | 12 +++----- docs/sdks/byo.mdx | 2 -- docs/tutorials/write-a-contract.mdx | 4 +-- 7 files changed, 63 insertions(+), 75 deletions(-) diff --git a/docs/built-in-contracts/token.mdx b/docs/built-in-contracts/token.mdx index a5603318..d5949738 100644 --- a/docs/built-in-contracts/token.mdx +++ b/docs/built-in-contracts/token.mdx @@ -87,9 +87,9 @@ token.with_source_account(&token_admin_id).mint( // `token_admin_id` in this case. &Signature::Invoker, // Nonce is always 0 for invokers. - &BigInt::zero(&env), + &0, &user_id, - &BigInt::from_u32(&env, 1000), + &1000, ); ``` @@ -117,14 +117,14 @@ let sig = soroban_auth::testutils::ed25519::sign( // Arguments of the contract function call. // Notice that instead of the signature (first `mint` argument), public key // is used as the first argument here. - (&token_admin_id, &nonce, &user_id, &BigInt::from_u32(&env, 1000)), + (&token_admin_id, &nonce, &user_id, &1000), ); // Call the contract with signature we computed above. token.mint( &sig, &nonce, &user_id, - &BigInt::from_u32(&env, 1000), + &1000, ); ``` @@ -172,60 +172,60 @@ fn init(env: Env, admin: Identifier, metadata: TokenMetadata); // user. // `id` must be a classic Stellar account (i.e. an account invoker or signature // signed by an account). -fn import(env: Env, id: Signature, nonce: BigInt, amount: i64); +fn import(env: Env, id: Signature, nonce: i128, amount: i64); // Moves the `amount` from token balance to the classic asset balance of `id` // user. // `id` must be a classic Stellar account (i.e. an account invoker or signature // signed by an account). -fn export(env: Env, id: Signature, nonce: BigInt, amount: i64); +fn export(env: Env, id: Signature, nonce: i128, amount: i64); // Admin interface -- these functions are privileged // If "admin" is the administrator, burn "amount" from "from" -fn burn(e: Env, admin: Signature, nonce: BigInt, from: Identifier, amount: BigInt); +fn burn(e: Env, admin: Signature, nonce: i128, from: Identifier, amount: i128); // If "admin" is the administrator, mint "amount" to "to" -fn mint(e: Env, admin: Signature, nonce: BigInt, to: Identifier, amount: BigInt); +fn mint(e: Env, admin: Signature, nonce: i128, to: Identifier, amount: i128); // If "admin" is the administrator, set the administrator to "id" -fn set_admin(e: Env, admin: Signature, nonce: BigInt, new_admin: Identifier); +fn set_admin(e: Env, admin: Signature, nonce: i128, new_admin: Identifier); // If "admin" is the administrator, freeze "id" -fn freeze(e: Env, admin: Signature, nonce: BigInt, id: Identifier); +fn freeze(e: Env, admin: Signature, nonce: i128, id: Identifier); // If "admin" is the administrator, unfreeze "id" -fn unfreeze(e: Env, admin: Signature, nonce: BigInt, id: Identifier); +fn unfreeze(e: Env, admin: Signature, nonce: i128, id: Identifier); // Token Interface // Get the allowance for "spender" to transfer from "from" -fn allowance(e: Env, from: Identifier, spender: Identifier) -> BigInt; +fn allowance(e: Env, from: Identifier, spender: Identifier) -> i128; // Set the allowance to "amount" for "spender" to transfer from "from" -fn approve(e: Env, from: Signature, nonce: BigInt, spender: Identifier, amount: BigInt); +fn approve(e: Env, from: Signature, nonce: i128, spender: Identifier, amount: i128); // Get the balance of "id" -fn balance(e: Env, id: Identifier) -> BigInt; +fn balance(e: Env, id: Identifier) -> i128; // Transfer "amount" from "from" to "to" -fn xfer(e: Env, from: Signature, nonce: BigInt, to: Identifier, amount: BigInt); +fn xfer(e: Env, from: Signature, nonce: i128, to: Identifier, amount: i128); // Transfer "amount" from "from" to "to", consuming the allowance of "spender" fn xfer_from( e: Env, spender: Signature, - nonce: BigInt, + nonce: i128, from: Identifier, to: Identifier, - amount: BigInt, + amount: i128, ); // Returns true if "id" is frozen fn is_frozen(e: Env, id: Identifier) -> bool; // Returns the current nonce for "id" -fn nonce(e: Env, id: Identifier) -> BigInt; +fn nonce(e: Env, id: Identifier) -> i128; // Descriptive Interface diff --git a/docs/common-interfaces/token.mdx b/docs/common-interfaces/token.mdx index 21db6198..0aad4e3b 100644 --- a/docs/common-interfaces/token.mdx +++ b/docs/common-interfaces/token.mdx @@ -23,25 +23,25 @@ pub trait Contract { fn burn( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::BigInt, + nonce: soroban_sdk::i128, from: soroban_auth::Identifier, - amount: soroban_sdk::BigInt, + amount: soroban_sdk::i128, ); /// If "admin" is the administrator, mint "amount" to "to". fn mint( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::BigInt, + nonce: soroban_sdk::i128, to: soroban_auth::Identifier, - amount: soroban_sdk::BigInt, + amount: soroban_sdk::i128, ); /// If "admin" is the administrator, set the administrator to "id". fn set_admin( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::BigInt, + nonce: soroban_sdk::i128, new_admin: soroban_auth::Identifier, ); @@ -49,7 +49,7 @@ pub trait Contract { fn freeze( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::BigInt, + nonce: soroban_sdk::i128, id: soroban_auth::Identifier, ); @@ -57,7 +57,7 @@ pub trait Contract { fn unfreeze( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::BigInt, + nonce: soroban_sdk::i128, id: soroban_auth::Identifier, ); @@ -70,44 +70,44 @@ pub trait Contract { env: soroban_sdk::Env, from: soroban_auth::Identifier, spender: soroban_auth::Identifier, - ) -> soroban_sdk::BigInt; + ) -> soroban_sdk::i128; /// Set the allowance to "amount" for "spender" to transfer from "from". fn approve( env: soroban_sdk::Env, from: soroban_auth::Signature, - nonce: soroban_sdk::BigInt, + nonce: soroban_sdk::i128, spender: soroban_auth::Identifier, - amount: soroban_sdk::BigInt, + amount: soroban_sdk::i128, ); /// Get the balance of "id". - fn balance(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> soroban_sdk::BigInt; + fn balance(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> soroban_sdk::i128; /// Transfer "amount" from "from" to "to. fn xfer( env: soroban_sdk::Env, from: soroban_auth::Signature, - nonce: soroban_sdk::BigInt, + nonce: soroban_sdk::i128, to: soroban_auth::Identifier, - amount: soroban_sdk::BigInt, + amount: soroban_sdk::i128, ); /// Transfer "amount" from "from" to "to", consuming the allowance of "spender". fn xfer_from( env: soroban_sdk::Env, spender: soroban_auth::Signature, - nonce: soroban_sdk::BigInt, + nonce: soroban_sdk::i128, from: soroban_auth::Identifier, to: soroban_auth::Identifier, - amount: soroban_sdk::BigInt, + amount: soroban_sdk::i128, ); // Returns true if "id" is frozen. fn is_frozen(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> bool; // Returns the current nonce for "id". - fn nonce(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> soroban_sdk::BigInt; + fn nonce(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> soroban_sdk::i128; // -------------------------------------------------------------------------------- // Descriptive Interface diff --git a/docs/examples/auth-advanced.mdx b/docs/examples/auth-advanced.mdx index 3b558125..ae603279 100644 --- a/docs/examples/auth-advanced.mdx +++ b/docs/examples/auth-advanced.mdx @@ -134,14 +134,14 @@ pub struct IncrementContract; #[contractimpl] impl IncrementContract { /// Increment increments a counter for the invoker, and returns the value. - pub fn increment(env: Env, sig: Signature, nonce: BigInt) -> u32 { + pub fn increment(env: Env, sig: Signature, nonce: i128) -> u32 { // Verify that the signature signs and authorizes this invocation. let id = sig.identifier(&env); verify(&env, &sig, symbol!("increment"), (&id, &nonce)); // Verify that the nonce has not been consumed to prevent replay of the // same presigned invocation more than once. - verify_and_consume_nonce(&env, &sig, &nonce); + verify_and_consume_nonce(&env, &sig, nonce); // Construct a key for the data being stored. Use an enum to set the // contract up well for adding other types of data to be stored. @@ -164,21 +164,21 @@ impl IncrementContract { count } - pub fn nonce(env: Env, id: Identifier) -> BigInt { + pub fn nonce(env: Env, id: Identifier) -> i128 { get_nonce(&env, &id) } } -fn verify_and_consume_nonce(env: &Env, sig: &Signature, nonce: &BigInt) { +fn verify_and_consume_nonce(env: &Env, sig: &Signature, nonce: i128) { match sig { Signature::Invoker => { - if BigInt::zero(env) != nonce { + if nonce != 0 { panic_with_error!(env, Error::IncorrectNonceForInvoker); } } Signature::Ed25519(_) | Signature::Account(_) => { let id = sig.identifier(env); - if nonce != &get_nonce(env, &id) { + if nonce != get_nonce(env, &id) { panic_with_error!(env, Error::IncorrectNonce); } set_nonce(env, &id, nonce + 1); @@ -186,15 +186,12 @@ fn verify_and_consume_nonce(env: &Env, sig: &Signature, nonce: &BigInt) { } } -fn get_nonce(env: &Env, id: &Identifier) -> BigInt { +fn get_nonce(env: &Env, id: &Identifier) -> i128 { let key = DataKey::Nonce(id.clone()); - env.data() - .get(key) - .unwrap_or_else(|| Ok(BigInt::zero(env))) - .unwrap() + env.data().get(key).unwrap_or(Ok(0)).unwrap() } -fn set_nonce(env: &Env, id: &Identifier, nonce: BigInt) { +fn set_nonce(env: &Env, id: &Identifier, nonce: i128) { let key = DataKey::Nonce(id.clone()); env.data().set(key, nonce); } @@ -349,7 +346,7 @@ stored with key `DataKey::Counter`. The `soroban_auth::verify` method verifies the input `Signature`. ```rust -pub fn increment(env: Env, sig: Signature, nonce: BigInt) -> u32 { +pub fn increment(env: Env, sig: Signature, nonce: i128) -> u32 { let id = sig.identifier(&env); verify(&env, &sig, symbol!("increment"), (&id, &nonce)); // ... @@ -397,7 +394,7 @@ This example uses a sequential nonce for replay prevention. ::: ```rust -pub fn increment(env: Env, sig: Signature, nonce: BigInt) -> u32 { +pub fn increment(env: Env, sig: Signature, nonce: i128) -> u32 { // ... verify_and_consume_nonce(&env, &sig, &nonce); // ... @@ -417,16 +414,16 @@ it matches the nonce included in this invocation, and error if not. The nonce is incremented so that the value is consumed and cannot be reused. ```rust -fn verify_and_consume_nonce(env: &Env, sig: &Signature, nonce: &BigInt) { +fn verify_and_consume_nonce(env: &Env, sig: &Signature, nonce: i128) { match sig { Signature::Invoker => { - if BigInt::zero(env) != nonce { + if nonce != 0 { panic_with_error!(env, Error::IncorrectNonceForInvoker); } } Signature::Ed25519(_) | Signature::Account(_) => { let id = sig.identifier(env); - if nonce != &get_nonce(env, &id) { + if nonce != get_nonce(env, &id) { panic_with_error!(env, Error::IncorrectNonce); } set_nonce(env, &id, nonce + 1); @@ -434,15 +431,12 @@ fn verify_and_consume_nonce(env: &Env, sig: &Signature, nonce: &BigInt) { } } -fn get_nonce(env: &Env, id: &Identifier) -> BigInt { +fn get_nonce(env: &Env, id: &Identifier) -> i128 { let key = DataKey::Nonce(id.clone()); - env.data() - .get(key) - .unwrap_or_else(|| Ok(BigInt::zero(env))) - .unwrap() + env.data().get(key).unwrap_or(Ok(0)).unwrap() } -fn set_nonce(env: &Env, id: &Identifier, nonce: BigInt) { +fn set_nonce(env: &Env, id: &Identifier, nonce: i128) { let key = DataKey::Nonce(id.clone()); env.data().set(key, nonce); } @@ -488,7 +482,7 @@ expect users to keep track of the next nonce to use, but that may not be trivial, so the contract exports a function that provides the information. ```rust -pub fn nonce(env: Env, id: Identifier) -> BigInt { +pub fn nonce(env: Env, id: Identifier) -> i128 { get_nonce(&env, &id) } ``` @@ -515,7 +509,7 @@ fn test_auth_with_invoker() { assert_eq!( client .with_source_account(&user_1) - .increment(&Signature::Invoker, &BigInt::zero(&env)), + .increment(&Signature::Invoker, &0), 1 ); // ... @@ -538,7 +532,7 @@ very simple. ```rust client .with_source_account(&user_1) - .increment(&Signature::Invoker, &BigInt::zero(&env)), + .increment(&Signature::Invoker, &0), ``` :::tip @@ -564,7 +558,7 @@ fn test_auth_with_ed25519() { let (user_1_id, user_1_sign) = soroban_auth::testutils::ed25519::generate(&env); let (user_2_id, user_2_sign) = soroban_auth::testutils::ed25519::generate(&env); - let nonce = BigInt::from_u32(&env, 0); + let nonce = 0; let sig = soroban_auth::testutils::ed25519::sign( &env, &user_1_sign, diff --git a/docs/examples/hello-world.mdx b/docs/examples/hello-world.mdx index f609ee43..fd56138a 100644 --- a/docs/examples/hello-world.mdx +++ b/docs/examples/hello-world.mdx @@ -79,8 +79,8 @@ pub struct HelloContract; Contract functions look much like regular Rust functions. They mave have any number of arguments, but arguments must support being transmitted to and from the Soroban environment that the contract runs in. The Soroban SDK provides some -types like `Vec`, `Map`, `BigInt`, `Symbol`, `Bytes`, `BytesN`, etc that -can be used. Primitive values like `u64`, `i64`, `u32`, `i32`, and `bool` can +types like `Vec`, `Map`, `Symbol`, `Bytes`, `BytesN`, etc that can be used. +Primitive values like `u128`, `i128`, `u64`, `i64`, `u32`, `i32`, and `bool` can also be used. Floats are not supported. Contract inputs must not be references. diff --git a/docs/learn/built-in-types.mdx b/docs/learn/built-in-types.mdx index fec3e74d..a98c3828 100644 --- a/docs/learn/built-in-types.mdx +++ b/docs/learn/built-in-types.mdx @@ -27,6 +27,10 @@ The following primitive types are supported: ### Signed 64-bit Integer (`i64`) +### Unsigned 128-bit Integer (`u128`) + +### Signed 128-bit Integer (`i128`) + ### Bool (`bool`) ## Symbol (`Symbol`) @@ -77,14 +81,6 @@ will fail if they are not. Most functions on Map return a Result due to this. Maps have at most one entry per key. Setting a value for a key in the map that already has a value for that key replaces the value. -## BigInt (`BigInt`) - -BigInt is an arbitrary sized signed integer. - -The value is stored in the Host and available to the Guest through functions on -the type. Operations between BigInts are performed inside the Host and do not -consume Guest resources such as memory. - ## Address (`Address`) Address is union of all the types that can be the invoker of a contract. diff --git a/docs/sdks/byo.mdx b/docs/sdks/byo.mdx index 7ffb5c0c..f02ee6b1 100644 --- a/docs/sdks/byo.mdx +++ b/docs/sdks/byo.mdx @@ -47,7 +47,6 @@ guarantee exists at this time. - [Map] - [Vec] - [Bytes] - - [BigInt] ### User Defined Types @@ -114,6 +113,5 @@ The test environment should include: [Map]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/map.rs [Vec]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/vec.rs [Bytes]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/bytes.rs -[BigInt]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/bigint.rs [`SCEnvMetaEntry`]: https://github.com/stellar/stellar-xdr/blob/next/Stellar-contract-env-meta.x [`SCSpecEntry`]: https://github.com/stellar/stellar-xdr/blob/next/Stellar-contract-spec.x diff --git a/docs/tutorials/write-a-contract.mdx b/docs/tutorials/write-a-contract.mdx index b617e3a6..6a2dbe15 100644 --- a/docs/tutorials/write-a-contract.mdx +++ b/docs/tutorials/write-a-contract.mdx @@ -26,8 +26,8 @@ how to setup a project. Many of the types available in typical Rust programs, such as `std::vec::Vec`, are not available, as there is no allocator and no heap memory in Soroban contracts. The `soroban-sdk` provides a variety of types like `Vec`, `Map`, -`BigInt`, `Bytes`, `BytesN`, `Symbol`, that all utilize the Soroban -environment's memory and native capabilities. +`Bytes`, `BytesN`, `Symbol`, that all utilize the Soroban environment's memory +and native capabilities. ```rust pub struct Contract; From 10cd25f63c31434abce4c6741c9125bce19354b7 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Fri, 2 Dec 2022 17:11:44 -0800 Subject: [PATCH 06/22] Fix soroban_sdk::i128 -> i128 (#238) --- docs/common-interfaces/token.mdx | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/common-interfaces/token.mdx b/docs/common-interfaces/token.mdx index 0aad4e3b..f88b5237 100644 --- a/docs/common-interfaces/token.mdx +++ b/docs/common-interfaces/token.mdx @@ -23,25 +23,25 @@ pub trait Contract { fn burn( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::i128, + nonce: i128, from: soroban_auth::Identifier, - amount: soroban_sdk::i128, + amount: i128, ); /// If "admin" is the administrator, mint "amount" to "to". fn mint( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::i128, + nonce: i128, to: soroban_auth::Identifier, - amount: soroban_sdk::i128, + amount: i128, ); /// If "admin" is the administrator, set the administrator to "id". fn set_admin( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::i128, + nonce: i128, new_admin: soroban_auth::Identifier, ); @@ -49,7 +49,7 @@ pub trait Contract { fn freeze( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::i128, + nonce: i128, id: soroban_auth::Identifier, ); @@ -57,7 +57,7 @@ pub trait Contract { fn unfreeze( env: soroban_sdk::Env, admin: soroban_auth::Signature, - nonce: soroban_sdk::i128, + nonce: i128, id: soroban_auth::Identifier, ); @@ -70,44 +70,44 @@ pub trait Contract { env: soroban_sdk::Env, from: soroban_auth::Identifier, spender: soroban_auth::Identifier, - ) -> soroban_sdk::i128; + ) -> i128; /// Set the allowance to "amount" for "spender" to transfer from "from". fn approve( env: soroban_sdk::Env, from: soroban_auth::Signature, - nonce: soroban_sdk::i128, + nonce: i128, spender: soroban_auth::Identifier, - amount: soroban_sdk::i128, + amount: i128, ); /// Get the balance of "id". - fn balance(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> soroban_sdk::i128; + fn balance(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> i128; /// Transfer "amount" from "from" to "to. fn xfer( env: soroban_sdk::Env, from: soroban_auth::Signature, - nonce: soroban_sdk::i128, + nonce: i128, to: soroban_auth::Identifier, - amount: soroban_sdk::i128, + amount: i128, ); /// Transfer "amount" from "from" to "to", consuming the allowance of "spender". fn xfer_from( env: soroban_sdk::Env, spender: soroban_auth::Signature, - nonce: soroban_sdk::i128, + nonce: i128, from: soroban_auth::Identifier, to: soroban_auth::Identifier, - amount: soroban_sdk::i128, + amount: i128, ); // Returns true if "id" is frozen. fn is_frozen(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> bool; // Returns the current nonce for "id". - fn nonce(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> soroban_sdk::i128; + fn nonce(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> i128; // -------------------------------------------------------------------------------- // Descriptive Interface From 702f39508b36e63e28c0638a9c10426a90a09537 Mon Sep 17 00:00:00 2001 From: Dmytro Kozhevin Date: Mon, 5 Dec 2022 19:50:20 -0500 Subject: [PATCH 07/22] Updated the deployer example. (#230) --- docs/examples/deployer.mdx | 125 +++++++++++++++++++++++-------------- 1 file changed, 79 insertions(+), 46 deletions(-) diff --git a/docs/examples/deployer.mdx b/docs/examples/deployer.mdx index 1bdaa973..2721e457 100644 --- a/docs/examples/deployer.mdx +++ b/docs/examples/deployer.mdx @@ -50,12 +50,18 @@ pub struct Deployer; #[contractimpl] impl Deployer { - /// Deploy the contract wasm and after deployment invoke the init function - /// of the contract with the given arguments. Returns the contract ID and - /// result of the init function. - pub fn deploy(env: Env, salt: Bytes, wasm: Bytes, init_fn: Symbol, init_args: Vec) -> (BytesN<32>, RawVal) { - // Deploy the wasm. - let id = env.deployer().with_current_contract(salt).deploy(wasm); + /// Deploy the contract using WASM hash and after deployment invoke the init + /// function of the contract with the given arguments. Returns the + /// contract ID and result of the init function. + pub fn deploy( + env: Env, + salt: Bytes, + wasm_hash: BytesN<32>, + init_fn: Symbol, + init_args: Vec, + ) -> (BytesN<32>, RawVal) { + // Deploy the contract using the installed WASM code with given hash. + let id = env.deployer().with_current_contract(salt).deploy(wasm_hash); // Invoke the init function with the given arguments. let res: RawVal = env.invoke_contract(&id, &init_fn, init_args); // Return the contract ID of the deployed contract and the result of @@ -74,21 +80,38 @@ Contracts can deploy other contracts by using the SDK. The contract ID of the deployed contract is deterministic and is derived from the deploying contract ID and the provided salt. -Open the `deployer/deployer/src/src.rs` file to follow along. +Open the `deployer/deployer/src/lib.rs` file to follow along. + +### Contract Code Installation + +Before deploying the new contract instances, the WASM code needs to be installed +on-chain. Then it can be used to deploy an arbitrary number of contract +instances. The installation should typically happen outside of the deployer +contract, as it needs to happen just once. +while the deployer contract can be called multiple times. + +See the [tests](#tests) for an example of installing the contract code in tests. +For the actual on-chain installation see the general deployment +[tutorial](https://soroban.stellar.org/docs/tutorials/deploy-to-futurenet). ### Deployer -The `deployer` contract deploys other contracts. It accepts a salt that will be -used to derive a contract ID, and a WASM bytes to deploy. It also accepts an -initialization function and arguments to pass to that function. +The `Deployer` contract deploys other contracts. It accepts a salt that will be +used to derive a contract ID and a hash-based identifier of the installed WASM +(note, that this is not just the hash of the WASM file). +It also accepts an initialization function and arguments to pass to that function. The contract first gets a deployer using the salt, then calls deploy with the -WASM bytes. The WASM bytes will be deployed and the contract ID for that new -contract is returned. The contract ID is deterministic and is derived from the -deploying contract and the salt. +WASM hash. The contract ID for the new contract is returned. The implementation +of the new contract is defined by the WASM file installed under `wasm_hash` ( +only the `wasm_hash` itself is stored per contract ID thus saving the ledger +space and fees). + +The contract ID is deterministic and is derived from the deploying contract and +the salt. ```rust -let id = env.deployer().with_current_contract(salt).deploy(wasm); +let id = env.deployer().with_current_contract(salt).deploy(wasm_hash); ``` The contract invokes the new contract's intialization function and passes @@ -98,7 +121,8 @@ through the arguments. let res: RawVal = env.invoke_contract(&id, &init_fn, init_args); ``` -The contract returns the new contract ID and the result of the initializatio function. +The contract returns the new contract ID and the result of the initialization +function. ```rust (id, res) ``` @@ -118,20 +142,16 @@ mod contract { #[test] fn test() { let env = Env::default(); - let deployer_id = BytesN::from_array(&env, &[0; 32]); - env.register_contract(&deployer_id, Deployer); - let client = DeployerClient::new(&env, &deployer_id); + let client = DeployerClient::new(&env, &env.register_contract(None, Deployer)); + + // Install the WASM that will be deployed by the deployer contract. + let wasm_hash = env.install_contract_wasm(contract::WASM); // Deploy contract using deployer, and include an init function to call. let salt = Bytes::from_array(&env, &[0; 32]); - let wasm: Bytes = contract::WASM.into_val(&env); let init_fn = symbol!("init"); let init_fn_args = (5u32,).into_val(&env); - let (contract_id, init_result) = client.deploy(&salt, &wasm, &init_fn, &init_fn_args); - assert_eq!( - contract_id, - bytesn!(&env, 0xead19f55aec09bfcb555e09f230149ba7f72744a5fd639804ce1e934e8fe9c5d) - ); + let (contract_id, init_result) = client.deploy(&salt, &wasm_hash, &init_fn, &init_fn_args); assert!(init_result.is_void()); // Invoke contract to check that it is initialized. @@ -154,9 +174,7 @@ mod contract { That contract contains the following code, which exports a couple functions that sets a value in the initialization function and allows the value -to be retrieved from another function. The test contract will be used when -testing the deployer, by deploying the contract and then checking if the -contract is deployed by invoking its functions. +to be retrieved from another function. ```rust title="deployer/contract/src/lib.rs" pub struct Contract; @@ -174,6 +192,9 @@ impl Contract { } ``` +The test contract will be used when testing the deployer. The deployer contract +deploys the test contract and invokes its `init` function. + In any test the first thing that is always required is an `Env`, which is the Soroban environment that the contract will run in. @@ -181,44 +202,42 @@ Soroban environment that the contract will run in. let env = Env::default(); ``` -A fixed contract ID is used so that we can assert on the contract ID of the -contract that gets deployed, which will be derived in part from the deployers -contract ID. +Install the code of the test contract that we have imported above via +`contractimport!` and get the hash of the installed WASM code: ```rust -let deployer_id = BytesN::from_array(&env, &[0; 32]); +// Install the WASM that will be deployed by the deployer contract. +let wasm_hash = env.install_contract_wasm(contract::WASM); ``` -The deployer contract is registered with the environment. +Register the deployer contract with the environment. ```rust env.register_contract(&deployer_id, Deployer); ``` +Create a client to invoke the `Deployer` contract. + +```rust +let client = DeployerClient::new(&env, &deployer_id); +``` + All public functions within an `impl` block that is annotated with the `#[contractimpl]` attribute have a corresponding function generated in a generated client type. The client type will be named the same as the contract type with `Client` appended. For example, in our contract the contract type is `Deployer`, and the client is named `DeployerClient`. -```rust -let client = DeployerClient::new(&env, &deployer_id); -``` - The client is used to invoke the `deploy` function. The contract will deploy the -test contract WASM bytes, call the `"init"` function, and pass in a single -`5u32` argument. +test contract using the hash of its WASM code, call the `"init"` function, and +pass in a single `5u32` argument. ```rust +// Deploy contract using deployer, and include an init function to call. let salt = Bytes::from_array(&env, &[0; 32]); -let wasm: Bytes = contract::WASM.into_val(&env); let init_fn = symbol!("init"); let init_fn_args = (5u32,).into_val(&env); -let (contract_id, init_result) = client.deploy(&salt, &wasm, &init_fn, &init_fn_args); -assert_eq!( - contract_id, - bytesn!(&env, 0xead19f55aec09bfcb555e09f230149ba7f72744a5fd639804ce1e934e8fe9c5d) -); +let (contract_id, init_result) = client.deploy(&salt, &wasm_hash, &init_fn, &init_fn_args); assert!(init_result.is_void()); ``` @@ -256,18 +275,32 @@ both contracts: If you have [`soroban-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. + +```sh +soroban install --wasm target/wasm32-unknown-unknown/release/soroban_deployer_test_contract.wasm +``` + +The command prints out the hash as hex. It will look something like `edce149b183ea03dfd896a263d2e17c1f08229da52afa6f822d9cbc67c103806`. + +Then the deployer contract may be invoked with the WASM hash value above. + ```sh soroban invoke \ --wasm target/wasm32-unknown-unknown/release/soroban_deployer_contract.wasm \ --id 0 \ --fn deploy \ --arg 0000000000000000000000000000000000000000000000000000000000000000 \ - --arg $(xxd -p -c- target/wasm32-unknown-unknown/release/soroban_deployer_test_contract.wasm) \ + --arg edce149b183ea03dfd896a263d2e17c1f08229da52afa6f822d9cbc67c103806 \ --arg init \ --arg '[{"u32":5}]' ``` -And then invoke the deployed test contract. +And then invoke the deployed test contract using the identifier returned from +the previous command. ```sh soroban invoke \ From c4c8a04a559939e62bc219c0104214f7c4fdfd5c Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 10:04:25 -0800 Subject: [PATCH 08/22] Update soroban-cli to v0.3.1 (#239) --- docs/getting-started/setup.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/setup.mdx b/docs/getting-started/setup.mdx index e8353dc3..54229aea 100644 --- a/docs/getting-started/setup.mdx +++ b/docs/getting-started/setup.mdx @@ -54,7 +54,7 @@ contract will execute on network, however in a local sandbox. Install the Soroban CLI using `cargo install`. ```sh -cargo install --locked --version 0.2.1 soroban-cli +cargo install --locked --version 0.3.1 soroban-cli ``` :::info @@ -72,7 +72,7 @@ soroban ``` ❯ soroban -soroban 0.2.1 +soroban 0.3.1 https://soroban.stellar.org USAGE: @@ -89,6 +89,7 @@ SUBCOMMANDS: serve Run a local webserver for web app development and testing token Wrap, create, and manage token contracts deploy Deploy a WASM file as a contract + install Install a WASM file to the ledger without creating a contract instance gen Generate code client bindings for a contract xdr Decode xdr version Print version information From 25f30616371a2cfe2dd18a6d12c37fa9032fd020 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 10:11:29 -0800 Subject: [PATCH 09/22] Update versions of software (#240) --- docs/releases.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/releases.mdx b/docs/releases.mdx index ea88384b..30ce20fe 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -26,11 +26,11 @@ network passphrase changes. | Software | Version | | -------- | ------- | -| XDR | https://github.com/stellar/stellar-xdr/tree/026c9cd074bdb28ddde8ee52f2a4502d9e518a09 | +| XDR | [026c9cd074bdb28ddde8ee52f2a4502d9e518a09](https://github.com/stellar/stellar-xdr/tree/026c9cd074bdb28ddde8ee52f2a4502d9e518a09) | | Soroban Environment | `v0.0.10` | | Stellar Core | `stellar-core_19.5.1-1137.b3a6bc281.focal~soroban` | | Soroban Rust SDK | `v0.3.1` | -| Soroban CLI | `` | +| Soroban CLI | `v0.3.1` | | Soroban RPC | `` | | Stellar Horizon | `stellar-horizon:2.22.0~soroban-318` | | Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:...` | @@ -77,7 +77,7 @@ See https://github.com/stellar/soroban-tools/releases v... for more details. | Stellar Core | `19.5.1-1111.eba1d3de9.focal~soroban` | | Soroban Rust SDK | `v0.2.1` | | Soroban CLI | `v0.2.1` | -| Soroban RPC | ??? | +| Soroban RPC | `0.3.1-32` | | Stellar Horizon | `2.22.0~soroban-304` | | Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:0993d3350148af6ffeab5dc8f0b835236b28dade6dcae77ff8a09317162f768d` | | Futurenet Network Passphrase | `Test SDF Future Network ; October 2022` | From 029ff79e0e3527d0511954e97173f108505c8a91 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 10:18:29 -0800 Subject: [PATCH 10/22] Remove "Preview" from releases page title --- docs/releases.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/releases.mdx b/docs/releases.mdx index 30ce20fe..a3d05407 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 1 -title: Preview Releases +title: Releases --- The following Soroban releases are preview releases. From 963705fd131793a7357f170ec515a5ed5ef60546 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 10:27:11 -0800 Subject: [PATCH 11/22] Update chanelogs --- docs/releases.mdx | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/docs/releases.mdx b/docs/releases.mdx index a3d05407..0b91aae0 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -40,31 +40,23 @@ network passphrase changes. #### XDR -* ... +See https://github.com/stellar/stellar-xdr/compare/48d5e17ae63bba0aa9725cd9d18d7438f44c07b1...026c9cd074bdb28ddde8ee52f2a4502d9e518a09 for more details. #### Soroban Environment -* ... - -See https://github.com/stellar/rs-soroban-env/releases v... for more details. +See https://github.com/stellar/rs-soroban-env/releases v0.0.10 for more details. #### Soroban Rust SDK -* ... - -See https://github.com/stellar/rs-soroban-sdk/releases v... for more details. +See https://github.com/stellar/rs-soroban-sdk/releases v0.3.0, v0.3.1 for more details. #### Soroban RPC -* ... - -See https://github.com/stellar/soroban-tools/releases v... for more details. +See https://github.com/stellar/soroban-tools/releases v0.3.0, v0.3.1 for more details. #### Soroban CLI -* ... - -See https://github.com/stellar/soroban-tools/releases v... for more details. +See https://github.com/stellar/soroban-tools/releases v0.3.0, v0.3.1 for more details. ## Preview 4 (November 15th, 2022) From d490ab6784c461ec611cade852945697a32d7b2e Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 10:28:45 -0800 Subject: [PATCH 12/22] Update soroban-rpc version --- docs/releases.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/releases.mdx b/docs/releases.mdx index 0b91aae0..aa795b87 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -31,7 +31,7 @@ network passphrase changes. | Stellar Core | `stellar-core_19.5.1-1137.b3a6bc281.focal~soroban` | | Soroban Rust SDK | `v0.3.1` | | Soroban CLI | `v0.3.1` | -| Soroban RPC | `` | +| Soroban RPC | `0.3.1-32` | | Stellar Horizon | `stellar-horizon:2.22.0~soroban-318` | | Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:...` | | Futurenet Network Passphrase | `Test SDF Future Network ; October 2022` | From 2b88bf17d9b092c6803cb907daa9402edc67aa8c Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 10:35:09 -0800 Subject: [PATCH 13/22] Update Friendbot version --- docs/releases.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/releases.mdx b/docs/releases.mdx index aa795b87..582e211e 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -33,6 +33,7 @@ network passphrase changes. | Soroban CLI | `v0.3.1` | | Soroban RPC | `0.3.1-32` | | Stellar Horizon | `stellar-horizon:2.22.0~soroban-318` | +| Stellar Friendbot | `soroban-v0.0.2-alpha` | | Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:...` | | Futurenet Network Passphrase | `Test SDF Future Network ; October 2022` | From 13a0c9f6a5c802685cb3b2451b8413ee854f22c9 Mon Sep 17 00:00:00 2001 From: shawn Date: Tue, 6 Dec 2022 12:15:58 -0800 Subject: [PATCH 14/22] updated quickstart image sha (#241) --- docs/releases.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/releases.mdx b/docs/releases.mdx index 582e211e..6e690bad 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -34,7 +34,7 @@ network passphrase changes. | Soroban RPC | `0.3.1-32` | | Stellar Horizon | `stellar-horizon:2.22.0~soroban-318` | | Stellar Friendbot | `soroban-v0.0.2-alpha` | -| Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:...` | +| Stellar Quickstart | `stellar/quickstart:soroban-dev@sha256:8046391718f8e58b2b88b9c379abda3587bb874689fa09b2ed4871a764ebda27` | | Futurenet Network Passphrase | `Test SDF Future Network ; October 2022` | ### Changelog From 114e00d4c4636a609751cc48926accd597cf707a Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 12:52:01 -0800 Subject: [PATCH 15/22] Add changelog notes about XDR --- docs/releases.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/releases.mdx b/docs/releases.mdx index 6e690bad..18eb4332 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -41,6 +41,11 @@ network passphrase changes. #### XDR +- Remove BigInt from ScVal +- Add u128 and i128 to ScVal +- Change the structure of events in meta +- Change transaction operation structure for Soroban deployments and invocations + See https://github.com/stellar/stellar-xdr/compare/48d5e17ae63bba0aa9725cd9d18d7438f44c07b1...026c9cd074bdb28ddde8ee52f2a4502d9e518a09 for more details. #### Soroban Environment From 170c0efee5b29d2da758e927c2c7894f8134945a Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 12:53:50 -0800 Subject: [PATCH 16/22] Add changelog notes about env --- docs/releases.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/releases.mdx b/docs/releases.mdx index 18eb4332..e70194e3 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -50,6 +50,12 @@ See https://github.com/stellar/stellar-xdr/compare/48d5e17ae63bba0aa9725cd9d18d7 #### Soroban Environment +- Add Host::with_artificial_test_contract_frame +- Restructure benchmark framework, add calibration code for all CostTypes +- Disable budget costs for object cmp +- Env changes to decouple contract instance from source +- Remove BigInt, switch everything to u128 and i128. + See https://github.com/stellar/rs-soroban-env/releases v0.0.10 for more details. #### Soroban Rust SDK From 4829f83f2fc989befa74c05d0aa6ffd30a3eefcd Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 13:10:24 -0800 Subject: [PATCH 17/22] Add other changelogs --- docs/releases.mdx | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/releases.mdx b/docs/releases.mdx index e70194e3..3c8b4224 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -54,20 +54,39 @@ See https://github.com/stellar/stellar-xdr/compare/48d5e17ae63bba0aa9725cd9d18d7 - Restructure benchmark framework, add calibration code for all CostTypes - Disable budget costs for object cmp - Env changes to decouple contract instance from source -- Remove BigInt, switch everything to u128 and i128. +- Remove BigInt, switch everything to u128 and i128 See https://github.com/stellar/rs-soroban-env/releases v0.0.10 for more details. #### Soroban Rust SDK +- Add Env::as_contract for testutils by @leighmcculloch in #761 +- Update contract deployment to match the Env changes by @dmkozh in #766 +- Make contract_id public in contract clients. by @dmkozh in #768 +- Remove BigInt by @sisuresh in #770 +- Add soroban-ledger-snapshot +- Change gen JSON output from stream to array (contribution by @vinamogit`) +- Contributions from @vinamogit + See https://github.com/stellar/rs-soroban-sdk/releases v0.3.0, v0.3.1 for more details. #### Soroban RPC +- Add soroban-rpc version subcommand +- Add a new getLedgerEntry jsonrpc method, deprecating and replacing getContractData allowing an application to fetch any ledger entry +- Added new getEvents method currently backed by horizon + See https://github.com/stellar/soroban-tools/releases v0.3.0, v0.3.1 for more details. #### Soroban CLI +- Added type description to errors when using --arg (contribution by @waldmatias) +- Additional CLI support for the contract deployment changes +- Adds support for soroban deploy --wasm-hash, as well as soroban install --wasm +- Add xdr and env version to version subcommand output +- Fix that the footpoint was not set correctly when deploying the wrapped token contract (contribution by @overcat) +- Contributions from @waldmatias, @willemneal, @overcat, @brson + See https://github.com/stellar/soroban-tools/releases v0.3.0, v0.3.1 for more details. ## Preview 4 (November 15th, 2022) From ffc2114490c0e35507a56dedf9d0dcd42e84bc5a Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Tue, 6 Dec 2022 13:33:40 -0800 Subject: [PATCH 18/22] Add contributors --- docs/releases.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/releases.mdx b/docs/releases.mdx index 3c8b4224..1fb27233 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -65,7 +65,7 @@ See https://github.com/stellar/rs-soroban-env/releases v0.0.10 for more details. - Make contract_id public in contract clients. by @dmkozh in #768 - Remove BigInt by @sisuresh in #770 - Add soroban-ledger-snapshot -- Change gen JSON output from stream to array (contribution by @vinamogit`) +- Change gen JSON output from stream to array (contribution by [@vinamogit]) - Contributions from @vinamogit See https://github.com/stellar/rs-soroban-sdk/releases v0.3.0, v0.3.1 for more details. @@ -85,7 +85,7 @@ See https://github.com/stellar/soroban-tools/releases v0.3.0, v0.3.1 for more de - Adds support for soroban deploy --wasm-hash, as well as soroban install --wasm - Add xdr and env version to version subcommand output - Fix that the footpoint was not set correctly when deploying the wrapped token contract (contribution by @overcat) -- Contributions from @waldmatias, @willemneal, @overcat, @brson +- Contributions from [@waldmatias], [@willemneal], [@overcat], [@brson] See https://github.com/stellar/soroban-tools/releases v0.3.0, v0.3.1 for more details. @@ -177,3 +177,9 @@ See https://www.stellar.org/developers-blog/soroban-preview-release-2. ## Preview 1 (August 1st, 2022) See https://www.stellar.org/blog/project-jump-cannon-soroban-preview-release. + +[@waldmatias]: https://github.com/waldmatias +[@willemneal]: https://github.com/willemneal +[@overcat]: https://github.com/overcat +[@brson]: https://github.com/brson +[@vinamogit]: https://github.com/vinamogit From 3ab80f07e2dabd6cc06799098f5c55917d469fe6 Mon Sep 17 00:00:00 2001 From: Siddharth Suresh Date: Wed, 4 Jan 2023 16:52:25 -0800 Subject: [PATCH 19/22] Token interface and single balance update --- docs/built-in-contracts/token.mdx | 192 ++++++++++-------------------- docs/common-interfaces/token.mdx | 85 +++++++------ 2 files changed, 112 insertions(+), 165 deletions(-) diff --git a/docs/built-in-contracts/token.mdx b/docs/built-in-contracts/token.mdx index 0bcb95e6..6cf8a497 100644 --- a/docs/built-in-contracts/token.mdx +++ b/docs/built-in-contracts/token.mdx @@ -1,49 +1,87 @@ --- sidebar_position: 1 -title: Token Contract +title: Stellar Asset Contract --- -# Token Contract +# Stellar Asset Contract -The token contract is an implementation of [CAP-46-6 Smart Contract Standardized Asset]. +The Stellar Asset Contract is an implementation of [CAP-46-6 Smart Contract Standardized Asset]. [CAP-46-6 Smart Contract Standardized Asset]: https://stellar.org/protocol/cap-46-06 :::caution The token contract is in early development, has not been audited, and is -intended for use in development and testing only at this stage.. Report issues +intended for use in development and testing only at this stage. Report issues [here](https://github.com/stellar/soroban-token-contract/issues/new/choose). ::: ## Overview -Tokens are a vital part of blockchains, and contracts that implement token -functionality are inevitable on any smart contract platform. A built-in token -contract has a number of advantages over token contracts written by the -ecosystem. First, we can special case this contract and run it natively instead -of running in a WASM VM, reducing the cost of using the contract. Second, we -can use this built-in contract to allow "classic" Stellar assets to interoperate -with Soroban. Note that this standard token contract does not prevent the -ecosystem from developing other token contracts if the standard is missing -functionality they require. +Stellar has numerous assets on its classic network, and being able to use them +in Soroban would give users much more flexibility with how they can use their +assets. For this reason, we introduced the Stellar Asset Contract, or SAC for +short, which will allow users to use their Stellar account and trustline +balances in Soroban. -The standard token contract is similar to the widely used ERC-20 token standard, -which should make it easier for existing smart contract developers to get -started on Stellar. +The SAC implements the [token interface](../common-interfaces/token.mdx), which is +similar to the widely used ERC-20 token standard. This should make it easier for +existing smart contract developers to get started on Stellar. -## Token contract authorization semantics +## Interacting with classic Stellar assets + +The Stellar Asset Contract is the only way to interact with 'classic' Stellar assets in +Soroban. 'Classic' assets include native Stellar token (lumens) and all the +existing trustlines. + +For every 'classic' asset exactly one respective token contract can be deployed. +It can be deployed using the `InvokeHostFunctionOp` with +`HOST_FUNCTION_TYPE_CREATE_CONTRACT` and `CONTRACT_ID_FROM_ASSET` specified +[here](../tutorials/invoking-contracts-with-transactions). The resulting token +will have a deterministic identifier. The issuer of the asset will be the +administrator of the deployed contract. Because the the Native Stellar token +doesn't have an issuer, it will not have an administrator either. It also cannot +be burned. + +After the contract has been deployed, users can use their classic account or +trustline balance. There are some differences depending on if you are using a +classic account identifier vs a non-account identifier like a contract. + +- Using `Identifier::Account` + - The balance must exist in a trustline or an account. This means the contract + will not store the balance in ContractData. If the trustline or account is + missing, any function that tries to interact with that balance will fail. + - Classic trustline semantics will be followed. + - Transfers will only succeed if the corresponding + trustline(s) have the `AUTHORIZED_FLAG` set. + - A trustline balance can only be clawed back using the `clawback` + contract function if the trustline has `TRUSTLINE_CLAWBACK_ENABLED_FLAG` + set. + - The admin can only deauthorize a trustline if the issuer of the asset has + `AUTH_REVOCABLE` set. The deauthorization will fail if the issuer is + missing. Note that when a trustline is deauthorized from Soroban, + `AUTHORIZED_FLAG` is cleared and `AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG` is + set to avoid having to pull offers and redeeming pool shares. + - Transfers to the issuer account will burn the token, while transfers from + the issuer account will mint. + - Trustline balances are stored in a 64-bit signed integer. +- Using `Identifier::Ed25519` or `Identifier::Contract` + - The balance and authorization state will be stored in ContractData, as + opposed to a trustline. + - These balances are stored in a 128-bit signed integer. + +## Authorization semantics See the [advanced auth example](../examples/auth-advanced) for an overview of authorization. -### Token operations +### SAC operations The token contract contains three kinds of operations - getters, such as `balance`, which do not change the state of the contract -- unprivileged mutators, such as `approve` and `xfer`, which change the state of +- unprivileged mutators, such as `incr_allow` and `xfer`, which change the state of the contract but do not require special privileges -- privileged mutators, such as `burn` and `set_admin`, which change the state of +- privileged mutators, such as `clawback` and `set_admin`, which change the state of the contract but require special privileges Getters require no authorization because they do not change the state of the @@ -52,8 +90,8 @@ the balance of the specified identity without changing it. Unprivileged mutators require authorization from some identity. The identity which must provide authorization will vary depending on the unprivileged -mutator. For example, a "grantor" can use `approve` to allow a "spender" to spend -the grantor's money up to some limit. So for approve, the grantor must provide +mutator. For example, a "grantor" can use `incr_allow` to allow a "spender" to spend +the grantor's money up to some limit. So for `incr_allow`, the grantor must provide authorization. Similarly, a "sender" can use `xfer` to send money to a "recipient". So for `xfer`, the sender must provide authorization. @@ -128,116 +166,10 @@ token.mint( ); ``` -## Interacting with classic Stellar assets - -Token contract is the only way to interact with 'classic' Stellar assets in -Soroban. 'Classic' assets include native Stellar token (lumens) and all the -existing trustlines. - -For every 'classic' asset exactly one respective token contract can be deployed -via `create_token_from_asset` host function. The resulting token will have a -deterministic identifier. The issuer of the asset will be the administrator of -the deployed contract. Native Stellar token doesn't have an administrator. - -After the contract has been deployed the users can use `import` function to move -part of their existing balance to the contract or `export` to move the token -balance back to their 'classic' balance. Otherwise, the token will behave in -exactly the same way as any other token, i.e. users that don't have a -corresponding trustline or even a Stellar account can still use it (with the -exception of the `import`/`export` functions). - ## Contract Interface -This interface can be found in the [SDK](https://github.com/stellar/rs-soroban-sdk/blob/47895a87b98a2fb8dd882839df7abde03f6c7fc6/soroban-token-spec/src/lib.rs#L27). It -extends the common [token interface](../common-interfaces/token.mdx) with -`import`/`export` functions for classic asset interactions. - -```rust -// The metadata used to initialize token (doesn't apply to contracts representing -// 'classic' Stellar assets). -pub struct TokenMetadata { - pub name: Bytes, - pub symbol: Bytes, - pub decimals: u32, -} - -// Initializes a 'smart-only' token by setting its admin and metadata. -// Tokens that represent 'classic' Stellar assets don't need to call this, as -// their metadata is inherited from the existing assets. -fn init(env: Env, admin: Identifier, metadata: TokenMetadata); - -// Functions that apply on for tokens representing classic assets. - -// Moves the `amount` from classic asset balance to the token balance of `id` -// user. -// `id` must be a classic Stellar account (i.e. an account invoker or signature -// signed by an account). -fn import(env: Env, id: Signature, nonce: i128, amount: i64); - -// Moves the `amount` from token balance to the classic asset balance of `id` -// user. -// `id` must be a classic Stellar account (i.e. an account invoker or signature -// signed by an account). -fn export(env: Env, id: Signature, nonce: i128, amount: i64); - -// Admin interface -- these functions are privileged - -// If "admin" is the administrator, burn "amount" from "from" -fn burn(e: Env, admin: Signature, nonce: i128, from: Identifier, amount: i128); - -// If "admin" is the administrator, mint "amount" to "to" -fn mint(e: Env, admin: Signature, nonce: i128, to: Identifier, amount: i128); - -// If "admin" is the administrator, set the administrator to "id" -fn set_admin(e: Env, admin: Signature, nonce: i128, new_admin: Identifier); - -// If "admin" is the administrator, freeze "id" -fn freeze(e: Env, admin: Signature, nonce: i128, id: Identifier); - -// If "admin" is the administrator, unfreeze "id" -fn unfreeze(e: Env, admin: Signature, nonce: i128, id: Identifier); - -// Token Interface - -// Get the allowance for "spender" to transfer from "from" -fn allowance(e: Env, from: Identifier, spender: Identifier) -> i128; - -// Set the allowance to "amount" for "spender" to transfer from "from" -fn approve(e: Env, from: Signature, nonce: i128, spender: Identifier, amount: i128); - -// Get the balance of "id" -fn balance(e: Env, id: Identifier) -> i128; - -// Transfer "amount" from "from" to "to" -fn xfer(e: Env, from: Signature, nonce: i128, to: Identifier, amount: i128); - -// Transfer "amount" from "from" to "to", consuming the allowance of "spender" -fn xfer_from( - e: Env, - spender: Signature, - nonce: i128, - from: Identifier, - to: Identifier, - amount: i128, -); - -// Returns true if "id" is frozen -fn is_frozen(e: Env, id: Identifier) -> bool; - -// Returns the current nonce for "id" -fn nonce(e: Env, id: Identifier) -> i128; - -// Descriptive Interface - -// Get the number of decimals used to represent amounts of this token -fn decimals(e: Env) -> u32; - -// Get the name for this token -fn name(e: Env) -> Bytes; - -// Get the symbol for this token -fn symbol(e: Env) -> Bytes; -``` +This interface can be found in the [SDK](https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-token-spec/src/lib.rs). It +extends the common [token interface](../common-interfaces/token.mdx). ## Interacting with the token contract in tests diff --git a/docs/common-interfaces/token.mdx b/docs/common-interfaces/token.mdx index 51e26490..1bbccb95 100644 --- a/docs/common-interfaces/token.mdx +++ b/docs/common-interfaces/token.mdx @@ -3,7 +3,7 @@ sidebar_position: 1 title: Token Interface --- -Token contracts, including the built-in token and example token implementations +Token contracts, including the Stellar Asset Contract and example token implementations expose the following common interface. Tokens deployed on Soroban can implement any interface they choose, however, @@ -12,16 +12,13 @@ built to support Soroban's built-in tokens. ```rust pub trait Contract { - /// Sets the administrator to "admin" and metadata. - fn init(env: soroban_sdk::Env, admin: soroban_auth::Identifier, metadata: TokenMetadata); - // -------------------------------------------------------------------------------- // Admin interface – privileged functions. // -------------------------------------------------------------------------------- - /// If "admin" is the administrator, burn "amount" from "from". - /// Emit event with topics = ["burn", from: Identifier, to: Identifier], data = [amount: i128] - fn burn( + /// If "admin" is the administrator, clawback "amount" from "from". "amount" is burned. + /// Emit event with topics = ["clawback", from: Identifier, to: Identifier], data = [amount: i128] + fn clawback( env: soroban_sdk::Env, admin: soroban_auth::Signature, nonce: i128, @@ -48,22 +45,15 @@ pub trait Contract { new_admin: soroban_auth::Identifier, ); - /// If "admin" is the administrator, freeze "id". - /// Emit event with topics = ["freeze", admin: Identifier], data = [id: Identifier] - fn freeze( - env: soroban_sdk::Env, - admin: soroban_auth::Signature, - nonce: i128, - id: soroban_auth::Identifier, - ); - - /// If "admin" is the administrator, unfreeze "id". - /// Emit event with topics = ["unfreeze", admin: Identifier], data = [id: Identifier] - fn unfreeze( + /// If "admin" is the administrator, set the authorize state of "id" to "authorize". + /// If "authorize" is true, "id" should be able to use its balance. + /// Emit event with topics = ["set_auth", admin: Identifier, id: Identifier], data = [authorize: bool] + fn set_auth( env: soroban_sdk::Env, admin: soroban_auth::Signature, nonce: i128, id: soroban_auth::Identifier, + authorize: bool, ); // -------------------------------------------------------------------------------- @@ -77,9 +67,20 @@ pub trait Contract { spender: soroban_auth::Identifier, ) -> i128; - /// Set the allowance to "amount" for "spender" to transfer from "from". - /// Emit event with topics = ["approve", from: Identifier, spender: Identifier], data = [amount: i128] - fn approve( + /// Increase the allowance by "amount" for "spender" to transfer/burn from "from". + /// Emit event with topics = ["incr_allow", from: Identifier, spender: Identifier], data = [amount: i128] + fn incr_allow( + env: soroban_sdk::Env, + from: soroban_auth::Signature, + nonce: i128, + spender: soroban_auth::Identifier, + amount: i128, + ); + + /// Decrease the allowance by "amount" for "spender" to transfer/burn from "from". + /// If "amount" is greater than the current allowance, set the allowance to 0. + /// Emit event with topics = ["decr_allow", from: Identifier, spender: Identifier], data = [amount: i128] + fn decr_allow( env: soroban_sdk::Env, from: soroban_auth::Signature, nonce: i128, @@ -90,6 +91,11 @@ pub trait Contract { /// Get the balance of "id". fn balance(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> i128; + /// Get the spendable balance of "id". This will return the same value as balance() + /// unless this is called on the Stellar Asset Contract, in which case this can + /// be less due to reserves/liabilities. + fn spendable(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> i128; + /// Transfer "amount" from "from" to "to. /// Emit event with topics = ["transfer", from: Identifier, to: Identifier], data = [amount: i128] fn xfer( @@ -111,8 +117,27 @@ pub trait Contract { amount: i128, ); - // Returns true if "id" is frozen. - fn is_frozen(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> bool; + /// Burn "amount" from "from". + /// Emit event with topics = ["burn", from: Identifier], data = [amount: i128] + fn burn( + env: soroban_sdk::Env, + from: soroban_auth::Signature, + nonce: i128, + amount: i128, + ); + + /// Burn "amount" from "from", consuming the allowance of "spender". + /// Emit event with topics = ["burn", from: Identifier], data = [amount: i128] + fn burn_from( + env: soroban_sdk::Env, + spender: soroban_auth::Signature, + nonce: i128, + from: soroban_auth::Identifier, + amount: i128, + ); + + // Returns true if "id" is authorized to use its balance. + fn authorized(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> bool; // Returns the current nonce for "id". fn nonce(env: soroban_sdk::Env, id: soroban_auth::Identifier) -> i128; @@ -133,17 +158,7 @@ pub trait Contract { ``` Most types that a token implementation utilizes are provided by the -[soroban-sdk] and [soroban-auth] crates. The following type is also used during -initialization. - -```rust -#[soroban_sdk::contracttype] -pub struct TokenMetadata { - pub name: soroban_sdk::Bytes, - pub symbol: soroban_sdk::Bytes, - pub decimals: u32, -} -``` +[soroban-sdk] and [soroban-auth] crates. [soroban-sdk]: ../SDKs/rust [soroban-auth]: ../SDKs/rust-auth From 647137a2fccdf72a2e3d91a550bdc3264db3e739 Mon Sep 17 00:00:00 2001 From: Siddharth Suresh Date: Thu, 5 Jan 2023 09:46:57 -0800 Subject: [PATCH 20/22] Add deployment section for the SAC --- docs/built-in-contracts/token.mdx | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/built-in-contracts/token.mdx b/docs/built-in-contracts/token.mdx index 6cf8a497..c9f54aba 100644 --- a/docs/built-in-contracts/token.mdx +++ b/docs/built-in-contracts/token.mdx @@ -27,17 +27,21 @@ The SAC implements the [token interface](../common-interfaces/token.mdx), which similar to the widely used ERC-20 token standard. This should make it easier for existing smart contract developers to get started on Stellar. +## Deployment + +For every 'classic' asset exactly one respective Stellar Asset Contract can be +deployed. It can be deployed using the `InvokeHostFunctionOp` with +`HOST_FUNCTION_TYPE_CREATE_CONTRACT` and `CONTRACT_ID_FROM_ASSET` specified +[here](../tutorials/invoking-contracts-with-transactions). The resulting token +will have a deterministic identifier, which will be the sha256 hash of +`HashIDPreimage::ENVELOPE_TYPE_CONTRACT_ID_FROM_ASSET` xdr specified +[here](https://github.com/stellar/stellar-xdr/blob/026c9cd074bdb28ddde8ee52f2a4502d9e518a09/Stellar-transaction.x#L637). + ## Interacting with classic Stellar assets The Stellar Asset Contract is the only way to interact with 'classic' Stellar assets in Soroban. 'Classic' assets include native Stellar token (lumens) and all the -existing trustlines. - -For every 'classic' asset exactly one respective token contract can be deployed. -It can be deployed using the `InvokeHostFunctionOp` with -`HOST_FUNCTION_TYPE_CREATE_CONTRACT` and `CONTRACT_ID_FROM_ASSET` specified -[here](../tutorials/invoking-contracts-with-transactions). The resulting token -will have a deterministic identifier. The issuer of the asset will be the +existing trustlines. The issuer of the asset will be the administrator of the deployed contract. Because the the Native Stellar token doesn't have an issuer, it will not have an administrator either. It also cannot be burned. From 2f6047214c601f95de5fff91433c68c28bbb5aac Mon Sep 17 00:00:00 2001 From: Siddharth Suresh Date: Thu, 5 Jan 2023 17:22:30 -0800 Subject: [PATCH 21/22] Token clarifications --- docs/built-in-contracts/token.mdx | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/built-in-contracts/token.mdx b/docs/built-in-contracts/token.mdx index c9f54aba..b5044e9a 100644 --- a/docs/built-in-contracts/token.mdx +++ b/docs/built-in-contracts/token.mdx @@ -51,9 +51,10 @@ trustline balance. There are some differences depending on if you are using a classic account identifier vs a non-account identifier like a contract. - Using `Identifier::Account` - - The balance must exist in a trustline or an account. This means the contract - will not store the balance in ContractData. If the trustline or account is - missing, any function that tries to interact with that balance will fail. + - The balance must exist in a trustline (or an account for the native balance). + This means the contract will not store the balance in ContractData. If the + trustline or account is missing, any function that tries to interact with + that balance will fail. - Classic trustline semantics will be followed. - Transfers will only succeed if the corresponding trustline(s) have the `AUTHORIZED_FLAG` set. @@ -67,10 +68,14 @@ classic account identifier vs a non-account identifier like a contract. set to avoid having to pull offers and redeeming pool shares. - Transfers to the issuer account will burn the token, while transfers from the issuer account will mint. - - Trustline balances are stored in a 64-bit signed integer. + - Trustline balances are stored in a 64-bit signed integer even though the + interface accepts 128-bit signed integers. Any operation that attempts to + send or recieve an amount more than the maximum amount that can be + represented by a 64-bit signed integer will fail. - Using `Identifier::Ed25519` or `Identifier::Contract` - The balance and authorization state will be stored in ContractData, as opposed to a trustline. + - `AUTH_REVOCABLE` is not required to be set on the issuer to deauthorize a balance. - These balances are stored in a 128-bit signed integer. ## Authorization semantics From 4a5a17df057e6aa238b581e80b7dc77320814144 Mon Sep 17 00:00:00 2001 From: Siddharth Suresh Date: Fri, 6 Jan 2023 11:33:14 -0800 Subject: [PATCH 22/22] Update outdated token terminology --- .../{token.mdx => stellar-asset-contract.mdx} | 2 +- docs/faq.mdx | 19 +++++++++---------- .../invoking-contracts-with-transactions.mdx | 2 +- 3 files changed, 11 insertions(+), 12 deletions(-) rename docs/built-in-contracts/{token.mdx => stellar-asset-contract.mdx} (99%) diff --git a/docs/built-in-contracts/token.mdx b/docs/built-in-contracts/stellar-asset-contract.mdx similarity index 99% rename from docs/built-in-contracts/token.mdx rename to docs/built-in-contracts/stellar-asset-contract.mdx index b5044e9a..5a6060f6 100644 --- a/docs/built-in-contracts/token.mdx +++ b/docs/built-in-contracts/stellar-asset-contract.mdx @@ -10,7 +10,7 @@ The Stellar Asset Contract is an implementation of [CAP-46-6 Smart Contract Stan [CAP-46-6 Smart Contract Standardized Asset]: https://stellar.org/protocol/cap-46-06 :::caution -The token contract is in early development, has not been audited, and is +The Stellar Asset Contract is in early development, has not been audited, and is intended for use in development and testing only at this stage. Report issues [here](https://github.com/stellar/soroban-token-contract/issues/new/choose). ::: diff --git a/docs/faq.mdx b/docs/faq.mdx index 34fca461..7b69ad19 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -17,12 +17,11 @@ A Soroban contract can be invoked by submitting a transaction that contains the Yes. Stellar accounts are shared with Soroban. Smart contacts have access to Stellar account signer configuration and know the source account that directly invoked them in a transaction. Check out the Auth and Advanced Auth examples for more information. ### Can Soroban contracts interact with Stellar Assets? -Yes. Soroban contains a built-in token contract that is able to import a balance from a Stellar trust line into an equivalent Soroban balance and also to export it back to the Stellar trust line. Check out the built-in token for more information on token capabilities, and the token interface for building your own tokens with custom behaviors. -*Note 1: This means that one account can simultaneously have two balances of the same asset: once in a Stellar trust line and one in a Soroban token balance. This bears some similarity to the relationship between ETH and WETH on Ethereum.* -*Note 2: Tokens that have been issued on Soroban can not be exported to a Stellar trust line.* +Yes. Soroban contains a built-in Stellar Asset Contract that is able to interact +with classic trustlines. Read more about this [here](built-in-contracts/stellar-asset-contract.mdx). -### Do Issuers of Stellar Assets maintain their authorization over an asset that has been imported to Soroban? (AUTH_REQUIRED, AUTH_REVOCABLE, AUTH_CLAWBACK) -Yes. Issuers retain the same level of control on Soroban as they have on Classic . This functionality is accessible through a set of admin functions (freeze, burn) on the built in Soroban token contract. +### Do Issuers of Stellar Assets maintain their authorization over an asset that has been sent to a non-account identifer in Soroban? (AUTH_REQUIRED, AUTH_REVOCABLE, AUTH_CLAWBACK) +Yes. Issuers retain the same level of control on Soroban as they have on Classic. This functionality is accessible through a set of admin functions (clawback, set_auth) on the built-in Stellar Asset Contract. ### Can Soroban contracts interact with any other Stellar operations? No. Aside from the interactions with Accounts and Assets as mentioned above. This means that Soroban contracts can not interact with SDEX, AMMs, Claimable Balances or Sponsorships. @@ -30,11 +29,11 @@ No. Aside from the interactions with Accounts and Assets as mentioned above. Thi ### Does the Stellar base reserve apply to Soroban contracts? No. Soroban has a different fee structure and ledger entries that are allocated by Soroban contracts do not add to an account's required minimal balance. -### Should I issue my token as a Stellar Asset or a Soroban token? -We recommend, to the extent possible, issuing tokens as Stellar assets. These tokens will benefit from being interopable with the existing ecosystem of tools available in the Stellar ecosystem, and will be usable on Soroban through import/export functionality. - -### How should Wallets handle Accounts having a Stellar and Soroban balance? -Best practices are still being explored. At this time we recommend: (1) displaying separate balances for Soroban and Stellar Assets, (2) allowing users to import/export between them and (3) executing payments based on the origin: Stellar payments for trust lines and Soroban token transfers for Soroban token balances +### Should I issue my token as a Stellar Asset or a custom Soroban token? +We recommend, to the extent possible, issuing tokens as Stellar assets. These +tokens will benefit from being interopable with the existing ecosystem of tools +available in the Stellar ecosystem, as well as being more performant because the +Stellar Asset Contract is built into the host. ### Haven't found what you're looking for? Join #soroban on the Stellar developer discord diff --git a/docs/tutorials/invoking-contracts-with-transactions.mdx b/docs/tutorials/invoking-contracts-with-transactions.mdx index ce480a32..3d8aafff 100644 --- a/docs/tutorials/invoking-contracts-with-transactions.mdx +++ b/docs/tutorials/invoking-contracts-with-transactions.mdx @@ -11,7 +11,7 @@ operations: - Invoke contract functions. - Install WASM of the new contracts. - Deploy new contracts using the installed WASM or built-in implementations ( - this currently includes only the [token contract](../built-in-contracts/token.mdx)). + this currently includes only the [token contract](../built-in-contracts/stellar-asset-contract.mdx)). [`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli