Developer setup

Build and test

cargo build --workspace --all-targets
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check

Rust 1.98.1 is the pinned toolchain (workspace.package.rust-version in the root Cargo.toml). CI runs all four of the above on every push to main and every pull request.

Reproducing the golden vectors

Every function in sorocharge-signer that produces XDR is tested against fixtures generated by a pinned @stellar/stellar-sdk version — not committed blindly, regenerated and diffed in CI:

cd tests/golden_vectors
npm ci
node generate.mjs
git diff --exit-code fixtures   # should report no changes

If that diff is non-empty, either the pinned SDK version changed (it shouldn’t have — it’s an exact pin in package.json) or sorocharge-signer’s output genuinely changed. Either way, that’s a signal to stop and look, not to update the fixtures and move on.

Running the examples against testnet

Every example takes its signing key from an environment variable — never hardcoded, never committed. Fund a testnet account at friendbot and export its S... secret seed.

The fastest way to see the whole system work end to end needs no external resource server at all — verify_and_settle plays both the payer and the facilitator itself:

export SOROCHARGE_TESTNET_PAYER_SECRET_KEY=S...
export SOROCHARGE_TESTNET_FACILITATOR_SECRET_KEY=S...
export SOROCHARGE_TESTNET_ASSET_CONTRACT=CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC  # testnet native XLM SAC
cargo run --example verify_and_settle -p sorocharge-x402

That asset contract is testnet’s native-XLM Stellar Asset Contract — no trustline needed, since friendbot already funds the account in XLM.

To see the actual HTTP flow, run a resource server and a client in separate shells:

# shell 1
export SOROCHARGE_TESTNET_FACILITATOR_SECRET_KEY=S...
export SOROCHARGE_TESTNET_ASSET_CONTRACT=CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC
cargo run --example resource_server_x402 -p sorocharge-x402

# shell 2
export SOROCHARGE_TESTNET_SECRET_KEY=S...     # a different, funded account
export SOROCHARGE_X402_RESOURCE_URL=http://127.0.0.1:8402/resource
cargo run --example sign_x402_payment -p sorocharge-x402

The MPP equivalents are resource_server_mpp and sign_mpp_charge in sorocharge-mpp’s examples/, with SOROCHARGE_MPP_FEE_PAYER=false on the server to exercise the unsponsored flow instead of the sponsored default.

Building this documentation site

cargo install mdbook   # if you don't have it
cd docs
mdbook build           # writes docs/book/
mdbook serve           # or, serve it locally with live reload