An immutable Soroban job-escrow kernel based on ERC-8183 Agentic Commerce, with allowlisted policy hooks and a relayed-auth TypeScript SDK.
This project is testnet-only and unaudited. Do not use it with mainnet funds.
An official release deployment is valid only when its contract IDs, fetched
Wasm hashes, transactions, and source commit appear in a schema-valid evidence
manifest whose status is verified. A deployment manifest proves the on-chain
run but is still pending publication/provenance gates. The absence of
deployments/testnet.json means there is no endorsed deployment yet.
The tag workflow publishes the reviewed provisional manifest as
evidence.deployment.json together with its hash-bound, whitelist-only
evidence.raw.json. After the demo recording has been attached manually, a
separate workflow-dispatch gate reruns semantic validation and re-downloads and
verifies the release Wasm, GitHub attestations, npm tarball/provenance, and
recording before scripts/promote-evidence.mjs can add
evidence.verified.json. The provisional assets remain for audit history; only
the verified asset is final release evidence. Each manifest is hashed only
after serialization and has a detached .sha256 release asset; a manifest
never embeds its own impossible self-hash.
To avoid a commit self-reference, release.source_commit names the clean
source/build/deployment commit. v0.1.0 names its evidence-only child commit,
whose diff is exactly deployments/testnet.json and
deployments/testnet.raw.json; the release workflow enforces that relationship
before building or publishing.
Watch the 78-second live testnet verification. It records actual Terminal commands and live Horizon responses, followed by a Playwright-controlled Chrome window showing the completion and permissionless refund transactions in Stellar Expert. The recording verifies previously finalized July 30, 2026 transactions; it does not submit a fresh transaction.
This remains testnet-only, unaudited deployment evidence. The live kernel
bytes differ from the public v0.1.0 release kernel, so the demo does not claim
byte-for-byte release provenance. See the transcript,
public evidence links,
captions, and
SHA-256 checksum.
The audit contact sheet
provides a quick visual index of the recording.
- The complete six-state ERC-8183 lifecycle: Open → Funded → Submitted → Completed/Rejected/Expired.
- One immutable SEP-41 payment token per kernel deployment.
- Client/provider budget negotiation and exact-budget funding protection.
- Full payment on completion, full refund on rejection/expiry, and no protocol fees.
- Permissionless
claim_refund, deliberately outside the hook system. - Before/after callbacks for the other six mutations, with admin admission and atomic rollback.
- An immutable SLA hook that preserves an evaluator review window.
- Persistent per-job storage with threshold TTL extension, pinned Protocol 23 same-envelope restoration keys, and an exact-key guarded separate restore-footprint fallback.
@trionlabs/stellar-8183, covering the full ABI, commitments, token units, secret-whitelisted raw evidence capture, and strict multi-party relay validation.
The normative target is the draft at
ethereum/ERCs@a078cab5cc8e9581c15f76c091ed96eed28f02f7. Its embedded Solidity
sample conflicts with its own specification; this project follows the normative
prose. The reviewed discrepancies are recorded in
ERC-8183 conformance.
Open ── fund ──────────────> Funded ── submit ──> Submitted ── complete ──> Completed
│ │ │
└─ client reject ─> Rejected├─ evaluator reject ───┴───────────────────> Rejected
└─ expired refund ──────┴───────────────────> Expired
The evaluator is a designated trusted address, not an arbitration system. At or after expiry, a still-valid provider/evaluator action and a refund can race; the first successful ledger transaction wins. Jobs that require an evaluation buffer can opt into the SLA hook.
Pinned development tools are Rust 1.96.0, wasm32v1-none, Soroban SDK 27.0.3,
Stellar CLI 27.0.0, Node 22, pnpm 11.9.0, and Stellar SDK 16.2.0.
corepack enable
pnpm install --frozen-lockfile
make check
make build
./scripts/verify-release.shDeployable optimized Wasm is built through Stellar CLI:
./scripts/release-build.shThe release artifacts are
artifacts/release/stellar_8183_commerce.wasm and
artifacts/release/stellar_8183_sla_hook.wasm. The release build embeds
source_repo=github:trionlabs/stellar-8183; publish that repository before
treating its SEP-55 provenance as meaningful.
See testing.md for the adversarial matrix and CONTRIBUTING.md for change requirements.
After publication:
npm install @trionlabs/stellar-8183Connect to the deployed kernel without giving the SDK a secret:
import { AgenticCommerce } from "@trionlabs/stellar-8183";
const commerce = await AgenticCommerce.connect({
contractId,
networkPassphrase,
publicKey: facilitatorAddress,
rpcUrl,
});Mutation methods prepare and simulate an invocation; they do not silently sign
or submit it. prepareRelay, authorizeRelay, and facilitateRelay implement
the intended flow:
- discover role authorization with recording-mode simulation;
- sign the exact auth entry as client, provider, or evaluator;
- validate it with enforcing-mode simulation;
- strictly validate and rebuild the envelope with a distinct facilitator;
- freshly simulate, sign as transaction source, submit, and wait for success.
The SDK takes SEP-43-compatible signer callbacks and does not accept or store secret keys. See the package guide for code and the EVM/Soroban mapping for the authorization model.
- Stellar ledgers currently close roughly every five seconds. That is not sub-second finality; always wait for a successful transaction result.
- A facilitator can pay transaction fees in XLM while another address authorizes the contract invocation.
- Fee sponsorship does not erase G-account reserve requirements. A normal client/provider G-account still needs an account reserve, and a classic asset trustline adds reserve. Sponsored reserves or C-account wallets are separate integration choices.
- Persistent and instance storage can archive. Since Protocol 23, fresh
simulation can include archived entries in the same invocation envelope; the
relay pins those exact keys. Stellar SDK's separate
restoreFootprintfallback is disabled unless an independently derived exact-ledger-key, bounded-fee policy is supplied. Manually assembled stale transactions may fail. - Successful events are transaction metadata, not permanent contract storage, and RPC event retention can be short. Capture evidence promptly.
The testnet release uses official test USDC:
| Property | Value |
|---|---|
| Issuer | GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 |
| SEP-41 contract | CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA |
| Decimals | 7 |
These are public testnet constants, not a live kernel deployment.
| Path | Purpose |
|---|---|
contracts/interfaces |
Shared jobs, hook context, errors, events, and callback client |
contracts/commerce |
Immutable escrow kernel |
contracts/sla-hook |
Reference review-window hook |
contracts/test-hooks |
Adversarial fixtures; not release policy contracts |
packages/sdk |
TypeScript client and relay safety layer |
docs |
Protocol, conformance, security, TTL, testing, and public evidence specification |
- Exact contract ABI and events
- ERC-8183 conformance and sample discrepancies
- ERC/EVM to Stellar/Soroban mapping
- Storage, TTL, archival, and restoration
- Security and threat model
- Test and acceptance matrix
- Testnet/release runbook
- Evidence JSON Schema and unfilled shape template
- Assembler input template
- Original statement of work
Version 0.1.0 does not include mainnet deployment, a security audit, disputes or arbitration, threshold evaluators, identity/reputation, fees, pausing, token sweeping, contract upgrades, per-job token selection, cross-chain jobs, or a front-end.