From 50e0f1950298d6d5ba4437f1e6d18ee5a1239a78 Mon Sep 17 00:00:00 2001 From: Blaine Heffron Date: Mon, 9 Sep 2024 16:55:01 -0400 Subject: [PATCH 1/6] Cookbook documentation (#1541) * add cookbook file * cookbook entries for testing and copying to docs * test for cli guide entries * formatting * fixes remaining commands * fmt --------- Co-authored-by: Willem Wyndham --- .../soroban-test/tests/it/integration.rs | 1 + .../tests/it/integration/cookbook.rs | 292 ++++++++++++++++++ .../soroban-test/tests/it/integration/util.rs | 2 +- .../src/commands/contract/extend.rs | 1 - cookbook/contract-lifecycle.mdx | 61 ++++ cookbook/deploy-contract.mdx | 14 + cookbook/deploy-stellar-asset-contract.mdx | 55 ++++ cookbook/extend-contract-instance.mdx | 24 ++ cookbook/extend-contract-storage.mdx | 37 +++ cookbook/extend-contract-wasm.mdx | 35 +++ cookbook/install-deploy.mdx | 14 + cookbook/install-wasm.mdx | 20 ++ cookbook/payments-and-assets.mdx | 59 ++++ cookbook/restore-contract-instance.mdx | 15 + cookbook/restore-contract-storage.mdx | 33 ++ 15 files changed, 661 insertions(+), 2 deletions(-) create mode 100644 cmd/crates/soroban-test/tests/it/integration/cookbook.rs create mode 100644 cookbook/contract-lifecycle.mdx create mode 100644 cookbook/deploy-contract.mdx create mode 100644 cookbook/deploy-stellar-asset-contract.mdx create mode 100644 cookbook/extend-contract-instance.mdx create mode 100644 cookbook/extend-contract-storage.mdx create mode 100644 cookbook/extend-contract-wasm.mdx create mode 100644 cookbook/install-deploy.mdx create mode 100644 cookbook/install-wasm.mdx create mode 100644 cookbook/payments-and-assets.mdx create mode 100644 cookbook/restore-contract-instance.mdx create mode 100644 cookbook/restore-contract-storage.mdx diff --git a/cmd/crates/soroban-test/tests/it/integration.rs b/cmd/crates/soroban-test/tests/it/integration.rs index 8e2bb89a4..3e8521869 100644 --- a/cmd/crates/soroban-test/tests/it/integration.rs +++ b/cmd/crates/soroban-test/tests/it/integration.rs @@ -1,4 +1,5 @@ mod bindings; +mod cookbook; mod custom_types; mod dotenv; mod fund; diff --git a/cmd/crates/soroban-test/tests/it/integration/cookbook.rs b/cmd/crates/soroban-test/tests/it/integration/cookbook.rs new file mode 100644 index 000000000..65855d775 --- /dev/null +++ b/cmd/crates/soroban-test/tests/it/integration/cookbook.rs @@ -0,0 +1,292 @@ +use predicates::prelude::*; +use soroban_cli::config::network::passphrase::LOCAL; +use soroban_test::TestEnv; +use std::fs; +use std::path::PathBuf; + +fn parse_command(command: &str) -> Vec { + command + .replace("\\\n", " ") + .split_whitespace() + .map(String::from) + .collect() +} + +async fn run_command( + sandbox: &TestEnv, + command: &str, + wasm_path: &str, + wasm_hash: &str, + source: &str, + contract_id: &str, + bob_id: &str, + native_id: &str, + key_xdr: &str, +) -> Result<(), String> { + if command.contains("export") { + return Ok(()); + } + let args = parse_command(command); + if args.is_empty() { + return Err("Empty command".to_string()); + } + if command.contains("contract asset deploy") { + return Ok(()); + } + /*if command.contains("keys generate"){ + return Ok(()); + }*/ + let cmd = args[1].clone(); + let mut modified_args: Vec = Vec::new(); + let mut skip_next = false; + + for (index, arg) in args[2..].iter().enumerate() { + if skip_next { + skip_next = false; + continue; + } + + match arg.as_str() { + "--wasm" => { + modified_args.push(arg.to_string()); + modified_args.push(wasm_path.to_string()); + skip_next = true; + } + "--wasm-hash" => { + modified_args.push(arg.to_string()); + modified_args.push(wasm_hash.to_string()); + skip_next = true; + } + "--source" | "--source-account" => { + modified_args.push(arg.to_string()); + modified_args.push(source.to_string()); + skip_next = true; + } + "--contract-id" | "--id" => { + modified_args.push(arg.to_string()); + modified_args.push(contract_id.to_string()); + skip_next = true; + } + "--network-passphrase" => { + modified_args.push(arg.to_string()); + modified_args.push(LOCAL.to_string()); + skip_next = true; + } + "--network" => { + modified_args.push(arg.to_string()); + modified_args.push("local".to_string()); + skip_next = true; + } + "--key-xdr" => { + modified_args.push(arg.to_string()); + modified_args.push(key_xdr.to_string()); + skip_next = true; + } + "" => { + modified_args.push("persistent".to_string()); + skip_next = false; + } + "" => { + modified_args.push("COUNTER".to_string()); + skip_next = false; + } + "" => { + modified_args.push(bob_id.to_string()); + skip_next = false; + } + "" => { + modified_args.push(native_id.to_string()); + skip_next = false; + } + _ => modified_args.push(arg.to_string()), + } + + // If this is the last argument, don't skip the next one + if index == args[2..].len() - 1 { + skip_next = false; + } + } + + println!("Executing command: {} {}", cmd, modified_args.join(" ")); + let result = sandbox.new_assert_cmd(&cmd).args(&modified_args).assert(); + + if command.contains("keys generate") { + result + .code(predicates::ord::eq(0).or(predicates::ord::eq(1))) + .stderr( + predicate::str::is_empty().or(predicates::str::contains("Generated new key for") + .or(predicates::str::contains("The identity") + .and(predicates::str::contains("already exists")))), + ); + } else if command.contains("contract invoke") { + result + .failure() + .stderr(predicates::str::contains("error: unrecognized subcommand")); + } else if command.contains("contract restore") { + result + .failure() + .stderr(predicates::str::contains("TxSorobanInvalid")); + } else { + result.success(); + } + + Ok(()) +} + +async fn test_mdx_file( + sandbox: &TestEnv, + file_path: &str, + wasm_path: &str, + wasm_hash: &str, + source: &str, + contract_id: &str, + bob_id: &str, + native_id: &str, + key_xdr: &str, +) -> Result<(), String> { + let content = fs::read_to_string(file_path) + .map_err(|e| format!("Failed to read file {}: {}", file_path, e))?; + + let commands: Vec<&str> = content + .split("```bash") + .skip(1) + .filter_map(|block| block.split("```").next()) + .collect(); + + println!("Testing commands from file: {}", file_path); + + for (i, command) in commands.iter().enumerate() { + println!("Running command {}: {}", i + 1, command); + run_command( + sandbox, + command, + wasm_path, + wasm_hash, + source, + contract_id, + bob_id, + native_id, + key_xdr, + ) + .await?; + } + + Ok(()) +} + +fn get_repo_root() -> PathBuf { + let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set"); + let mut path = PathBuf::from(manifest_dir); + for _ in 0..3 { + path.pop(); + } + path +} + +#[cfg(test)] +mod tests { + use soroban_test::AssertExt; + + use crate::integration::util::{deploy_hello, HELLO_WORLD}; + + use super::*; + + #[tokio::test] + async fn test_all_mdx_files() { + let sandbox = TestEnv::new(); + let wasm = HELLO_WORLD; + let wasm_path = wasm.path(); + let wasm_hash = wasm.hash().expect("should exist").to_string(); + let source = "test"; + + sandbox + .new_assert_cmd("keys") + .arg("fund") + .arg(source) + .assert() + .success(); + + sandbox + .new_assert_cmd("keys") + .arg("generate") + .arg("bob") + .assert() + .success(); + let bob_id = sandbox + .new_assert_cmd("keys") + .arg("address") + .arg("bob") + .assert() + .success() + .stdout_as_str(); + sandbox + .new_assert_cmd("contract") + .arg("asset") + .arg("deploy") + .arg("--asset") + .arg("native") + .arg("--source-account") + .arg(source) + .output() + .expect("Failed to execute command"); + let native_id = sandbox + .new_assert_cmd("contract") + .arg("id") + .arg("asset") + .arg("--asset") + .arg("native") + .arg("--source-account") + .arg(source) + .assert() + .stdout_as_str(); + let contract_id = deploy_hello(&sandbox).await; + sandbox + .invoke_with_test(&["--id", &contract_id, "--", "inc"]) + .await + .unwrap(); + let read_xdr = sandbox + .new_assert_cmd("contract") + .arg("read") + .arg("--id") + .arg(contract_id.clone()) + .arg("--output") + .arg("xdr") + .arg("--key") + .arg("COUNTER") + .arg("--source-account") + .arg(source) + .assert() + .stdout_as_str(); + let key_xdr = read_xdr.split(',').next().unwrap_or("").trim(); + let repo_root = get_repo_root(); + let docs_dir = repo_root.join("cookbook"); + if !docs_dir.is_dir() { + panic!("docs directory not found"); + } + + for entry in fs::read_dir(docs_dir).expect("Failed to read docs directory") { + let entry = entry.expect("Failed to read directory entry"); + let path = entry.path(); + + if path.is_file() && path.extension().and_then(|s| s.to_str()) == Some("mdx") { + let file_path = path.to_str().unwrap(); + match test_mdx_file( + &sandbox, + file_path, + &wasm_path.to_str().unwrap(), + &wasm_hash, + source, + &contract_id, + &bob_id, + &native_id, + &key_xdr, + ) + .await + { + Ok(_) => println!("Successfully tested all commands in {}", file_path), + Err(e) => panic!("Error testing {}: {}", file_path, e), + } + } + } + } +} diff --git a/cmd/crates/soroban-test/tests/it/integration/util.rs b/cmd/crates/soroban-test/tests/it/integration/util.rs index c7f348e20..dec7941f6 100644 --- a/cmd/crates/soroban-test/tests/it/integration/util.rs +++ b/cmd/crates/soroban-test/tests/it/integration/util.rs @@ -94,7 +94,7 @@ pub async fn extend(sandbox: &TestEnv, id: &str, value: Option<&str>) { "--durability", "persistent", "--ledgers-to-extend", - "100000", + "100001", ]; if let Some(value) = value { args.push("--key"); diff --git a/cmd/soroban-cli/src/commands/contract/extend.rs b/cmd/soroban-cli/src/commands/contract/extend.rs index a0e563e58..5901c71b1 100644 --- a/cmd/soroban-cli/src/commands/contract/extend.rs +++ b/cmd/soroban-cli/src/commands/contract/extend.rs @@ -131,7 +131,6 @@ impl NetworkRunnable for Cmd { let network = config.get_network()?; tracing::trace!(?network); let keys = self.key.parse_keys(&config.locator, &network)?; - let network = &config.get_network()?; let client = Client::new(&network.rpc_url)?; let key = config.key_pair()?; let extend_to = self.ledgers_to_extend(); diff --git a/cookbook/contract-lifecycle.mdx b/cookbook/contract-lifecycle.mdx new file mode 100644 index 000000000..890618b51 --- /dev/null +++ b/cookbook/contract-lifecycle.mdx @@ -0,0 +1,61 @@ +--- +title: Contract Lifecycle +hide_table_of_contents: true +description: Manage the lifecycle of a Stellar smart contract using the CLI. +--- + +To manage the lifecycle of a Stellar smart contract using the CLI, follow these steps: + +1. Create an identity for Alice: + +```bash +stellar keys generate alice +``` + +2. Fund the identity: + +```bash +stellar keys fund alice +``` + +3. Deploy a contract: + +```bash +stellar contract deploy --wasm /path/to/contract.wasm --source alice --network testnet +``` + +This will display the resulting contract ID, e.g.: + +``` +CBB65ZLBQBZL5IYHDHEEPCVUUMFOQUZSQKAJFV36R7TZETCLWGFTRLOQ +``` + +To learn more about how to build contract `.wasm` files, take a look at our [getting started tutorial](https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup). + +4. Initialize the contract: + +```bash +stellar contract invoke --id --source alice --network testnet -- initialize --param1 value1 --param2 value2 +``` + +5. Invoke a contract function: + +```bash +stellar contract invoke --id --source alice --network testnet -- function_name --arg1 value1 --arg2 value2 +``` + +6. View the contract's state: + +```bash +stellar contract read --id --network testnet --source alice --durability --key +``` + +Note: `` is either `persistent` or `temporary`. `KEY` provides the key of the storage entry being read. + +7. Manage expired states: + +```bash +stellar contract extend --id --ledgers-to-extend 1000 --source alice --network testnet --durability --key +``` + +This extends the state of the instance provided by the given key to at least 1000 ledgers from the current ledger. diff --git a/cookbook/deploy-contract.mdx b/cookbook/deploy-contract.mdx new file mode 100644 index 000000000..5714ac41d --- /dev/null +++ b/cookbook/deploy-contract.mdx @@ -0,0 +1,14 @@ +--- +title: Deploy a contract from installed Wasm bytecode +hide_table_of_contents: true +description: Deploy an instance of a compiled contract that is already installed on the network. +--- + +To deploy an instance of a compiled smart contract that has already been installed onto the Stellar network, use the `stellar contract deploy` command: + +```bash +stellar contract deploy \ + --source S... \ + --network testnet \ + --wasm-hash +``` diff --git a/cookbook/deploy-stellar-asset-contract.mdx b/cookbook/deploy-stellar-asset-contract.mdx new file mode 100644 index 000000000..e3301279c --- /dev/null +++ b/cookbook/deploy-stellar-asset-contract.mdx @@ -0,0 +1,55 @@ +--- +title: Deploy the Stellar Asset Contract for a Stellar asset +hide_table_of_contents: true +description: Deploy an SAC for a Stellar asset so that it can interact with smart contracts. +--- + +The Stellar CLI can deploy a [Stellar Asset Contract] for a Stellar asset so that any Stellar smart contract can interact with the asset. + +Every Stellar asset has reserved a contract that anyone can deploy. Once deployed any contract can interact with that asset by holding a balance of the asset, receiving the asset, or sending the asset. + +Deploying the Stellar Asset Contract for a Stellar asset enables that asset for use in smart contracts. + +The Stellar Asset Contract can be deployed for any possible Stellar asset, either assets already in use on Stellar or assets that have never seen any activity. This means that the issuer doesn't need to have been created, and no one needs to be yet holding the asset on Stellar. + +To perform the deploy, use the following command: + +```bash +stellar contract asset deploy \ + --source S... \ + --network testnet \ + --asset USDC:GCYEIQEWOCTTSA72VPZ6LYIZIK4W4KNGJR72UADIXUXG45VDFRVCQTYE +``` + +The `asset` argument corresponds to the symbol and it's issuer address, which is how assets are identified on Stellar. + +The same can be done for the native [Lumens] asset: + +```bash +stellar contract asset deploy \ + --source S... \ + --network testnet \ + --asset native +``` + +:::note + +Deploying the native asset will fail on testnet or mainnet as a Stellar Asset Contract already exists. + +::: + +For any asset, the contract address can be fetched with: + +```bash +stellar contract id asset \ + --source S... \ + --network testnet \ + --asset native +``` + +[stellar asset contract]: ../../../tokens/stellar-asset-contract.mdx +[lumens]: ../../../learn/fundamentals/lumens.mdx +[sep-41]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md +[`soroban_sdk::token`]: https://docs.rs/soroban-sdk/latest/soroban_sdk/token/ +[`token::tokenclient`]: https://docs.rs/soroban-sdk/latest/soroban_sdk/token/struct.TokenClient.html +[`token::stellarassetclient`]: https://docs.rs/soroban-sdk/latest/soroban_sdk/token/struct.StellarAssetClient.html diff --git a/cookbook/extend-contract-instance.mdx b/cookbook/extend-contract-instance.mdx new file mode 100644 index 000000000..8cea14060 --- /dev/null +++ b/cookbook/extend-contract-instance.mdx @@ -0,0 +1,24 @@ +--- +title: Extend a deployed contract instance's TTL +hide_table_of_contents: true +description: Use the CLI to extend the time to live (TTL) of a contract instance. +--- + +You can use the Stellar CLI to extend the TTL of a contract instance like so: + +```bash +stellar contract extend \ + --source S... \ + --network testnet \ + --id C... \ + --ledgers-to-extend 535679 \ + --durability persistent +``` + +This example uses 535,679 ledgers as the new archival TTL. This is the maximum allowable value for this argument on the CLI. This corresponds to roughly 30 days (averaging 5 second ledger close times). + +When you extend a contract instance, this includes: + +- the contract instance itself +- any `env.storage().instance()` entries in the contract +- the contract's Wasm code diff --git a/cookbook/extend-contract-storage.mdx b/cookbook/extend-contract-storage.mdx new file mode 100644 index 000000000..afd068a1c --- /dev/null +++ b/cookbook/extend-contract-storage.mdx @@ -0,0 +1,37 @@ +--- +title: Extend a deployed contract's storage entry TTL +hide_table_of_contents: true +description: Use the CLI to extend the time to live (TTL) of a contract's persistent storage entry. +--- + +You can use the Stellar CLI to extend the TTL of a contract's persistent storage entry. For a storage entry that uses a simple `Symbol` as its storage key, you can run a command like so: + +```bash +stellar contract extend \ + --source S... \ + --network testnet \ + --id C... \ + --key COUNTER \ + --ledgers-to-extend 535679 \ + --durability persistent +``` + +This example uses 535,679 ledgers as the new archival TTL. This is the maximum allowable value for this argument on the CLI. This corresponds to roughly 30 days (averaging 5 second ledger close times). + +If your storage entry uses a more advanced storage key, such as `Balance(Address)` in a token contract, you'll need to provide the key in a base64-encoded XDR form: + +```bash +stellar contract extend \ + --source S... \ + --network testnet \ + --id C... \ + --key-xdr AAAABgAAAAHXkotywnA8z+r365/0701QSlWouXn8m0UOoshCtNHOYQAAAA4AAAAHQmFsYW5jZQAAAAAB \ + --ledgers-to-extend 535679 \ + --durability persistent +``` + +:::info + +Be sure to check out our [guide on creating XDR ledger keys](../rpc/generate-ledger-keys-python.mdx) for help generating them. + +::: diff --git a/cookbook/extend-contract-wasm.mdx b/cookbook/extend-contract-wasm.mdx new file mode 100644 index 000000000..dd581b6c9 --- /dev/null +++ b/cookbook/extend-contract-wasm.mdx @@ -0,0 +1,35 @@ +--- +title: Extend a deployed contract's Wasm code TTL +hide_table_of_contents: true +description: Use Stellar CLI to extend contract's Wasm bytecode TTL, with or without local binary. +--- + +You can use the Stellar CLI to extend the TTL of a contract's Wasm bytecode. This can be done in two forms: if you do or do not have the compiled contract locally. If you do have the compiled binary on your local machine: + +```bash +stellar contract extend \ + --source S... \ + --network testnet \ + --wasm ../relative/path/to/soroban_contract.wasm \ + --ledgers-to-extend 535679 \ + --durability persistent +``` + +This example uses 535,679 ledgers as the new archival TTL. This is the maximum allowable value for this argument on the CLI. This corresponds to roughly 30 days (averaging 5 second ledger close times). + +If you do not have the compiled binary on your local machine, you can still use the CLI to extend the bytecode TTL. You'll need to know the Wasm hash of the installed contract code: + +```bash +stellar contract extend \ + --source S... \ + --network testnet \ + --wasm-hash \ + --ledgers-to-extend 535679 \ + --durability persistent +``` + +:::info + +You can learn more about finding the correct Wasm hash for a contract instance [here (JavaScript)](../rpc/retrieve-contract-code-js.mdx) and [here (Python)](../rpc/retrieve-contract-code-python.mdx). + +::: diff --git a/cookbook/install-deploy.mdx b/cookbook/install-deploy.mdx new file mode 100644 index 000000000..3cc8e786a --- /dev/null +++ b/cookbook/install-deploy.mdx @@ -0,0 +1,14 @@ +--- +title: Install and deploy a smart contract +hide_table_of_contents: true +description: Combine the install and deploy commands in the Stellar CLI to accomplish both tasks. +--- + +You can combine the `install` and `deploy` commands of the Stellar CLI to accomplish both tasks: + +```bash +stellar contract deploy \ + --source S... \ + --network testnet \ + --wasm ../relative/path/to/soroban_contract.wasm +``` diff --git a/cookbook/install-wasm.mdx b/cookbook/install-wasm.mdx new file mode 100644 index 000000000..3c8166913 --- /dev/null +++ b/cookbook/install-wasm.mdx @@ -0,0 +1,20 @@ +--- +title: Install Wasm bytecode +hide_table_of_contents: true +description: Use the Stellar CLI to install a compiled smart contract on the ledger. +--- + +To use the Stellar CLI to install a compiled smart contract on the ledger, use the `stellar contract install` command: + +```bash +stellar contract install \ + --source S... \ + --network testnet \ + --wasm ../relative/path/to/soroban_contract.wasm +``` + +:::note + +Note this command will return the hash ID of the Wasm bytecode, rather than an address for a contract instance. + +::: diff --git a/cookbook/payments-and-assets.mdx b/cookbook/payments-and-assets.mdx new file mode 100644 index 000000000..08607af02 --- /dev/null +++ b/cookbook/payments-and-assets.mdx @@ -0,0 +1,59 @@ +--- +title: Payments and Assets +hide_table_of_contents: true +description: Send XLM, stellar classic, or a soroban asset using the Stellar CLI. +--- + +To send payments and work with assets using the Stellar CLI, follow these steps: + +1. Set your preferred network. For this guide, we will use `testnet`. A list of available networks can be found [here](https://developers.stellar.org/docs/networks) + +```bash +export STELLAR_NETWORK=testnet +``` + +By setting the `STELLAR_NETWORK` environment variable, we will not have to set the `--network` argument when using the CLI. + +2. Fund the accounts: + +```bash +stellar keys generate alice +``` + +```bash +stellar keys generate bob +``` + +```bash +stellar keys fund alice +``` + +```bash +stellar keys fund bob +``` + +3. Obtain the stellar asset contract ID: + +```bash +stellar contract id asset --asset native --source-account alice +``` + +4. Get Bob's public key: + +```bash +stellar keys address bob +``` + +5. Send 100 XLM from Alice to Bob: + +```bash +stellar contract invoke --id --source-account alice -- transfer --to --from alice --amount 100 +``` + +6. Check account balance: + +```bash +stellar contract invoke --id --source-account alice -- balance --id +``` + +For more information on the functions available to the stellar asset contract, see the [token interface code](https://developers.stellar.org/docs/tokens/token-interface#code). diff --git a/cookbook/restore-contract-instance.mdx b/cookbook/restore-contract-instance.mdx new file mode 100644 index 000000000..1380233f9 --- /dev/null +++ b/cookbook/restore-contract-instance.mdx @@ -0,0 +1,15 @@ +--- +title: Restore an archived contract using the Stellar CLI +hide_table_of_contents: true +description: Restore an archived contract instance using the Stellar CLI. +--- + +If your contract instance has been archived, it can easily be restored using the Stellar CLI. + +```bash +stellar contract restore \ + --source S... \ + --network testnet \ + --id C... \ + --durability persistent +``` diff --git a/cookbook/restore-contract-storage.mdx b/cookbook/restore-contract-storage.mdx new file mode 100644 index 000000000..0af356ccb --- /dev/null +++ b/cookbook/restore-contract-storage.mdx @@ -0,0 +1,33 @@ +--- +title: Restore archived contract data using the Stellar CLI +hide_table_of_contents: true +description: Restore archived contract storage entries using Stellar CLI. +--- + +If a contract's persistent storage entry has been archived, you can restore it using the Stellar CLI. For a storage entry that uses a simple `Symbol` as its storage key, you can run a command like so: + +```bash +stellar contract restore \ + --source S... \ + --network testnet \ + --id C... \ + --key COUNTER \ + --durability persistent +``` + +If your storage entry uses a more advanced storage key, such as `Balance(Address)` in a token contract, you'll need to provide the key in a base64-encoded XDR form: + +```bash +stellar contract restore \ + --source S... \ + --network testnet \ + --id C... \ + --key-xdr AAAABgAAAAHXkotywnA8z+r365/0701QSlWouXn8m0UOoshCtNHOYQAAAA4AAAAHQmFsYW5jZQAAAAAB \ + --durability persistent +``` + +:::info + +Be sure to check out our [guide on creating XDR ledger keys](../rpc/generate-ledger-keys-python.mdx) for help generating them. + +::: From 6b61f2d36cb1b3cc9eb97cc8956729101fd69fb8 Mon Sep 17 00:00:00 2001 From: Blaine Heffron Date: Mon, 9 Sep 2024 21:06:38 -0400 Subject: [PATCH 2/6] unifying formatting to reflect stellar-docs#1541 (#1587) --- cookbook/contract-lifecycle.mdx | 2 +- cookbook/deploy-contract.mdx | 2 +- cookbook/deploy-stellar-asset-contract.mdx | 2 +- cookbook/extend-contract-instance.mdx | 2 +- cookbook/extend-contract-storage.mdx | 2 +- cookbook/extend-contract-wasm.mdx | 2 +- cookbook/install-deploy.mdx | 2 +- cookbook/install-wasm.mdx | 2 +- cookbook/payments-and-assets.mdx | 2 +- cookbook/restore-contract-instance.mdx | 2 +- cookbook/restore-contract-storage.mdx | 2 +- 11 files changed, 11 insertions(+), 11 deletions(-) diff --git a/cookbook/contract-lifecycle.mdx b/cookbook/contract-lifecycle.mdx index 890618b51..b64262b34 100644 --- a/cookbook/contract-lifecycle.mdx +++ b/cookbook/contract-lifecycle.mdx @@ -1,7 +1,7 @@ --- title: Contract Lifecycle hide_table_of_contents: true -description: Manage the lifecycle of a Stellar smart contract using the CLI. +description: Manage the lifecycle of a Stellar smart contract using the CLI --- To manage the lifecycle of a Stellar smart contract using the CLI, follow these steps: diff --git a/cookbook/deploy-contract.mdx b/cookbook/deploy-contract.mdx index 5714ac41d..ec0accf7b 100644 --- a/cookbook/deploy-contract.mdx +++ b/cookbook/deploy-contract.mdx @@ -1,7 +1,7 @@ --- title: Deploy a contract from installed Wasm bytecode hide_table_of_contents: true -description: Deploy an instance of a compiled contract that is already installed on the network. +description: Deploy an instance of a compiled contract that is already installed on the network --- To deploy an instance of a compiled smart contract that has already been installed onto the Stellar network, use the `stellar contract deploy` command: diff --git a/cookbook/deploy-stellar-asset-contract.mdx b/cookbook/deploy-stellar-asset-contract.mdx index e3301279c..7233acc60 100644 --- a/cookbook/deploy-stellar-asset-contract.mdx +++ b/cookbook/deploy-stellar-asset-contract.mdx @@ -1,7 +1,7 @@ --- title: Deploy the Stellar Asset Contract for a Stellar asset hide_table_of_contents: true -description: Deploy an SAC for a Stellar asset so that it can interact with smart contracts. +description: Deploy an SAC for a Stellar asset so that it can interact with smart contracts --- The Stellar CLI can deploy a [Stellar Asset Contract] for a Stellar asset so that any Stellar smart contract can interact with the asset. diff --git a/cookbook/extend-contract-instance.mdx b/cookbook/extend-contract-instance.mdx index 8cea14060..3c456a39a 100644 --- a/cookbook/extend-contract-instance.mdx +++ b/cookbook/extend-contract-instance.mdx @@ -1,7 +1,7 @@ --- title: Extend a deployed contract instance's TTL hide_table_of_contents: true -description: Use the CLI to extend the time to live (TTL) of a contract instance. +description: Use the CLI to extend the time to live (TTL) of a contract instance --- You can use the Stellar CLI to extend the TTL of a contract instance like so: diff --git a/cookbook/extend-contract-storage.mdx b/cookbook/extend-contract-storage.mdx index afd068a1c..21ce9c186 100644 --- a/cookbook/extend-contract-storage.mdx +++ b/cookbook/extend-contract-storage.mdx @@ -1,7 +1,7 @@ --- title: Extend a deployed contract's storage entry TTL hide_table_of_contents: true -description: Use the CLI to extend the time to live (TTL) of a contract's persistent storage entry. +description: Use the CLI to extend the time to live (TTL) of a contract's persistent storage entry --- You can use the Stellar CLI to extend the TTL of a contract's persistent storage entry. For a storage entry that uses a simple `Symbol` as its storage key, you can run a command like so: diff --git a/cookbook/extend-contract-wasm.mdx b/cookbook/extend-contract-wasm.mdx index dd581b6c9..9c4763b92 100644 --- a/cookbook/extend-contract-wasm.mdx +++ b/cookbook/extend-contract-wasm.mdx @@ -1,7 +1,7 @@ --- title: Extend a deployed contract's Wasm code TTL hide_table_of_contents: true -description: Use Stellar CLI to extend contract's Wasm bytecode TTL, with or without local binary. +description: Use Stellar CLI to extend contract's Wasm bytecode TTL, with or without local binary --- You can use the Stellar CLI to extend the TTL of a contract's Wasm bytecode. This can be done in two forms: if you do or do not have the compiled contract locally. If you do have the compiled binary on your local machine: diff --git a/cookbook/install-deploy.mdx b/cookbook/install-deploy.mdx index 3cc8e786a..3eb84b357 100644 --- a/cookbook/install-deploy.mdx +++ b/cookbook/install-deploy.mdx @@ -1,7 +1,7 @@ --- title: Install and deploy a smart contract hide_table_of_contents: true -description: Combine the install and deploy commands in the Stellar CLI to accomplish both tasks. +description: Combine the install and deploy commands in the Stellar CLI to accomplish both tasks --- You can combine the `install` and `deploy` commands of the Stellar CLI to accomplish both tasks: diff --git a/cookbook/install-wasm.mdx b/cookbook/install-wasm.mdx index 3c8166913..96a4913ef 100644 --- a/cookbook/install-wasm.mdx +++ b/cookbook/install-wasm.mdx @@ -1,7 +1,7 @@ --- title: Install Wasm bytecode hide_table_of_contents: true -description: Use the Stellar CLI to install a compiled smart contract on the ledger. +description: Use the Stellar CLI to install a compiled smart contract on the ledger --- To use the Stellar CLI to install a compiled smart contract on the ledger, use the `stellar contract install` command: diff --git a/cookbook/payments-and-assets.mdx b/cookbook/payments-and-assets.mdx index 08607af02..9849bf3d9 100644 --- a/cookbook/payments-and-assets.mdx +++ b/cookbook/payments-and-assets.mdx @@ -1,7 +1,7 @@ --- title: Payments and Assets hide_table_of_contents: true -description: Send XLM, stellar classic, or a soroban asset using the Stellar CLI. +description: Send XLM, stellar classic, or a soroban asset using the Stellar CLI --- To send payments and work with assets using the Stellar CLI, follow these steps: diff --git a/cookbook/restore-contract-instance.mdx b/cookbook/restore-contract-instance.mdx index 1380233f9..488760ba4 100644 --- a/cookbook/restore-contract-instance.mdx +++ b/cookbook/restore-contract-instance.mdx @@ -1,7 +1,7 @@ --- title: Restore an archived contract using the Stellar CLI hide_table_of_contents: true -description: Restore an archived contract instance using the Stellar CLI. +description: Restore an archived contract instance using the Stellar CLI --- If your contract instance has been archived, it can easily be restored using the Stellar CLI. diff --git a/cookbook/restore-contract-storage.mdx b/cookbook/restore-contract-storage.mdx index 0af356ccb..48fd86b9d 100644 --- a/cookbook/restore-contract-storage.mdx +++ b/cookbook/restore-contract-storage.mdx @@ -1,7 +1,7 @@ --- title: Restore archived contract data using the Stellar CLI hide_table_of_contents: true -description: Restore archived contract storage entries using Stellar CLI. +description: Restore archived contract storage entries using Stellar CLI --- If a contract's persistent storage entry has been archived, you can restore it using the Stellar CLI. For a storage entry that uses a simple `Symbol` as its storage key, you can run a command like so: From 17f0fa582ab2a00bd4551835a9f05ac7721d1745 Mon Sep 17 00:00:00 2001 From: Nando Vieira Date: Tue, 10 Sep 2024 10:40:45 -0700 Subject: [PATCH 3/6] Add libudev-dev as dep. (#1434) Co-authored-by: Willem Wyndham --- .github/workflows/binaries.yml | 2 +- .github/workflows/publish.yml | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/binaries.yml b/.github/workflows/binaries.yml index 191b604fa..3757f94f3 100644 --- a/.github/workflows/binaries.yml +++ b/.github/workflows/binaries.yml @@ -42,7 +42,7 @@ jobs: - run: rustup update - run: rustup target add ${{ matrix.sys.target }} - if: matrix.sys.target == 'aarch64-unknown-linux-gnu' - run: sudo apt-get update && sudo apt-get -y install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu + run: sudo apt-get update && sudo apt-get -y install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu libudev-dev - name: Setup vars run: | version="$(cargo metadata --format-version 1 --no-deps | jq -r '.packages[] | select(.name == "stellar-cli") | .version')" diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 744dc76b2..ac0f6ca20 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -12,5 +12,7 @@ jobs: publish: uses: stellar/actions/.github/workflows/rust-publish.yml@main + with: + additional-deb-packages: libudev-dev secrets: CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }} From b26394c71d96730e228b1293578eab1eeacea8b1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 11 Sep 2024 09:24:42 -0700 Subject: [PATCH 4/6] Bump version to 21.5.0 (#1596) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- Cargo.lock | 28 +++++++++---------- Cargo.toml | 10 +++---- cmd/crates/soroban-test/Cargo.toml | 2 +- .../tests/fixtures/hello/Cargo.toml | 2 +- .../test-wasms/custom_account/Cargo.toml | 2 +- .../test-wasms/custom_type/Cargo.toml | 2 +- .../test-wasms/hello_world/Cargo.toml | 2 +- cmd/soroban-cli/Cargo.toml | 2 +- cmd/stellar-cli/Cargo.toml | 2 +- 9 files changed, 26 insertions(+), 26 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index ae6408d09..788fc8e59 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4675,7 +4675,7 @@ dependencies = [ [[package]] name = "soroban-cli" -version = "21.4.1" +version = "21.5.0" dependencies = [ "assert_cmd", "assert_fs", @@ -4839,7 +4839,7 @@ dependencies = [ [[package]] name = "soroban-hello" -version = "21.4.1" +version = "21.5.0" [[package]] name = "soroban-ledger-snapshot" @@ -4909,7 +4909,7 @@ dependencies = [ [[package]] name = "soroban-spec-json" -version = "21.4.1" +version = "21.5.0" dependencies = [ "pretty_assertions", "serde", @@ -4939,7 +4939,7 @@ dependencies = [ [[package]] name = "soroban-spec-tools" -version = "21.4.1" +version = "21.5.0" dependencies = [ "base64 0.21.7", "ethnum", @@ -4958,7 +4958,7 @@ dependencies = [ [[package]] name = "soroban-spec-typescript" -version = "21.4.1" +version = "21.5.0" dependencies = [ "base64 0.21.7", "heck 0.4.1", @@ -4979,7 +4979,7 @@ dependencies = [ [[package]] name = "soroban-test" -version = "21.4.1" +version = "21.5.0" dependencies = [ "assert_cmd", "assert_fs", @@ -5051,14 +5051,14 @@ checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f" [[package]] name = "stellar-cli" -version = "21.4.1" +version = "21.5.0" dependencies = [ "soroban-cli", ] [[package]] name = "stellar-ledger" -version = "21.4.1" +version = "21.5.0" dependencies = [ "async-trait", "bollard", @@ -5364,35 +5364,35 @@ dependencies = [ [[package]] name = "test_custom_account" -version = "21.4.1" +version = "21.5.0" dependencies = [ "soroban-sdk", ] [[package]] name = "test_custom_types" -version = "21.4.1" +version = "21.5.0" dependencies = [ "soroban-sdk", ] [[package]] name = "test_hello_world" -version = "21.4.1" +version = "21.5.0" dependencies = [ "soroban-sdk", ] [[package]] name = "test_swap" -version = "21.4.1" +version = "21.5.0" dependencies = [ "soroban-sdk", ] [[package]] name = "test_token" -version = "21.4.1" +version = "21.5.0" dependencies = [ "soroban-sdk", "soroban-token-sdk", @@ -5400,7 +5400,7 @@ dependencies = [ [[package]] name = "test_udt" -version = "21.4.1" +version = "21.5.0" dependencies = [ "soroban-sdk", ] diff --git a/Cargo.toml b/Cargo.toml index d58335a21..c3108dc78 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ default-members = ["cmd/soroban-cli", "cmd/crates/soroban-spec-tools", "cmd/crat exclude = ["cmd/crates/soroban-test/tests/fixtures/hello"] [workspace.package] -version = "21.4.1" +version = "21.5.0" rust-version = "1.79.0" [workspace.dependencies.soroban-env-host] @@ -27,15 +27,15 @@ version = "=21.5.0" version = "=21.5.0" [workspace.dependencies.soroban-spec-json] -version = "=21.4.1" +version = "=21.5.0" path = "./cmd/crates/soroban-spec-json" [workspace.dependencies.soroban-spec-typescript] -version = "21.4.1" +version = "21.5.0" path = "./cmd/crates/soroban-spec-typescript" [workspace.dependencies.soroban-spec-tools] -version = "21.4.1" +version = "21.5.0" path = "./cmd/crates/soroban-spec-tools" [workspace.dependencies.soroban-sdk] @@ -48,7 +48,7 @@ version = "=21.2.0" version = "=21.2.0" [workspace.dependencies.soroban-cli] -version = "=21.4.1" +version = "=21.5.0" path = "cmd/soroban-cli" [workspace.dependencies.soroban-rpc] diff --git a/cmd/crates/soroban-test/Cargo.toml b/cmd/crates/soroban-test/Cargo.toml index 643db6ec3..09126adcf 100644 --- a/cmd/crates/soroban-test/Cargo.toml +++ b/cmd/crates/soroban-test/Cargo.toml @@ -6,7 +6,7 @@ repository = "https://github.com/stellar/soroban-test" authors = ["Stellar Development Foundation "] license = "Apache-2.0" readme = "README.md" -version = "21.4.1" +version = "21.5.0" edition = "2021" rust-version.workspace = true autobins = false diff --git a/cmd/crates/soroban-test/tests/fixtures/hello/Cargo.toml b/cmd/crates/soroban-test/tests/fixtures/hello/Cargo.toml index 64d861184..0c3b1512f 100644 --- a/cmd/crates/soroban-test/tests/fixtures/hello/Cargo.toml +++ b/cmd/crates/soroban-test/tests/fixtures/hello/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "soroban-hello" -version = "21.4.1" +version = "21.5.0" edition = "2021" publish = false diff --git a/cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_account/Cargo.toml b/cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_account/Cargo.toml index db31464f2..d4405c512 100644 --- a/cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_account/Cargo.toml +++ b/cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_account/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "test_custom_account" -version = "21.4.1" +version = "21.5.0" authors = ["Stellar Development Foundation "] license = "Apache-2.0" edition = "2021" diff --git a/cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_type/Cargo.toml b/cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_type/Cargo.toml index 61b1cd4c6..17e618805 100644 --- a/cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_type/Cargo.toml +++ b/cmd/crates/soroban-test/tests/fixtures/test-wasms/custom_type/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "test_custom_types" -version = "21.4.1" +version = "21.5.0" authors = ["Stellar Development Foundation "] license = "Apache-2.0" edition = "2021" diff --git a/cmd/crates/soroban-test/tests/fixtures/test-wasms/hello_world/Cargo.toml b/cmd/crates/soroban-test/tests/fixtures/test-wasms/hello_world/Cargo.toml index c2bb8ce80..9ad83fd1c 100644 --- a/cmd/crates/soroban-test/tests/fixtures/test-wasms/hello_world/Cargo.toml +++ b/cmd/crates/soroban-test/tests/fixtures/test-wasms/hello_world/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "test_hello_world" -version = "21.4.1" +version = "21.5.0" authors = ["Stellar Development Foundation "] license = "Apache-2.0" edition = "2021" diff --git a/cmd/soroban-cli/Cargo.toml b/cmd/soroban-cli/Cargo.toml index d9ced8aa2..1f381eb42 100644 --- a/cmd/soroban-cli/Cargo.toml +++ b/cmd/soroban-cli/Cargo.toml @@ -6,7 +6,7 @@ repository = "https://github.com/stellar/stellar-cli" authors = ["Stellar Development Foundation "] license = "Apache-2.0" readme = "README.md" -version = "21.4.1" +version = "21.5.0" edition = "2021" rust-version.workspace = true autobins = false diff --git a/cmd/stellar-cli/Cargo.toml b/cmd/stellar-cli/Cargo.toml index 40fa29dcf..2a388b4de 100644 --- a/cmd/stellar-cli/Cargo.toml +++ b/cmd/stellar-cli/Cargo.toml @@ -6,7 +6,7 @@ repository = "https://github.com/stellar/stellar-cli" authors = ["Stellar Development Foundation "] license = "Apache-2.0" readme = "README.md" -version = "21.4.1" +version = "21.5.0" edition = "2021" rust-version.workspace = true autobins = false From 7f83ec04492054246c3832d1c2fa6c830f75a92d Mon Sep 17 00:00:00 2001 From: Nando Vieira Date: Wed, 11 Sep 2024 10:04:32 -0700 Subject: [PATCH 5/6] Add `stellar-ledger` crate description. (#1597) --- cmd/crates/stellar-ledger/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/crates/stellar-ledger/Cargo.toml b/cmd/crates/stellar-ledger/Cargo.toml index 24d2e8a74..d8847c7d7 100644 --- a/cmd/crates/stellar-ledger/Cargo.toml +++ b/cmd/crates/stellar-ledger/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "stellar-ledger" -description = "" +description = "Handle Stellar signing with Ledger device" homepage = "https://github.com/stellar/soroban-tools" repository = "https://github.com/stellar/soroban-tools" authors = ["Stellar Development Foundation "] From dd14b52fda743b6b6f8397e33a4da190b126d4e6 Mon Sep 17 00:00:00 2001 From: Nando Vieira Date: Wed, 11 Sep 2024 13:28:04 -0700 Subject: [PATCH 6/6] Add crate version badge. (#1598) --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index a3632af92..46c6d6816 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Stellar CLI (stellar-cli) ![Apache 2.0 licensed](https://img.shields.io/badge/license-apache%202.0-blue.svg) +[![Crates.io Version](https://img.shields.io/crates/v/stellar-cli?label=version&color=04ac5b)](https://crates.io/crates/stellar-cli) This repo is home to the Stellar CLI, the command-line multi-tool for running and deploying Stellar contracts on the Stellar network.