[Hassan-oladipupo]

Summary

Four docs for teams consuming the live testnet deployment: guidance for writing your own integration suite, two tooling specifications, and a decision log explaining why testnet/tooling/ holds specs rather than code.

File	Purpose
testnet/examples/integration-test-harness-notes.md	Guidance for a consuming project's integration suite against live testnet
testnet/tooling/nonce-inspector-spec.md	Spec: read-only helper printing the current on-chain nonce
testnet/tooling/faucet-helper-spec.md	Spec: fund + initialise a fresh test account in one step
testnet/tooling/decision-log.md	Why tooling specs live here rather than as runnable scripts

Integration harness notes

scripts/test.sh runs cargo test against an in-process Soroban environment — no network, no fees. That is the right tool for contract logic and the wrong tool for anything depending on a real deployment, so this doc covers what a live suite is actually for, and splits out the assertions an in-process test cannot make (balance conservation, WASM-vs-deployment drift, RPC behaviour, nonce contention).

The two sections that took the most care:

Latency — budget ~15 s per state-changing step, sequence state transitions rather than parallelising them, prefer simulate_sweep() for pre-flight, and never use a fixed sleep as a synchronisation primitive.

Shared-state hygiene — the testnet deployment is shared, and the failure mode is concrete: SweepController keeps a single nonce for all accounts, so another integrator's sweep invalidates a signature you are holding, and the symptom is a bare ed25519_verify trap with no error code. The doc gives the rules that follow (re-read immediately before signing, serialise per controller, treat a trap as retryable, bound the retries) and draws an explicit line at what a suite may touch: it may create its own accounts, it may not change shared configuration.

It also records several things that will otherwise cost a reader an afternoon: cleanup does not reclaim anything (expire() moves no tokens), there is no local sandbox so expiry tests are genuinely ledger-bound, SweepController has no getters so a whole suite failing with UnauthorizedDestination usually means the shared controller is in locked mode rather than a bug in your code, and scripts/deploy-testnet.sh currently aborts on an unassigned RESERVE_CONTRACT_ID.

Tooling specs

Both specs are read-only or single-account by construction, so neither can grief the shared deployment — that property is stated as a design constraint rather than assumed. The nonce inspector multi-samples to expose churn before you pay a fee to have a stale signature rejected, and the faucet helper echoes the recovery_address prominently because it cannot be corrected after initialize().

Neither spec is implemented. Each opens with an explicit status line.

Decision log

testnet/tooling/ currently contains no runnable tools, which looks like an error and invites three reasonable-but-wrong reactions. The log records that the batch was explicitly scoped away from scripts/, that specs-not-tools is deliberate for now, and — the important part — that where runnable tools should live has not been decided. It inventories the open questions, states what would count as legitimately "fixing" the directory, and distinguishes scripts/ (repo build/CI entrypoints) from testnet-facing integrator tooling as a real category difference rather than a location preference.

It also flags a risk to the whole batch: these tools mostly work around the absence of a local sandbox, so if one is ever added they should be re-evaluated before being built.

Scope

• Documentation only. No contract, script, or tool changes.
• tools/sweep-signer is referenced contextually and not modified.
• testnet/tooling/README.md (the index) is tracked separately under testnet/tooling/README.md: index proposed testnet-facing tooling that lives outside the project's scripts/ folder #643 and is intentionally left alone; this PR adds the decision-log.md that testnet/tooling/README.md follow-up: add a decision log noting why tooling specs live here rather than as actual scripts #649 asks for.
• Every claim about contract behaviour is checked against contracts/sweep_controller/src/, contracts/ephemeral_account/src/, and contracts/sweep_controller/src/errors.rs rather than restated from docs/api-reference.md.

Closes #642
Closes #647
Closes #648
Closes #649

[drips-wave]

@Hassan-oladipupo Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits