Merge dev docs to main (#316)

* proposed auth-next support for simulateTransaction method * Add note about multiple results * auth is an array * Updated example docs for Auth Next. (#306) * Updated example docs for Auth Next. * Update token documentation for Auth Next (#307) * Update token doc to use auth next. * Add AUTH_REQUIRED section * Mention set_auth and link to classic docs * feat: update for upcoming CLI version * feat: CLI reference page * Update optimize contracts section (#310) * Update hello-world.mdx * Update hello-world.mdx * don't need to manually install wasm-opt via binaryen * remove the -Z flags * More Auth Next docs updates (#311) * Remove rust-auth.mdx * Update authorization docs and `Address` type info. * Added auth info to transactions doc. * Added a document about migrating to auth next. * Add some high-level docs for Auth Next preflight (#312) * Add some preflight information for Auth Next * Update docs/reference/command-line.mdx * Update docs/reference/releases.mdx * Update docs/reference/releases.mdx * Update simulateTransaction.mdx * Update examples to point to 0.6.0 * Update releases page to current state * Add change log for cli and rpc * Added a note on the breaking auth changes to the release notes. (#315) --------- Co-authored-by: Paul Bellamy <[email protected]> Co-authored-by: Siddharth Suresh <[email protected]> Co-authored-by: Chad Ostrowski <[email protected]> Co-authored-by: Willem Wyndham <[email protected]> Co-authored-by: Tyler van der Hoeven <[email protected]> Co-authored-by: Paul Bellamy <[email protected]>
stellar-deprecated · Feb 15, 2023 · ad0a0dd · ad0a0dd
1 parent d81cf29
commit ad0a0dd
Show file tree

Hide file tree

Showing 34 changed files with 1,872 additions and 1,274 deletions.
diff --git a/api/methods/simulateTransaction.mdx b/api/methods/simulateTransaction.mdx
@@ -14,9 +14,10 @@ Submit a trial contract invocation to get back return values, expected ledger fo
   - `cost`: `<object>` - Information about the fees expected, instructions used, etc.
     - `cpuInsns`: `<string>` - Stringified-number of the total cpu instructions consumed by this transaction
     - `memBytes`: `<string>` - Stringified-number of the total memory bytes allocated by this transaction
-  - `footprint`: `<xdr.LedgerFootprint>` -Array of ledger keys expected to be written by this transaction. (serialized in base64)
-  - `results`: `<object[]>` - If error is present then results will not be in the response
-    - `xdr`: `<xdr.ScVal>` - (optional) Only present on success. xdr-encoded return value of the contract call
+  - `results`: `<object[]>` - If error is present then results will not be in the response. There will be one results object for each operation in the transaction.
+    - `xdr`: `<xdr.ScVal>` - (optional) Only present on success. xdr-encoded return value of the contract call operation.
+    - `footprint`: `<xdr.LedgerFootprint>` - The contract data ledger keys which were accessed when simulating this operation. (serialized in a base64 string)
+    - `auth`: `<xdr.ContractAuth[]>` - Per-address authorizations recorded when simulating this operation. (an array of serialized base64 strings)
   - `latestLedger`: `<string>` - Stringified-number of the current latest ledger observed by the node when this response was generated.
   - `error`: `<string>` - (optional) only present if the transaction failed. This field will include more details from `stellar-core` about why the invoke host function call failed.
 
@@ -46,10 +47,11 @@ The example transaction below invokes the `increment` function from the [`increm
   "result": {
     "results": [
       {
-        "xdr": "AAAAAQAAAAY="
+        "xdr": "AAAAAQAAAAY=",
+        "footprint": "AAAAAgAAAAYb+s4jp1nFUXRjGY7RSklpy0p3TKfST1Sy18UKgLyqiQAAAAMAAAADAAAAB9QqWUc9AUjduz5qrbJgYb/gACScB4Jq7yTT6x0QJfZfAAAAAQAAAAYb+s4jp1nFUXRjGY7RSklpy0p3TKfST1Sy18UKgLyqiQAAAAUAAAAHQ09VTlRFUgA=",
+        "auth": "... TODO: Generate a plausible xdr.ContractAuth ..."
       }
     ],
-    "footprint": "AAAAAgAAAAYb+s4jp1nFUXRjGY7RSklpy0p3TKfST1Sy18UKgLyqiQAAAAMAAAADAAAAB9QqWUc9AUjduz5qrbJgYb/gACScB4Jq7yTT6x0QJfZfAAAAAQAAAAYb+s4jp1nFUXRjGY7RSklpy0p3TKfST1Sy18UKgLyqiQAAAAUAAAAHQ09VTlRFUgA=",
     "cost": {
       "cpuInsns": "163642",
       "memBytes": "1506"
@@ -59,4 +61,4 @@ The example transaction below invokes the `increment` function from the [`increm
 }
 ```
 
-[`increment` example contract]: /docs/getting-started/storing-data
+[`increment` example contract]: /docs/getting-started/storing-data
diff --git a/docs/getting-started/deploy-to-a-local-network.mdx b/docs/getting-started/deploy-to-a-local-network.mdx
@@ -52,7 +52,7 @@ curl "http://localhost:8000/friendbot?addr=G..."
 Once you have an account on the network, we'll use the code we wrote in [Write a Contract] and the resulting `.wasm` file we built in [Build] as our contract to deploy. Run the following commands to deploy the contract to the network. Use the `S...` key as the secret key.
 
 ```sh
-soroban deploy \
+soroban contract deploy \
     --wasm target/wasm32-unknown-unknown/release/[project-name].wasm \
     --secret-key S... \
     --rpc-url http://localhost:8000/soroban/rpc \
@@ -74,13 +74,14 @@ cd4dae2c409c433b1e1d83994a20214d3e5f60bdd3a817978d8aa7c797864313
 Using the contract ID that was outputted, use the [`soroban-cli`] to invoke the `hello` function with a single argument `friend`.
 
 ```sh
-soroban invoke \
+soroban contract invoke \
     --id cd4dae2c409c433b1e1d83994a20214d3e5f60bdd3a817978d8aa7c797864313 \
     --secret-key S... \
     --rpc-url http://localhost:8000/soroban/rpc \
     --network-passphrase 'Standalone Network ; February 2017' \
     --fn hello \
-    --arg friend
+    -- \
+    --to friend
 ```
 
 The following output should appear.

diff --git a/docs/getting-started/deploy-to-futurenet.mdx b/docs/getting-started/deploy-to-futurenet.mdx
@@ -49,7 +49,7 @@ curl "https://friendbot-futurenet.stellar.org/?addr=G..."
 Once you have an account on the network, we'll use the code we wrote in [Write a Contract] and the resulting `.wasm` file we built in [Build] as our contract to deploy. Run the following commands to deploy the contract to the network. Use the `S...` key as the secret key.
 
 ```sh
-soroban deploy \
+soroban contract deploy \
     --wasm target/wasm32-unknown-unknown/release/[project-name].wasm \
     --secret-key S... \
     --rpc-url http://localhost:8000/soroban/rpc \
@@ -71,13 +71,14 @@ cd4dae2c409c433b1e1d83994a20214d3e5f60bdd3a817978d8aa7c797864313
 Using the contract ID that was outputted, use the [`soroban-cli`] to invoke the `hello` function with a single argument `friend`.
 
 ```sh
-soroban invoke \
+soroban contract invoke \
     --id cd4dae2c409c433b1e1d83994a20214d3e5f60bdd3a817978d8aa7c797864313 \
     --secret-key S... \
     --rpc-url http://localhost:8000/soroban/rpc \
     --network-passphrase 'Test SDF Future Network ; October 2022' \
     --fn hello \
-    --arg friend
+    -- \
+    --to friend
 ```
 
 The following output should appear.

diff --git a/docs/getting-started/hello-world.mdx b/docs/getting-started/hello-world.mdx
@@ -328,14 +328,15 @@ It's also possible to run a contract on a fully featured local network. See [Dep
 
 :::
 
-Using the code we wrote in [Write a Contract] and the resulting `.wasm` file we built in [Build] run the following command to invoke the `hello` function with a single argument `friend`.
+Using the code we wrote in [Write a Contract] and the resulting `.wasm` file we built in [Build], run the following command to invoke the `hello` function. Here we're setting the `to` argument to `friend`:
 
 ```sh
-soroban invoke \
+soroban contract invoke \
     --wasm target/wasm32-unknown-unknown/release/[project-name].wasm \
     --id 1 \
     --fn hello \
-    --arg friend
+    -- \
+    --to friend
 ```
 
 The following output should appear.
@@ -344,84 +345,32 @@ The following output should appear.
 ["Hello", "friend"]
 ```
 
-[Write a Contract]: #write-a-contract
-[Deploy to a Local Network]: deploy-to-a-local-network
-[Build]: #build
-[`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli
+:::info The `--` double-dash is required!
 
-## Optimizing Builds
+This is a general [CLI pattern](https://unix.stackexchange.com/questions/11376/what-does-double-dash-mean) used by other commands like [cargo run](https://doc.rust-lang.org/cargo/commands/cargo-run.html). Everything after the `--`, sometimes called [slop](https://github.com/clap-rs/clap/issues/971), is passed to a child process. In this case, `soroban contract invoke` builds an _implicit CLI_ on-the-fly for the `hello` method in your contract. It can do this because Soroban SDK embeds your contract's schema / interface types right in the `.wasm` file that gets deployed on-chain. Try this, too:
 
-Building optimized contracts to be as small as possible requires some additional tools, and requires installing the `nightly` Rust toolchain and `wasm-opt`.
-
-:::tip
-
-Building optimized contracts is only necessary when deploying to a network with fees or when analyzing and profiling a contract to get it as small as possible. If you're just starting out writing a contract, these steps are not necessary. See [Build] for details on how to build for development.
+    soroban contract invoke ... --fn hello -- --help
 
 :::
 
-[Build]: #build
-
-### Install Rust `nightly`
-
-To install the nightly Rust toolchain use [`rustup`].
-
-[`rustup`]: ../getting-started/setup#install-rust
-
-```sh
-rustup install nightly
-rustup target add --toolchain nightly wasm32-unknown-unknown
-rustup component add --toolchain nightly rust-src
-```
-
-### Install `wasm-opt`
-
-To install `wasm-opt`, install [`binaryen`]. Depending on your operating system there may be different ways to install it.
-
-[`binaryen`]: https://github.com/WebAssembly/binaryen
-
-<Tabs>
-<TabItem value="macos" label="macOS" default>
-
-```sh
-brew install binaryen
-```
-
-</TabItem>
-<TabItem value="linux" label="Linux">
+## Optimizing Builds
 
-For distributions that use `apt`:
+Use `soroban contract optimize` to further minimize the size of the `.wasm`.
 
 ```sh
-sudo apt install binaryen
+soroban contract optimize \
+    --wasm target/wasm32-unknown-unknown/release/first_project.wasm
 ```
 
-For other distributions see:
-https://github.com/WebAssembly/binaryen/releases
-
-</TabItem>
-<TabItem value="windows" label="Windows">
-
-For install options see: https://github.com/WebAssembly/binaryen/releases
-
-</TabItem>
-</Tabs>
-
-### Build with `nightly` and `wasm-opt`
+This will optimize and output a new `first_project.optimized.wasm` file in the same location as the input `.wasm`.
 
-Build your contract using nightly. The additional options instruct the compiler to remove unnecessary information from the contract.
+:::tip
 
-```sh
-cargo +nightly build \
-    --target wasm32-unknown-unknown \
-    --release \
-    -Z build-std=std,panic_abort \
-    -Z build-std-features=panic_immediate_abort
-```
+Building optimized contracts is only necessary when deploying to a network with fees or when analyzing and profiling a contract to get it as small as possible. If you're just starting out writing a contract, these steps are not necessary. See [Build] for details on how to build for development.
 
-Use `wasm-opt` to further minimize the size of the `.wasm`.
+:::
 
-```sh
-wasm-opt -Oz \
-    target/wasm32-unknown-unknown/release/first_project.wasm \
-    -o target/wasm32-unknown-unknown/release/first_project_optimized.wasm
-```
+[Write a Contract]: #write-a-contract
+[Deploy to a Local Network]: deploy-to-a-local-network
+[Build]: #build
+[`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli
diff --git a/docs/getting-started/setup.mdx b/docs/getting-started/setup.mdx
@@ -56,7 +56,7 @@ contract will execute on network, however in a local sandbox.
 Install the Soroban CLI using `cargo install`.
 
 ```sh
-cargo install --locked --version 0.4.0 soroban-cli
+cargo install --locked --version 0.5.0 soroban-cli
 ```
 
 :::info
@@ -76,7 +76,8 @@ soroban
 
 ```
 ❯ soroban
-soroban 0.4.0
+soroban
+soroban 0.5.0
 https://soroban.stellar.org
 
 USAGE:
@@ -86,16 +87,11 @@ OPTIONS:
     -h, --help    Print help information
 
 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
+    contract      Tools for smart contract developers
+    config        Read and update config
     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
+    events        Watch the network for contract events
+    lab           Experiment with early features and expert tools
     version       Print version information
     completion    Print shell completion code for the specified shell
 ```

diff --git a/docs/getting-started/storing-data.mdx b/docs/getting-started/storing-data.mdx
@@ -6,18 +6,18 @@ title: 2. Storing Data
 The [increment example] demonstrates how to write a simple contract that stores 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.4.2
+[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.6.0
 
-[increment example]: https://github.com/stellar/soroban-examples/tree/v0.4.2/increment
+[increment example]: https://github.com/stellar/soroban-examples/tree/v0.6.0/increment
 
 ## Run the Example
 
-First go through the [Setup] process to get your development environment configured, then clone the `v0.4.2` tag of `soroban-examples` repository:
+First go through the [Setup] process to get your development environment configured, then clone the `v0.6.0` tag of `soroban-examples` repository:
 
 [Setup]: setup.mdx
 
 ```
-git clone -b v0.4.2 https://github.com/stellar/soroban-examples
+git clone -b v0.6.0 https://github.com/stellar/soroban-examples
 ```
 
 Or, skip the development environment setup and open this example in [Gitpod][oigp].
@@ -62,7 +62,7 @@ impl IncrementContract {
 }
 ```
 
-Ref: https://github.com/stellar/soroban-examples/tree/v0.4.2/increment
+Ref: https://github.com/stellar/soroban-examples/tree/v0.6.0/increment
 
 ## How it Works
 
@@ -162,7 +162,7 @@ A `.wasm` file should be outputted in the `../target` directory:
 If you have [`soroban-cli`] installed, you can invoke contract functions in the WASM using it.
 
 ```sh
-soroban invoke \
+soroban contract invoke \
     --wasm ../target/wasm32-unknown-unknown/release/soroban_increment_contract.wasm \
     --id 1 \
     --fn increment
@@ -177,7 +177,7 @@ The following output should occur using the code above.
 Rerun the invoke with the `--footprint` option to view the [footprint] of the invocation, which is the ledger entries that the contract will have read or written to.
 
 ```sh
-soroban invoke \
+soroban contract invoke \
     --wasm ../target/wasm32-unknown-unknown/release/soroban_increment_contract.wasm \
     --id 1 \
     --fn increment \
@@ -201,7 +201,7 @@ Run it a few more times to watch the count change.
 Use the `soroban` to inspect what the counter is after a few runs.
 
 ```sh
-soroban read --id 1 --key COUNTER
+soroban contract read --id 1 --key COUNTER
 ```
 
 [`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli
diff --git a/docs/how-to-guides/alloc.mdx b/docs/how-to-guides/alloc.mdx
@@ -1,25 +1,25 @@
 ---
-sidebar_position: 15
+sidebar_position: 10
 title: Allocator
 ---
 
 The [allocator example] demonstrates how to utilize the allocator feature when writing a contract.
 
-[allocator example]: https://github.com/stellar/soroban-examples/tree/v0.4.2/alloc
+[allocator example]: https://github.com/stellar/soroban-examples/tree/v0.6.0/alloc
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp]
-[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.4.2
+[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.6.0
 
 The `soroban-sdk` crate provides a lightweight bump-pointer allocator which can be used to emulate heap memory allocation in a WASM smart contract.
 
 ## Run the Example
 
-First go through the [Setup] process to get your development environment configured, then clone the `v0.4.2` tag of `soroban-examples` repository:
+First go through the [Setup] process to get your development environment configured, then clone the `v0.6.0` tag of `soroban-examples` repository:
 
 [setup]: ../getting-started/setup.mdx
 
 ```
-git clone -b v0.4.2 https://github.com/stellar/soroban-examples
+git clone -b v0.6.0 https://github.com/stellar/soroban-examples
 ```
 
 Or, skip the development environment setup and open this example in [Gitpod][oigp].
@@ -77,7 +77,7 @@ impl AllocContract {
 }
 ```
 
-Ref: https://github.com/stellar/soroban-examples/tree/v0.4.2/alloc
+Ref: https://github.com/stellar/soroban-examples/tree/v0.6.0/alloc
 
 ## How it Works
 

diff --git a/docs/how-to-guides/atomic-multi-swap.mdx b/docs/how-to-guides/atomic-multi-swap.mdx
@@ -0,0 +1,20 @@
+---
+sidebar_position: 12
+title: Batched Atomic Swaps
+---
+
+The [atomic swap batching example] swaps a pair of tokens between the two groups
+of users that authorized the `swap` operation from the [Atomic Swap] example. 
+
+This contract basically batches the multiple swaps while following some simple
+rules to match the swap participants.
+
+Follow the comments in the code for more information.
+
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp]
+
+[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.6.0
+
+[Atomic Swap]: atomic-swap.mdx
+
+[atomic swap batching example]: https://github.com/stellar/soroban-examples/tree/v0.6.0/atomic_multiswap