Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions cookbook/asset-management.mdx
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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 \
Expand All @@ -57,37 +57,37 @@ 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 \
--set-revocable \
--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.

The asset code along with the issuer account address will uniquely identify the asset. An issuer can issue multiple assets, distinguished by their asset code.

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.

Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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
10 changes: 5 additions & 5 deletions cookbook/contract-build-meta.mdx
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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)
Expand Down
30 changes: 15 additions & 15 deletions cookbook/contract-invoke-arguments.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <value>` 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.

Expand All @@ -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.

Expand All @@ -24,7 +24,7 @@ stellar contract invoke --id mycontract -- my_function \
--amount 340282366920938463463374607431768211455
```

### Boolean
## Boolean

Pass `true` or `false` as unquoted literals.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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).

Expand All @@ -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.

Expand All @@ -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<T>` parameter that is not provided.

Expand All @@ -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.

Expand All @@ -107,7 +107,7 @@ stellar contract invoke --id mycontract -- my_function \
--recipients '["alice", "bob", "carol"]'
```

### Map
## Map

Pass a JSON object with string keys.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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`.

Expand All @@ -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 \
Expand Down
Loading
Loading