Skip to main content

Build and deploy a contract

Have your agent create a contract project, build it, deploy it to testnet, and call it. The project comes with an AGENTS.md file that tells your agent how to work in it.

Ask your agent​

Create a Stellar contract project called my-project, build it, deploy it to testnet from agent-1, and call its hello function.

Before you start​

  • Follow the Quickstart first. stellar contract init writes AGENTS.md from stellar-cli 28.0.0 on.
  • Install Rust 1.84 or later and the wasm32v1-none target with rustup target add wasm32v1-none. Rust 1.82 and 1.83 cannot build contracts.
  • Fund a testnet identity, for example agent-1 from the Quickstart.

Steps​

  1. Create the project:

    stellar contract init my-project
    cd my-project

    This writes a Cargo workspace with one contract in contracts/hello-world, plus README.md and AGENTS.md at the workspace root. Pass --name <NAME> for a different contract name.

  2. Build every contract in the workspace:

    stellar contract build

    The WASM file lands at target/wasm32v1-none/release/hello_world.wasm. The file name uses _ where the package name has -. Add --package <NAME> to build one contract.

  3. Deploy the contract and save an alias for it:

    ID=$(stellar contract deploy --wasm target/wasm32v1-none/release/hello_world.wasm --source agent-1 --network testnet --alias hello_world)

    stdout is the contract ID alone, on one line. --alias replaces an existing alias of the same name without asking, and warns about it on stderr.

    Inside a workspace you can leave out --wasm. deploy then builds first, deploys every contract, uses each package name as its alias, and prints one contract ID per line.

  4. Call the contract:

    stellar contract invoke --id hello_world --source agent-1 --network testnet -- hello --to world

    stdout is the return value as one line of JSON, here ["Hello","world"]. A function with no return value prints an empty line.

    hello only reads, so the CLI simulates the call and does not submit a transaction. It says so on stderr. Add --send=yes to submit it anyway. A call that writes state, emits an event, or needs authorization is submitted by default.

    To list a deployed contract's functions and their arguments, run stellar contract invoke --id hello_world --network testnet -- -h. It prints the list on stdout and exits with code 1, so do not treat that exit code as a failure.

Read stdout, not --output json​

contract init, contract build, contract deploy, and contract invoke have no --output flag. Output and errors lists the commands that do. Parse these four by stream:

Commandstdoutstderr
contract initNothingEach file it writes or skips
contract buildNothing to parseCargo progress and the build summary
contract deployThe contract IDUpload and deploy progress, and the alias warning
contract invokeThe return value as JSONSimulation and submission progress

Keep the two streams apart. 2>&1 mixes progress lines into the value you parse. A failure prints ❌ error: ... on stderr and exits non-zero, so check the exit code before you read stdout.

The generated AGENTS.md​

stellar contract init writes AGENTS.md at the workspace root. It is a short Markdown brief for coding agents. It covers:

  • Layout: the workspace Cargo.toml, and each contract's src/lib.rs and src/test.rs under contracts/<name>/.
  • Build: stellar contract build, where the WASM files land, and --package for one contract. It tells the agent not to use cargo build --target wasm32v1-none, because stellar contract build applies the flags and metadata the network expects.
  • Toolchain: the wasm32v1-none target and Rust 1.84 or later.
  • Test: cargo test, or cargo test -p <name> for one contract.
  • Deploy and invoke: testnet commands for the sample hello function, and -- -h to list a deployed contract's functions.
  • Further reading: links to the smart contract docs and soroban-examples.

The template lives in the CLI source at contract-workspace-template/AGENTS.md.

AGENTS.md describes this project. stellar skill describes the CLI itself. Give your agent both.

How agents pick it up​

AGENTS.md follows the AGENTS.md convention. Agents that support it read the file when they work in the project, so there is nothing to install or run. If your agent reads a different instructions file, add a line there that points to AGENTS.md.

The file is a copy made when you ran init. It does not change when you upgrade the CLI.

Customize it​

AGENTS.md is a plain file in your project. Edit it and commit it with the rest of your code. Useful changes:

  • Replace the hello sample with your own contract names, functions, and arguments.
  • Name the identity and network the agent must use, for example --source agent-1 --network testnet.
  • Add your own rules, for example "run cargo test before every deploy".

A rule in AGENTS.md is an instruction to the agent, not a limit the CLI enforces. To limit what an agent can spend, see Delegate spending.

Running init again keeps your edits. For example, stellar contract init . --name increment adds a contract and skips every file that already exists, AGENTS.md included. --overwrite replaces every template file, AGENTS.md included, so save your changes before you use it.