From 0097f7c88b27b9fc75b2d0e92b83658cbb22c92f Mon Sep 17 00:00:00 2001 From: Rohan Singh Date: Mon, 17 Aug 2026 16:32:29 +0530 Subject: [PATCH 1/3] Add AGENTS.md to the stellar contract init workspace template. New projects get agent-oriented build, test, and deploy guidance at the workspace root so coding agents can work without extra setup. Co-authored-by: Cursor --- cmd/crates/soroban-test/tests/it/init.rs | 5 ++ cmd/soroban-cli/src/commands/contract/init.rs | 19 +++++- .../contract-workspace-template/AGENTS.md | 66 +++++++++++++++++++ .../contract-workspace-template/README.md | 1 + 4 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md diff --git a/cmd/crates/soroban-test/tests/it/init.rs b/cmd/crates/soroban-test/tests/it/init.rs index c2b8678dc3..21ecc98313 100644 --- a/cmd/crates/soroban-test/tests/it/init.rs +++ b/cmd/crates/soroban-test/tests/it/init.rs @@ -39,6 +39,11 @@ fn init() { .arg(".") .assert() .success(); + sandbox + .dir() + .child("AGENTS.md") + .assert(predicate::str::contains("stellar contract build")); + sandbox .dir() .child("Cargo.toml") diff --git a/cmd/soroban-cli/src/commands/contract/init.rs b/cmd/soroban-cli/src/commands/contract/init.rs index 47f21d955a..787a5d9c33 100644 --- a/cmd/soroban-cli/src/commands/contract/init.rs +++ b/cmd/soroban-cli/src/commands/contract/init.rs @@ -196,6 +196,7 @@ mod tests { runner.run().unwrap(); assert_base_template_files_exist(&project_dir); + assert_agents_md_covers_build_and_test(&project_dir); assert_contract_files_exist(&project_dir, "hello_world"); assert_excluded_paths_do_not_exist(&project_dir); @@ -224,12 +225,28 @@ mod tests { // test helpers fn assert_base_template_files_exist(project_dir: &Path) { - let expected_paths = ["contracts", "Cargo.toml", "README.md"]; + let expected_paths = ["contracts", "Cargo.toml", "README.md", "AGENTS.md"]; for path in &expected_paths { assert!(project_dir.join(path).exists()); } } + fn assert_agents_md_covers_build_and_test(project_dir: &Path) { + let agents = read_to_string(project_dir.join("AGENTS.md")).unwrap(); + assert!( + agents.contains("stellar contract build"), + "AGENTS.md should document stellar contract build" + ); + assert!( + agents.contains("cargo test"), + "AGENTS.md should document cargo test" + ); + assert!( + agents.contains("wasm32v1-none"), + "AGENTS.md should mention the WASM target" + ); + } + fn assert_contract_files_exist(project_dir: &Path, contract_name: &str) { let contract_dir = project_dir.join("contracts").join(contract_name); diff --git a/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md b/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md new file mode 100644 index 0000000000..b3d735ddfe --- /dev/null +++ b/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md @@ -0,0 +1,66 @@ +# Agent instructions + +This is a Stellar smart-contract workspace (Soroban). Each contract is a +workspace member under `contracts//`. + +## Layout + +- `Cargo.toml` — workspace root; contract crates inherit `soroban-sdk` from here +- `contracts//src/lib.rs` — contract implementation (`#![no_std]`) +- `contracts//src/test.rs` — host-side unit tests + +## Build + +From the workspace root: + +```sh +stellar contract build +``` + +That compiles every `cdylib` member to WASM. Artifacts land in +`target/wasm32v1-none/release/*.wasm`. Build one crate with +`stellar contract build --package `. + +Do not substitute `cargo build --target wasm32v1-none`. `stellar contract build` +applies the flags and metadata the network expects. + +The `wasm32v1-none` Rust target must be installed (`rustup target add wasm32v1-none`). +Rust 1.84 or newer is required for that target. Rust 1.82 and 1.83 cannot build +contracts. + +## Test + +Host tests run with the normal Cargo test harness (not on-chain): + +```sh +cargo test +``` + +A single crate: `cargo test -p `. + +## Deploy and invoke + +On testnet, after a successful build: + +```sh +stellar contract deploy \ + --wasm target/wasm32v1-none/release/.wasm \ + --source-account \ + --network testnet \ + --alias + +stellar contract invoke \ + --id \ + --network testnet \ + --source-account \ + -- hello --to world +``` + +The sample `hello_world` contract exposes `hello(to: String) -> Vec`. +Replace that with your own functions; `stellar contract invoke --id -- -h` +prints the generated CLI for the deployed contract. + +## Further reading + +- https://developers.stellar.org/docs/build/smart-contracts/overview +- https://github.com/stellar/soroban-examples diff --git a/cmd/soroban-cli/src/utils/contract-workspace-template/README.md b/cmd/soroban-cli/src/utils/contract-workspace-template/README.md index 8b445e4ceb..843446db0c 100644 --- a/cmd/soroban-cli/src/utils/contract-workspace-template/README.md +++ b/cmd/soroban-cli/src/utils/contract-workspace-template/README.md @@ -13,6 +13,7 @@ This repository uses the recommended structure for a Soroban project: │   │   └── test.rs │   └── Cargo.toml ├── Cargo.toml +├── AGENTS.md └── README.md ``` From b8a61f206e5eb96bf0b42111b7c0826887c0c077 Mon Sep 17 00:00:00 2001 From: Rohan Singh Date: Mon, 17 Aug 2026 16:52:37 +0530 Subject: [PATCH 2/3] Potential fix for pull request finding Minor change Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md b/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md index b3d735ddfe..b5af335bf4 100644 --- a/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md +++ b/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md @@ -21,7 +21,7 @@ That compiles every `cdylib` member to WASM. Artifacts land in `target/wasm32v1-none/release/*.wasm`. Build one crate with `stellar contract build --package `. -Do not substitute `cargo build --target wasm32v1-none`. `stellar contract build` +Do not substitute this with `cargo build --target wasm32v1-none`. `stellar contract build` applies the flags and metadata the network expects. The `wasm32v1-none` Rust target must be installed (`rustup target add wasm32v1-none`). From 2611da44b6eb70b911d829928d6870d75fb3bf86 Mon Sep 17 00:00:00 2001 From: Nando Vieira Date: Mon, 17 Aug 2026 15:57:31 -0300 Subject: [PATCH 3/3] Format file. --- .../contract-workspace-template/AGENTS.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md b/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md index b5af335bf4..d4a64dfbac 100644 --- a/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md +++ b/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md @@ -1,7 +1,6 @@ # Agent instructions -This is a Stellar smart-contract workspace (Soroban). Each contract is a -workspace member under `contracts//`. +This is a Stellar smart-contract workspace (Soroban). Each contract is a workspace member under `contracts//`. ## Layout @@ -17,16 +16,11 @@ From the workspace root: stellar contract build ``` -That compiles every `cdylib` member to WASM. Artifacts land in -`target/wasm32v1-none/release/*.wasm`. Build one crate with -`stellar contract build --package `. +That compiles every `cdylib` member to WASM. Artifacts land in `target/wasm32v1-none/release/*.wasm`. Build one crate with `stellar contract build --package `. -Do not substitute this with `cargo build --target wasm32v1-none`. `stellar contract build` -applies the flags and metadata the network expects. +Do not substitute this with `cargo build --target wasm32v1-none`. `stellar contract build` applies the flags and metadata the network expects. -The `wasm32v1-none` Rust target must be installed (`rustup target add wasm32v1-none`). -Rust 1.84 or newer is required for that target. Rust 1.82 and 1.83 cannot build -contracts. +The `wasm32v1-none` Rust target must be installed (`rustup target add wasm32v1-none`). Rust 1.84 or newer is required for that target. Rust 1.82 and 1.83 cannot build contracts. ## Test @@ -56,9 +50,7 @@ stellar contract invoke \ -- hello --to world ``` -The sample `hello_world` contract exposes `hello(to: String) -> Vec`. -Replace that with your own functions; `stellar contract invoke --id -- -h` -prints the generated CLI for the deployed contract. +The sample `hello_world` contract exposes `hello(to: String) -> Vec`. Replace that with your own functions; `stellar contract invoke --id -- -h` prints the generated CLI for the deployed contract. ## Further reading