From 285f9fc0fe344b6d90013e2b720e277febd10abf Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 12 Nov 2026 14:43:45 -0600 Subject: [PATCH 1/2] fix(docs): Polish the cookbook for Mintlify - Use root-relative links and current page paths - Start pages at h2, label output blocks as text, drop "Note:" callout prefixes - Give each page its own description and fix copy errors - Correct the TTL cap explanation and drop the obsolete --inflation-dest Refs stellar/stellar-docs#3121 --- cookbook/asset-management.mdx | 60 ++++++++++---------- cookbook/contract-build-meta.mdx | 10 ++-- cookbook/contract-invoke-arguments.mdx | 30 +++++----- cookbook/contract-lifecycle.mdx | 12 ++-- cookbook/deploy-contract.mdx | 2 +- cookbook/deploy-stellar-asset-contract.mdx | 14 ++--- cookbook/extend-contract-instance.mdx | 2 +- cookbook/extend-contract-storage.mdx | 4 +- cookbook/extend-contract-wasm.mdx | 8 +-- cookbook/payments-and-assets.mdx | 10 ++-- cookbook/restore-contract-storage.mdx | 4 +- cookbook/stellar-keys.mdx | 42 +++++++------- cookbook/tx-new-create-claimable-balance.mdx | 6 +- cookbook/tx-new.mdx | 20 +++---- cookbook/tx-op-add.mdx | 15 +++-- cookbook/tx-sign.mdx | 26 ++++----- cookbook/upload-wasm.mdx | 2 +- 17 files changed, 132 insertions(+), 135 deletions(-) diff --git a/cookbook/asset-management.mdx b/cookbook/asset-management.mdx index 3bc396da6d..f132b9d3cc 100644 --- a/cookbook/asset-management.mdx +++ b/cookbook/asset-management.mdx @@ -1,25 +1,25 @@ --- title: Asset Management -description: Issue a Stellar Asset, deploy it's contract, and mint, burn, freeze, and clawback. +description: Issue a Stellar asset, deploy its contract, and mint, burn, freeze, and claw back the asset --- The [stellar-cli] can be used to issue and administer assets on the Stellar network. -The following guide assumes that the [stellar-cli] has been configured to use testnet, or a local test network. To use testnet, run the following command. +The following guide assumes that the [stellar-cli] has been configured to use testnet, or a local test network. To use testnet, run the following command: ```bash stellar network use testnet ``` -### Asset Issuance +## Asset Issuance To create a Stellar Asset using the [stellar-cli] several steps take place: - An issuer account must exist. -- An asset code selected. +- An asset code must be chosen. - Optionally, an admin is configured. -#### Issuer Creation +### Issuer Creation To create an issuer, generate a key and fund it. Funding uses friendbot, the testnet faucet, and is only available on testnet. @@ -43,11 +43,11 @@ Configure the issuer key to be used for signing transactions: stellar keys use issuer ``` -#### Issuer Config +### Issuer Config Issuer accounts have several configuration flags that can be toggled and affect all assets issued by the issuer. -In this guide the issuer account will be setup with the revocable and clawback-enabled features will be enabled. These features allow the asset admin to revoke authorisation to use an asset, which has the effect of freezing their balance, and to clawback, which has the effect of forcibly burning the asset. +In this guide, the issuer account is set up with the revocable and clawback-enabled flags. These flags allow the asset admin to revoke a holder's authorization to use the asset, which freezes their balance, and to claw back the asset, which forcibly burns it. ```bash stellar tx new set-options \ @@ -57,7 +57,7 @@ stellar tx new set-options \ For other options, see the manual for the [stellar tx new set-options] command. -To view the tx before sending, use the `--build-only` option and pipe the transaction through the tx edit command: +To view the transaction before sending it, use the `--build-only` option and pipe the transaction through the `tx edit` command: ```bash cookbooktest.ignore="because piping isn't supported" stellar tx new set-options \ @@ -65,11 +65,11 @@ stellar tx new set-options \ --set-clawback-enabled \ --build-only \ | stellar tx edit \ - | stellar sign \ - | stellar send + | stellar tx sign \ + | stellar tx send ``` -#### Choosing the Asset Code +### Choosing the Asset Code Choose an asset code 1 to 12 characters long. @@ -77,17 +77,17 @@ The asset code along with the issuer account address will uniquely identify the For the rest of this guide the asset code `ABC` will be used. -#### Asset Contract Setup +### Asset Contract Setup -A built-in contract exists on network for every asset. It's address is reserved and can be calculated using the following command. +A built-in contract exists on the network for every asset. Its address is reserved and can be calculated using the following command: ```bash stellar contract asset id --asset ABC:issuer ``` -The contract is not deployed automatically. Anyone can deploy the contract, it is not an action requiring authorisation. +The contract is not deployed automatically. Anyone can deploy the contract; it doesn't require authorization. -##### Contract Deployment +#### Contract Deployment Deploy the built-in asset contract. @@ -99,13 +99,13 @@ The `--alias` option stores locally an alias that can be used in subsequent comm stellar contract asset deploy --asset ABC:issuer --alias mycontract ``` -Run the following command to get some read only data from the contract to confirm it's deployed. +Run the following command to read some data from the contract and confirm it's deployed: ```bash stellar contract invoke --id mycontract -- name ``` -##### Admin Setup +#### Admin Setup At this point the issuer is the admin of the contract. Let's create another account that'll be the admin. @@ -121,7 +121,7 @@ stellar keys public-key admin stellar keys fund admin ``` -Using the issuer account, invoke the asset contract's `set_admin` function. +Using the issuer account, invoke the asset contract's `set_admin` function: ```bash stellar keys use issuer @@ -131,11 +131,11 @@ stellar keys use issuer stellar contract invoke --source issuer --id mycontract -- set_admin --new_admin admin ``` -### Actions +## Actions -Once the asset contract is deployed and setup, the following actions can take place. +Once the asset contract is deployed and set up, the following actions can take place. -#### Mint (Admin Only) +### Mint (Admin Only) Generate and fund a user account that the minted asset will be transferred to. @@ -161,7 +161,7 @@ stellar keys use user stellar tx new change-trust --line ABC:issuer ``` -To mint the asset to the user, use the admin account, invoke the asset contract's `mint` function. +To mint the asset to the user, use the admin account to invoke the asset contract's `mint` function: ```bash stellar keys use admin @@ -177,7 +177,7 @@ Check the balance after the mint. stellar contract invoke --id mycontract -- balance --id user ``` -#### Transfer +### Transfer Generate and fund a second user account that the user account from the previous step can transfer the asset to. @@ -223,7 +223,7 @@ stellar contract invoke --id mycontract -- balance --id user stellar contract invoke --id mycontract -- balance --id user2 ``` -#### Burn +### Burn Using the user account, invoke the asset contract's `burn` function. @@ -241,9 +241,9 @@ Check the balance after the burn. stellar contract invoke --id mycontract -- balance --id user ``` -#### Revoke Authorization / Freeze (Admin Only) +### Revoke Authorization / Freeze (Admin Only) -An admin can revoke a user's authorisation to use the asset. The user will continue to hold the balance but will be unable to transfer it or create new payments. Any existing liabilities, such as those created by offers created on Stellar, will continue to exist and could still be executed. +An admin can revoke a user's authorization to use the asset. The user will continue to hold the balance but will be unable to transfer it or create new payments. Any existing liabilities, such as those created by offers created on Stellar, will continue to exist and could still be executed. Using the admin, invoke the asset contract's `set_authorized` function. @@ -265,9 +265,9 @@ stellar keys use user stellar contract invoke --id mycontract -- transfer --from user --to user2 --amount 3 ``` -#### Clawback (Admin Only) +### Clawback (Admin Only) -An admin can clawback a user's balance. The amount clawed back will be burned. +An admin can claw back a user's balance. The amount clawed back will be burned. Using the admin, invoke the asset contract's `clawback` function. @@ -285,5 +285,5 @@ Check the balance after the clawback. stellar contract invoke --id mycontract -- balance --id user ``` -[stellar-cli]: ../stellar-cli.mdx -[stellar tx new set-options]: ../stellar-cli.mdx#stellar-tx-new-set-options +[stellar-cli]: /docs/tools/cli/stellar-cli +[stellar tx new set-options]: /docs/tools/cli/stellar-cli#stellar-tx-new-set-options diff --git a/cookbook/contract-build-meta.mdx b/cookbook/contract-build-meta.mdx index dda20b58ae..e22f1fce7e 100644 --- a/cookbook/contract-build-meta.mdx +++ b/cookbook/contract-build-meta.mdx @@ -1,9 +1,9 @@ --- -title: Add meta data to contract WASM on build -description: Include meta data in the contract WASM byte code on build +title: Add metadata to contract Wasm on build +description: Include metadata in the contract Wasm bytecode on build --- -To build a smart contract, use the `stellar contract build` command. The `--meta` option will allow you to add additional meta data entries to the `contractmetav0` custom section of the resulting WASM file at build time. +To build a smart contract, use the `stellar contract build` command. The `--meta` option adds metadata entries to the `contractmetav0` custom section of the resulting Wasm file at build time. ```bash cookbooktest.ignore="" export SHA=$(git rev-parse HEAD) @@ -16,14 +16,14 @@ stellar contract build \ --meta commit_sha=$SHA ``` -You can then use `stellar contract info meta` to see the meta data: +You can then use `stellar contract info meta` to see the metadata: ```bash stellar contract info meta \ --wasm target/wasm32v1-none/release/test_hello_world.wasm ``` -```bash cookbooktest.ignore="" +```text Contract meta: • rsver: 1.91.0 (Rust version) • rssdkver: 23.0.1#510d3feb724c2b01d7e7ab7652f03b9f8efc3f35 (Soroban SDK version and its commit hash) diff --git a/cookbook/contract-invoke-arguments.mdx b/cookbook/contract-invoke-arguments.mdx index 2fb1e3dd41..59a6166b8e 100644 --- a/cookbook/contract-invoke-arguments.mdx +++ b/cookbook/contract-invoke-arguments.mdx @@ -5,7 +5,7 @@ description: How to pass each argument type when invoking a Stellar smart contra When using `stellar contract invoke`, each `--arg-name ` flag is parsed according to the contract's type spec. This guide shows the correct format for each supported type. -### Integers (`u32`, `i32`, `u64`, `i64`) +## Integers (`u32`, `i32`, `u64`, `i64`) Pass bare numeric literals directly on the command line. @@ -15,7 +15,7 @@ stellar contract invoke --id mycontract -- my_function \ --offset -7 ``` -### Large Integers (`u128`, `i128`, `u256`, `i256`) +## Large Integers (`u128`, `i128`, `u256`, `i256`) Pass bare numeric literals, just like small integers. The CLI reads the raw value as a string internally, bypassing JSON number precision limits entirely. @@ -24,7 +24,7 @@ stellar contract invoke --id mycontract -- my_function \ --amount 340282366920938463463374607431768211455 ``` -### Boolean +## Boolean Pass `true` or `false` as unquoted literals. @@ -34,7 +34,7 @@ stellar contract invoke --id mycontract -- my_function \ --is_paused false ``` -### String +## String Bare words work for simple strings. Numbers and booleans are also accepted and are automatically converted to their string representation, so you do not need to add extra quoting. Explicit JSON quoting is also accepted. @@ -56,7 +56,7 @@ stellar contract invoke --id mycontract -- my_function \ --label '"hello world"' ``` -### Symbol +## Symbol Symbols follow the same rules as `String`: bare words, numbers, and booleans are all accepted, and non-string JSON values are auto-converted. @@ -65,7 +65,7 @@ stellar contract invoke --id mycontract -- my_function \ --status active ``` -### Address +## Address You can pass either a locally known identity name (e.g. `alice`) or a raw Stellar strkey (`G…` for accounts, `C…` for contracts). @@ -79,7 +79,7 @@ stellar contract invoke --id mycontract -- my_function \ --owner GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN ``` -### Bytes / BytesN +## Bytes / BytesN Pass a hex-encoded string representing the byte sequence. @@ -88,7 +88,7 @@ stellar contract invoke --id mycontract -- my_function \ --hash "deadbeef01020304" ``` -### Optional Arguments +## Optional Arguments Simply omit the flag. The CLI will supply a `void` / null value for any `Option` parameter that is not provided. @@ -98,7 +98,7 @@ stellar contract invoke --id mycontract -- my_function \ --amount 100 ``` -### Vec +## Vec Pass a JSON array, quoting the whole value so the shell does not split it. @@ -107,7 +107,7 @@ stellar contract invoke --id mycontract -- my_function \ --recipients '["alice", "bob", "carol"]' ``` -### Map +## Map Pass a JSON object with string keys. @@ -116,7 +116,7 @@ stellar contract invoke --id mycontract -- my_function \ --metadata '{"key": "value", "version": "1"}' ``` -### Tuple +## Tuple Pass a JSON array whose elements match the tuple's field order. @@ -125,7 +125,7 @@ stellar contract invoke --id mycontract -- my_function \ --point '[10, 20]' ``` -### Struct (User-Defined Type) +## Struct (User-Defined Type) Pass a JSON object with the struct's named fields. @@ -134,7 +134,7 @@ stellar contract invoke --id mycontract -- my_function \ --config '{"max_supply": "1000000", "decimals": 7}' ``` -### Enum / Union (User-Defined Type) +## Enum / Union (User-Defined Type) For unit variants, pass the variant name as a plain string. For variants that carry a value, pass a JSON object with the variant name as the key. @@ -148,7 +148,7 @@ stellar contract invoke --id mycontract -- my_function \ --result '{"Ok": 42}' ``` -### File-Based Arguments +## File-Based Arguments For long or complex JSON values, use the `--arg-file-path` flag variant to load the value from a file instead of inlining it on the command line. The flag name is derived from the argument name by appending `-file-path`. @@ -161,7 +161,7 @@ stellar contract invoke --id mycontract -- my_function \ --config-file-path config.json ``` -For `Bytes` and `BytesN` parameters, the file's raw binary content is read directly — no hex encoding is required. +For `Bytes` and `BytesN` parameters, the file's raw binary content is read directly, so no hex encoding is required. ```bash cookbooktest.ignore="" stellar contract invoke --id mycontract -- my_function \ diff --git a/cookbook/contract-lifecycle.mdx b/cookbook/contract-lifecycle.mdx index b352d1bb9c..d7d790c9c0 100644 --- a/cookbook/contract-lifecycle.mdx +++ b/cookbook/contract-lifecycle.mdx @@ -5,7 +5,7 @@ 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. Set your preferred network. For this guide, we will use `testnet`. A list of available networks can be found [here](/docs/networks) +1. Set your preferred network. This guide uses `testnet`. See [Networks](/docs/networks) for the list of available networks. ```bash stellar network use testnet @@ -33,9 +33,9 @@ stellar keys use alice stellar contract deploy --wasm /path/to/contract.wasm --alias mycontract ``` -This will display the resulting contract ID, e.g.: +This displays the resulting contract ID, for example: -``` +```text CBB65ZLBQBZL5IYHDHEEPCVUUMFOQUZSQKAJFV36R7TZETCLWGFTRLOQ ``` @@ -53,12 +53,12 @@ stellar contract invoke --id mycontract -- stellar contract read --id mycontract --durability --key ``` -Note: `` is either `persistent` or `temporary`. `KEY` provides the key of the storage entry being read. +`` is either `persistent` or `temporary`. `` is the key of the storage entry being read. -7. Manage expired states: +7. Extend the TTL of the contract's state: ```bash stellar contract extend --id mycontract --ledgers-to-extend 1000 --durability --key ``` -This extends the state of the instance provided by the given key to at least 1000 ledgers from the current ledger. +This extends the TTL of the storage entry with the given key to at least 1,000 ledgers from the current ledger. diff --git a/cookbook/deploy-contract.mdx b/cookbook/deploy-contract.mdx index ddb9918f70..d778048c1d 100644 --- a/cookbook/deploy-contract.mdx +++ b/cookbook/deploy-contract.mdx @@ -15,6 +15,6 @@ stellar contract deploy \ -Optionally assign an alias by replacing `` with your desired alias name for the contract. The alias is a locally stored mapping to the contract address, and can be used in other stellar-cli commands in place of the address. +Optionally assign an alias by replacing `` with your desired alias name for the contract. The alias is a locally stored mapping to the contract address, and can be used in other Stellar CLI commands in place of the address. diff --git a/cookbook/deploy-stellar-asset-contract.mdx b/cookbook/deploy-stellar-asset-contract.mdx index e3750584c9..4075497fc0 100644 --- a/cookbook/deploy-stellar-asset-contract.mdx +++ b/cookbook/deploy-stellar-asset-contract.mdx @@ -5,7 +5,7 @@ description: Deploy an SAC for a Stellar asset so that it can interact with smar 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. +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. @@ -20,7 +20,7 @@ stellar contract asset deploy \ --asset USDC:GCYEIQEWOCTTSA72VPZ6LYIZIK4W4KNGJR72UADIXUXG45VDFRVCQTYE ``` -The `asset` argument corresponds to the symbol and it's issuer address, which is how assets are identified on Stellar. +The `--asset` argument takes the asset code and its issuer address, which is how assets are identified on Stellar. The same can be done for the native [Lumens] asset: @@ -33,7 +33,7 @@ stellar contract asset deploy \ -Deploying the native asset will fail on testnet or mainnet as a Stellar Asset Contract already exists. +Deploying the native asset fails on testnet and mainnet, because its Stellar Asset Contract already exists. @@ -45,9 +45,5 @@ stellar contract id asset \ --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 +[stellar asset contract]: /docs/tokens/stellar-asset-contract +[lumens]: /docs/learn/fundamentals/lumens diff --git a/cookbook/extend-contract-instance.mdx b/cookbook/extend-contract-instance.mdx index 935243f13e..65e276af71 100644 --- a/cookbook/extend-contract-instance.mdx +++ b/cookbook/extend-contract-instance.mdx @@ -14,7 +14,7 @@ stellar contract extend \ --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). +This example extends the TTL by 535,679 ledgers, roughly 30 days at an average ledger close time of 5 seconds. The network's `max_entry_ttl` setting caps this value, and the CLI returns an error if you ask for more. When you extend a contract instance, this includes: diff --git a/cookbook/extend-contract-storage.mdx b/cookbook/extend-contract-storage.mdx index 75d46f0f31..e97855a51f 100644 --- a/cookbook/extend-contract-storage.mdx +++ b/cookbook/extend-contract-storage.mdx @@ -15,7 +15,7 @@ stellar contract extend \ --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). +This example extends the TTL by 535,679 ledgers, roughly 30 days at an average ledger close time of 5 seconds. The network's `max_entry_ttl` setting caps this value, and the CLI returns an error if you ask for more. 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: @@ -31,6 +31,6 @@ stellar contract extend \ -Be sure to check out our [guide on creating XDR ledger keys](/docs/build/guides/rpc/generate-ledger-keys-python) for help generating them. +Be sure to check out our [guide on creating XDR ledger keys](/docs/build/guides/rpc/generate-ledger-keys) for help generating them. diff --git a/cookbook/extend-contract-wasm.mdx b/cookbook/extend-contract-wasm.mdx index d46f3a364c..68e9d73be8 100644 --- a/cookbook/extend-contract-wasm.mdx +++ b/cookbook/extend-contract-wasm.mdx @@ -1,9 +1,9 @@ --- title: Extend a deployed contract's Wasm code TTL -description: Use Stellar CLI to extend contract's Wasm bytecode TTL, with or without local binary +description: Use the Stellar CLI to extend the TTL of a contract's Wasm bytecode, with or without a 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: +You can use the Stellar CLI to extend the TTL of a contract's Wasm bytecode. You can do this whether or not you have the compiled contract locally. If you have the compiled binary on your local machine: ```bash stellar contract extend \ @@ -14,7 +14,7 @@ stellar contract extend \ --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). +This example extends the TTL by 535,679 ledgers, roughly 30 days at an average ledger close time of 5 seconds. The network's `max_entry_ttl` setting caps this value, and the CLI returns an error if you ask for more. 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: @@ -29,6 +29,6 @@ stellar contract extend \ -You can learn more about finding the correct Wasm hash for a contract instance [here (JavaScript)](/docs/build/guides/rpc/retrieve-contract-code-js) and [here (Python)](/docs/build/guides/rpc/retrieve-contract-code-python). +You can learn more about finding the correct Wasm hash for a contract instance in [Retrieve a contract code ledger entry](/docs/build/guides/rpc/retrieve-contract-code). diff --git a/cookbook/payments-and-assets.mdx b/cookbook/payments-and-assets.mdx index 14004aef16..657f7a72a4 100644 --- a/cookbook/payments-and-assets.mdx +++ b/cookbook/payments-and-assets.mdx @@ -1,11 +1,11 @@ --- title: Payments and Assets -description: Send XLM, stellar classic, or a soroban asset using the Stellar CLI +description: Send XLM and other Stellar assets 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](/docs/networks) +1. Set your preferred network. This guide uses `testnet`. See [Networks](/docs/networks) for the list of available networks. ```bash stellar network use testnet @@ -29,7 +29,7 @@ stellar keys generate bob stellar keys fund bob ``` -3. Obtain the stellar asset contract ID: +3. Get the contract ID of the native asset's Stellar Asset Contract: ```bash stellar contract id asset --asset native @@ -51,10 +51,10 @@ stellar keys use alice stellar contract invoke --id -- transfer --to bob --from alice --amount 100 ``` -6. Check account balance: +6. Check Bob's balance: ```bash stellar contract invoke --id -- balance --id bob ``` -For more information on the functions available to the stellar asset contract, see the [token interface code](/docs/tokens/token-interface#code) +For more information on the functions available on the Stellar Asset Contract, see the [token interface code](/docs/tokens/token-interface#code). diff --git a/cookbook/restore-contract-storage.mdx b/cookbook/restore-contract-storage.mdx index fa97a64928..4f353efee2 100644 --- a/cookbook/restore-contract-storage.mdx +++ b/cookbook/restore-contract-storage.mdx @@ -1,6 +1,6 @@ --- title: Restore archived contract data using the Stellar CLI -description: Restore archived contract storage entries using Stellar CLI +description: Restore archived contract storage entries using the 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: @@ -27,6 +27,6 @@ stellar contract restore \ -Be sure to check out our [guide on creating XDR ledger keys](/docs/build/guides/rpc/generate-ledger-keys-python) for help generating them. +Be sure to check out our [guide on creating XDR ledger keys](/docs/build/guides/rpc/generate-ledger-keys) for help generating them. diff --git a/cookbook/stellar-keys.mdx b/cookbook/stellar-keys.mdx index a072cce3c2..42f27cb262 100644 --- a/cookbook/stellar-keys.mdx +++ b/cookbook/stellar-keys.mdx @@ -1,11 +1,11 @@ --- title: Stellar Keys -description: Manage stellar keys +description: Generate, inspect, fund, and remove Stellar identities using the Stellar CLI --- This guide walks you through generating, inspecting, and removing a Stellar identity using the CLI. -### 1. Generate a New Identity +## 1. Generate a New Identity Run the following command to create a new keypair and save it under the alias named `carol`: @@ -15,13 +15,13 @@ stellar keys generate carol Output: -``` +```text ✅ Key saved with alias carol in ".config/soroban/identity/carol.toml" ``` The CLI stores this identity in a TOML file. -### 2. Verify the Identity File +## 2. Verify the Identity File Navigate to the configuration directory and list the contents: @@ -31,13 +31,13 @@ cd .config/soroban/identity && ls Output: -``` +```text carol.toml ``` -The file carol.toml contains the seed phrase for your identity. +The file `carol.toml` contains the seed phrase for your identity. -### 3. View the Seed Phrase +## 3. View the Seed Phrase ```bash cookbooktest.ignore="" cat carol.toml @@ -45,19 +45,19 @@ cat carol.toml Output: -``` +```text seed_phrase = "patrol clean public grocery roof aim have valve cherry dismiss lunar tail duty license capable little version banana amount often cover dice couple party" ``` -Note: The seed phrase is sensitive information. Handle it with care and never expose it publicly. +The seed phrase is sensitive information. Handle it with care and never expose it publicly. -### 4. Derive the Secret Key +## 4. Derive the Secret Key -To display the secret key for the carol identity: +To display the secret key for the `carol` identity: ```bash stellar keys secret carol @@ -65,19 +65,19 @@ stellar keys secret carol Output: -``` +```text SCJP663VYFZPYN75H2DYJA3FYUBP5UR23HZ4ZDHDMDY6TXVYUYMWNKTI ``` -Note: The secret key is sensitive information. Handle it with care and never expose it publicly. +The secret key is sensitive information. Handle it with care and never expose it publicly. -### 5. Derive the Public Key +## 5. Derive the Public Key -To display the corresponding public key for the carol identity: +To display the corresponding public key for the `carol` identity: ```bash stellar keys public-key carol @@ -85,13 +85,13 @@ stellar keys public-key carol Output: -``` +```text GD3BFFX7DTNJAGDVVM5RYGGQQNURZTH4VSBLWF55YXY3L6T2WWZK57EI ``` This is the public address of your key. -### 6. Fund this account +## 6. Fund the Account ```bash stellar keys fund carol @@ -99,13 +99,13 @@ stellar keys fund carol Output: -``` +```text ✅ Account carol funded on "Test SDF Network ; September 2015" ``` You can also fund the account while creating the key by using `stellar keys generate --fund`. -### 7. Remove the Identity +## 7. Remove the Identity When you no longer need this identity, remove it using: @@ -115,8 +115,8 @@ stellar keys rm carol --force Output: -``` +```text ℹ️ Removing the key's cli config file ``` -At this point, the identity file carol.toml is deleted, and the alias is no longer available in the CLI. +At this point, the identity file `carol.toml` is deleted, and the alias is no longer available in the CLI. diff --git a/cookbook/tx-new-create-claimable-balance.mdx b/cookbook/tx-new-create-claimable-balance.mdx index ff1111cd3a..392d2f3226 100644 --- a/cookbook/tx-new-create-claimable-balance.mdx +++ b/cookbook/tx-new-create-claimable-balance.mdx @@ -184,7 +184,11 @@ stellar tx new create-claimable-balance \ ## Understanding Predicates -**Note**: Predicates must be valid JSON, so you must use proper quoting and escaping. + + +Predicates must be valid JSON, so quote and escape them carefully. + + ### Predicate Types diff --git a/cookbook/tx-new.mdx b/cookbook/tx-new.mdx index 8cc59aba9a..8b13931732 100644 --- a/cookbook/tx-new.mdx +++ b/cookbook/tx-new.mdx @@ -1,13 +1,13 @@ --- title: tx Commands -description: Create stellar transactions using the Stellar CLI +description: Build, sign, and send classic Stellar transactions with the Stellar CLI's tx new commands --- -So far the examples of the CLI interacting with the blockchain have been through the `contract` command. Uploading contracts, deploying contracts, and invoking them. Each of these are different types of transactions, which must be signed and submitted to the network (and in the case of contract related transactions simulated first). +So far, the examples of the CLI interacting with the network have used the `contract` command: uploading, deploying, and invoking contracts. Each of these is a different type of transaction, which must be signed and submitted to the network (and, for contract transactions, simulated first). -Technically these three are different operations, of which a transaction can contain up to 100 operations. However, in the case of contract related operations a transaction is limited to just one. +Technically, these are three different operations. A transaction can contain up to 100 operations, but a transaction with a contract operation can contain only that one. -So for all other transactions the CLI provides the `tx` subcommands. These are: +For all other transactions, the CLI provides the `tx` subcommands: - `new` - `sign` @@ -16,20 +16,20 @@ So for all other transactions the CLI provides the `tx` subcommands. These are: ## `tx new` -For the following examples we will use the following accounts: +The following examples use these accounts: ```sh stellar keys generate --fund alice --network testnet stellar keys generate bob # You can add a public key to the keys stellar keys add --public-key GBUG7QTBTT47XVDVE6RZYWRUZBPLOIO57INE6LYZDMIXMMDCREQRUQKI charlie -## and use testnet +# and use testnet stellar network use testnet ``` ### Create Account -Creates and funds a new Stellar account. Above `alice` was funded by [friendbot](/docs/networks#friendbot). However, `bob` and `charlie` were not. So we can use the `create-account` command to fund them. +Creates and funds a new Stellar account. Above, `alice` was funded by [Friendbot](/docs/networks#friendbot), but `bob` and `charlie` were not, so you can use the `create-account` command to fund them. `bob` will receive 10 XLM and `charlie` will get 1 XLM. @@ -63,7 +63,7 @@ stellar tx new payment \ Notes: -- `--asset`: The asset to send - either "native" for XLM or "CODE:ISSUER" format for other assets +- `--asset`: The asset to send: either `native` for XLM, or `CODE:ISSUER` for other assets ### Bump Sequence @@ -89,7 +89,7 @@ stellar tx new account-merge \ Notes: -- `--source`: The account to remove from the ledger, thus this is its final tranaction +- `--source`: The account to remove from the ledger, so this is its final transaction ### Set Trustline Flags @@ -122,7 +122,6 @@ Configure account settings: ```sh stellar tx new set-options \ --source alice \ - --inflation-dest GBUG7QTBTT47XVDVE6RZYWRUZBPLOIO57INE6LYZDMIXMMDCREQRUQKI \ --home-domain "example.com" \ --master-weight 100 \ --med-threshold 100 \ @@ -139,7 +138,6 @@ stellar tx new set-options \ Notes: - `--source`: Account to modify settings for -- `--inflation-dest`: Set inflation destination account - `--home-domain`: Set home domain for federation/compliance - `--master-weight`: Weight of the account's master key (0-255) - `--low-threshold`: Weight threshold for low security operations diff --git a/cookbook/tx-op-add.mdx b/cookbook/tx-op-add.mdx index 15c7eee206..d77758dc99 100644 --- a/cookbook/tx-op-add.mdx +++ b/cookbook/tx-op-add.mdx @@ -1,16 +1,15 @@ --- title: tx op add -description: Create stellar transactions using the Stellar CLI +description: Add operations to a transaction by piping it through the Stellar CLI's tx op add command --- -As seen before you can use pipes to pass a transaction envelope between commands. Before we have only been looking at transactions with one operation, however, as mentioned there can be up to 100 operations in a single transaction. +As shown before, you can use pipes to pass a transaction envelope between commands. So far, the examples have used transactions with one operation, but a transaction can contain up to 100 operations. -To add an operation to a transaction you can use the `tx op add` command. This command takes the transaction envolope from the previous command and adds an operation to it. +To add an operation to a transaction you can use the `tx op add` command. This command takes the transaction envelope from the previous command and adds an operation to it. -Let's consider a more complicated example. Consider issuing an asset, here `USDC` with the requirement that only the issuer can transfer funds to the distrubtor. +Consider a more complicated example: issuing an asset, here `USDC`, with the requirement that only the issuer can transfer funds to the distributor. ```sh - stellar keys generate --fund issuer stellar keys generate --fund distributor @@ -25,7 +24,7 @@ ASSET="USDC:$ISSUER_PK" # first the issuer sets the options for being able to clawback and revoke the asset stellar tx new set-options --inclusion-fee 1000 --source issuer --set-clawback-enabled --set-revocable --build-only \ -# next the distributor establishes a trustline with the asset. Note that here the distributor the source account for the operation, not the issuer +# next the distributor establishes a trustline with the asset. Note that here the distributor is the source account for the operation, not the issuer | stellar tx op add change-trust --op-source distributor --line $ASSET \ # then the issuer sends the smallest amount possible to the distributor | stellar tx op add payment --destination distributor --asset $ASSET --amount 1 \ @@ -36,10 +35,10 @@ stellar tx new set-options --inclusion-fee 1000 --source issuer --set-clawback-e | stellar tx sign --sign-with-key distributor \ | stellar tx send -# Next is an example of sandwiching an operation. That is giving permission in one operation, preforming the operation, and then removing the permission in a third operation. +# Next is an example of sandwiching an operation. That is giving permission in one operation, performing the operation, and then removing the permission in a third operation. # Here is an example of minting new assets to the distributor with a sandwich transaction # First authorize the distributor to receive the asset -stellar tx new set-trustline-flags --inclusion-fee 1000 --build-only --source issuer --asset $ASSET --trustor $distributor_PK --set-authorize \ +stellar tx new set-trustline-flags --inclusion-fee 1000 --build-only --source issuer --asset $ASSET --trustor distributor --set-authorize \ # Then mint the asset to the distributor | stellar tx op add payment --destination distributor --asset $ASSET --amount 1_000_000_000_000 \ # Finally remove the authorization diff --git a/cookbook/tx-sign.mdx b/cookbook/tx-sign.mdx index d47032261a..007bc57b6d 100644 --- a/cookbook/tx-sign.mdx +++ b/cookbook/tx-sign.mdx @@ -1,15 +1,15 @@ --- title: tx sign and tx send -description: Create stellar transactions using the Stellar CLI +description: Sign and submit transactions with the Stellar CLI's tx sign and tx send commands --- -The previous examples of using `tx new` showed how to create transactions. However, these transactions were immediately ready to be signed and submitted to the network. +The previous `tx new` examples created transactions, then signed and submitted them to the network right away. -To avoid this each of the subcommands has the `--build-only` argument, which as the name suggests only builds the transaction and prints the transaction envelope. +To stop before signing, each subcommand has a `--build-only` argument, which only builds the transaction and prints the transaction envelope. ## `tx sign` -Let's return to the first example of creating `bob`s account: +Return to the first example of creating `bob`'s account: ```sh stellar tx new create-account \ @@ -19,15 +19,15 @@ stellar tx new create-account \ --build-only ``` -would output something like: +This outputs something like: -```sh +```text AAAAAgAAAADwSUp9CwmVlPN40mKX1I1j39y6DmYc36QS1aK2x6eYVQAAAGQAEcMsAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAACTMkzn1TwPo8SIhnKvnyuv9K2/aWjpX9NTYfyiA7vXaAAAAAAX14QAAAAAAAAAAAA== ``` -You can inspect it with [stellar lab!](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;&xdr$blob=AAAAAgAAAADwSUp9CwmVlPN40mKX1I1j39y6DmYc36QS1aK2x6eYVQAAAGQAEcMsAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAACTMkzn1TwPo8SIhnKvnyuv9K2//aWjpX9NTYfyiA7vXaAAAAAAX14QAAAAAAAAAAAA==;;) Where you can also sign and send the transaction. +You can inspect it with [Stellar Lab](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;&xdr$blob=AAAAAgAAAADwSUp9CwmVlPN40mKX1I1j39y6DmYc36QS1aK2x6eYVQAAAGQAEcMsAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAACTMkzn1TwPo8SIhnKvnyuv9K2//aWjpX9NTYfyiA7vXaAAAAAAX14QAAAAAAAAAAAA==;;), where you can also sign and send the transaction. -However, you can also sign the transaction with the `tx sign` command. To do this you can pipe the output of the `tx new` command to the `tx sign` command: +You can also sign the transaction with the `tx sign` command. To do this, pipe the output of the `tx new` command to the `tx sign` command: ```sh stellar tx new create-account \ @@ -38,17 +38,17 @@ stellar tx new create-account \ | stellar tx sign --sign-with-key alice ``` -This should output something like: +This outputs something like: -```sh +```text AAAAAgAAAAAebE8Ewg9uzvHRAl+UmvP0kixsyp238kkz0zOy+91FeQAAAGQAFJk4AAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAPpiy8qfSw4pLYG/Bav78FfrFWlte7YQfiHX41DQ+nGWAAAAAAX14QAAAAAAAAAAAfvdRXkAAABA4kjz9Yeub/IrzogjMr57U4nYwCmSJAXxIW+7Xyjan/UweIByF7uEhVS4gEl1N138uq07njVxZwRMtugWyMleCg== ``` -You can again [view it in lab and see that there is now a signature attached to the transaction envelope](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;&xdr$blob=AAAAAgAAAAAebE8Ewg9uzvHRAl+UmvP0kixsyp238kkz0zOy+91FeQAAAGQAFJk4AAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAPpiy8qfSw4pLYG//Bav78FfrFWlte7YQfiHX41DQ+nGWAAAAAAX14QAAAAAAAAAAAfvdRXkAAABA4kjz9Yeub//IrzogjMr57U4nYwCmSJAXxIW+7Xyjan//UweIByF7uEhVS4gEl1N138uq07njVxZwRMtugWyMleCg==;;). +You can again [view it in Lab and see that there is now a signature attached to the transaction envelope](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;&xdr$blob=AAAAAgAAAAAebE8Ewg9uzvHRAl+UmvP0kixsyp238kkz0zOy+91FeQAAAGQAFJk4AAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAPpiy8qfSw4pLYG//Bav78FfrFWlte7YQfiHX41DQ+nGWAAAAAAX14QAAAAAAAAAAAfvdRXkAAABA4kjz9Yeub//IrzogjMr57U4nYwCmSJAXxIW+7Xyjan//UweIByF7uEhVS4gEl1N138uq07njVxZwRMtugWyMleCg==;;). -Or sign with lab! Though currently you must send it from lab and cannot return to the CLI (a work in progress!). +You can also sign with Stellar Lab. For now, you must send the transaction from Lab, because it can't return the signed transaction to the CLI. ```sh stellar tx new create-account \ @@ -63,7 +63,7 @@ stellar tx new create-account \ ## `tx send` -Finally, to submit the transaction to the network you can use the `tx send` command. This command will submit the transaction to the network. +Finally, to submit the transaction to the network, use the `tx send` command: ```sh stellar tx new create-account \ diff --git a/cookbook/upload-wasm.mdx b/cookbook/upload-wasm.mdx index 87cb78a76e..c5ca3bc400 100644 --- a/cookbook/upload-wasm.mdx +++ b/cookbook/upload-wasm.mdx @@ -14,6 +14,6 @@ stellar contract upload \ -Note this command will return the hash ID of the Wasm bytecode, rather than an address for a contract instance. +This command returns the hash of the Wasm bytecode, not the address of a contract instance. From f2c934a5865ad8120a8917cd1ed894190ff84892 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 12 Nov 2026 15:10:04 -0600 Subject: [PATCH 2/2] fix(docs): Use Mintlify steps in the lifecycle and payments recipes --- cookbook/contract-lifecycle.mdx | 34 +++++++++++++++++++++++++------- cookbook/payments-and-assets.mdx | 32 ++++++++++++++++++++++++------ 2 files changed, 53 insertions(+), 13 deletions(-) diff --git a/cookbook/contract-lifecycle.mdx b/cookbook/contract-lifecycle.mdx index d7d790c9c0..81f99e612b 100644 --- a/cookbook/contract-lifecycle.mdx +++ b/cookbook/contract-lifecycle.mdx @@ -5,25 +5,35 @@ 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. Set your preferred network. This guide uses `testnet`. See [Networks](/docs/networks) for the list of available networks. + + + + +This guide uses `testnet`. See [Networks](/docs/networks) for the list of available networks. ```bash stellar network use testnet ``` -2. Create an identity for Alice: + + + ```bash stellar keys generate alice -q ``` -3. Fund the identity: + + + ```bash stellar keys fund alice ``` -4. Deploy a contract: + + + ```bash stellar keys use alice @@ -41,13 +51,17 @@ CBB65ZLBQBZL5IYHDHEEPCVUUMFOQUZSQKAJFV36R7TZETCLWGFTRLOQ To learn more about how to build contract `.wasm` files, take a look at our [getting started tutorial](/docs/build/smart-contracts/getting-started/setup). -5. Invoke a contract function: + + + ```bash stellar contract invoke --id mycontract -- ``` -6. View the contract's state: + + + ```bash stellar contract read --id mycontract --durability --key @@ -55,10 +69,16 @@ stellar contract read --id mycontract --durability --key `` is either `persistent` or `temporary`. `` is the key of the storage entry being read. -7. Extend the TTL of the contract's state: + + + ```bash stellar contract extend --id mycontract --ledgers-to-extend 1000 --durability --key ``` This extends the TTL of the storage entry with the given key to at least 1,000 ledgers from the current ledger. + + + + diff --git a/cookbook/payments-and-assets.mdx b/cookbook/payments-and-assets.mdx index 657f7a72a4..cc80a470ed 100644 --- a/cookbook/payments-and-assets.mdx +++ b/cookbook/payments-and-assets.mdx @@ -5,13 +5,19 @@ description: Send XLM and other Stellar assets using the Stellar CLI To send payments and work with assets using the Stellar CLI, follow these steps: -1. Set your preferred network. This guide uses `testnet`. See [Networks](/docs/networks) for the list of available networks. + + + + +This guide uses `testnet`. See [Networks](/docs/networks) for the list of available networks. ```bash stellar network use testnet ``` -2. Fund the accounts: + + + ```bash stellar keys generate alice @@ -29,19 +35,27 @@ stellar keys generate bob stellar keys fund bob ``` -3. Get the contract ID of the native asset's Stellar Asset Contract: + + + ```bash stellar contract id asset --asset native ``` -4. Get Bob's public key: + + + ```bash stellar keys address bob ``` -5. Send 100 XLM from Alice to Bob: + + + + +The Stellar Asset Contract takes amounts in stroops (1 XLM = 10,000,000 stroops), so this sends 100 stroops: ```bash stellar keys use alice @@ -51,10 +65,16 @@ stellar keys use alice stellar contract invoke --id -- transfer --to bob --from alice --amount 100 ``` -6. Check Bob's balance: + + + ```bash stellar contract invoke --id -- balance --id bob ``` + + + + For more information on the functions available on the Stellar Asset Contract, see the [token interface code](/docs/tokens/token-interface#code).