Skip to content

SPINE.md

Latest commit

 

History

History
148 lines (123 loc) · 9.19 KB

SPINE.md

File metadata and controls

148 lines (123 loc) · 9.19 KB
Raw

The spine — what stellar-pay is, and what every piece is for

Companion to ROADMAP.md (what's next) and PARITY.md (how we compare to pay.sh). This is the one document that says what the whole thing IS, so a new build either serves the loop below or it doesn't ship.

One sentence

stellar-pay is the neutral, self-custody layer for human-to-agent work on Stellar — an agent CLI and a toolkit where you fund an agent safely, hire it for real work under an escrowed agreement, get that work verified and paid automatically, and carry provable reputation from what it completed.

Three things at once, deliberately:

  • an agent CLI (the pay.sh-shaped client an agent or human runs — curl, session, bounty, receipts, and the MCP that exposes them as agent tools; the job lifecycle is library-only, reached from the CLI via bounty),
  • a toolkit (the same capabilities as importable modules — pay/job, pay/resolver, pay/rails (reputation is a DESIGN PHASE, not a module — see reputation-design-questions.md) — a builder drops into their own agent),
  • a layer (neutral and self-custody: consumes every rails provider, takes no fee, holds no keys — the coordination layer the ecosystem builds on, not a platform it depends on).

The thesis (why this and not "a payments CLI")

Before agent-to-agent commerce goes mainstream, human-to-agent commerce is the wedge: people will pay agents to do real work. The layer that decides whether that works is not payment alone — it is payments + reputation + task-verification-tied-to-agreements + fulfillment. Payment is table stakes (Circle, Merit, pay.sh all have it). The differentiated, defensible layer — the one nobody else has on Stellar — is the work layer: escrow + agreement + automated resolution + portable work-reputation.

We build that layer neutrally and self-custody: the agent holds its own keys, we take no fee, we consume every rails provider. That is the deliberate opposite of the platform pole (Circle Agents is hosted, with MPC key shares in their infrastructure and spend limits enforced by their policy engine — a policy promise, not a chain rule; we are the client + the coordination layer they explicitly refuse to build — "ranking is not adjudication; a discovery layer never holds funds").

The loop (every feature is one beat of this)

   fund ───────► hire ───────► verify ───────► pay ───────► reputation
  (vault)       (job open      (resolver       (release/     (receipts →
                 + escrow +     reads terms     refund on-     per-agent
                 agreement)     + evidence,     chain)         work record)
                                judges)                            │
                                                                   ▼
                                                        who to hire next time

A human (or an agent) funds a capped vault, hires an agent under an escrowed agreement whose terms live on-chain, the resolver verifies the delivered work against those terms and releases or refunds automatically, and the outcome becomes a costly-to-fake reputation signal that informs the next hire.

What each piece is FOR (flagship vs supporting cast)

Flagship — the work layer (ours alone on Stellar):

piece file(s) role in the loop
Agreement pay/agreement.ts the terms: a resolver-readable doc (Terms / Review Question / Allowed Evidence / Resolution Effects), sha256-addressed, pinned on-chain. Stellar-native; AutoContracts is credited prior art, not a standard we emit.
Escrow rails pay/rails.ts + pay/rails-trustless-work.ts hold-verify-release mechanics. A swappable adapter — Trustless Work today; MPP-native or Alkahest-on-Stellar tomorrow is a new file + setRails(), never a rewrite.
Job lifecycle pay/job.ts open → fund → deliver → approve → release / dispute → resolve, each step a ref-chained receipt.
Resolver pay/resolver.ts the "auto service" that fills the escrow's resolver role: reads terms + evidence, answers the review question via a policy (hash-match = deterministic; callback = delegated judge, honest about its strength), executes the outcome.
Reputation (design phase — deliberately not building yet) reputation-design-questions.md aggregates work-outcomes into a per-agent record. Parked for deep design: if it one day underwrites credit lines for agents, a gameable score is a solvency risk, not an annoyance. The receipts substrate keeps accruing meanwhile — the record is free; the score waits.

Supporting cast — table stakes that make the flagship usable:

piece file(s) why it's here
Pay a 402 pay/curl.ts, pay/offers.ts the agent pays for its own inputs (APIs, data, inference). x402 + MPP.
Session mode pay/session.ts high-frequency paying via one-way channels — a busy agent loop.
Vault pay/vault.ts, smart-account-kit fund an agent safely: on-chain spend caps a compromised key can't exceed. This is "fund" in the loop.
Wallet / keystore pay/wallet.ts, pay/keystore.ts self-custody keys, OS-keychain sealed.
Governance pay/policy.ts, pay/governed.ts + vendored Scrimp per-host spend rules + outcome-attributed budget.
Receipts pay/receipts.ts the substrate under BOTH pay and work: content-addressed, tamper-checked, on-chain-verifiable. Reputation reads these.
MCP mcp.ts every verb as an agent tool — the primary consumer is an agent, not a human at a shell.

The quality bar (Circle + Merit, made concrete)

  1. Costly-to-fake, and describe ≠ adjudicate. Reputation is grounded in escrow-judged outcomes (real money moved through a resolver's decision), never self-declared feedback or raw payment volume. The resolver adjudicates and holds funds; reputation only describes. Keep them separate layers.
  2. One sharp, adoptable primitive over a sprawling toolkit. Merit's echo is one thing people install. The work layer is our echo: package it so a builder drops it in (CLI verbs + MCP tools + a clean SDK surface), not a pile of features.
  3. Neutral and self-custody, always. No fee, no custody, every rails provider consumable. The moment we take a cut or hold keys we are just a smaller Circle.
  4. Every non-trivial step proven on testnet, end to end, with an on-chain check. Not "it compiles" — a receipt whose tx a stranger can verify.

Layer first, then products ON the layer

The strategic sequence, decided 2026-08-30. The question was "stay a layer forever, or become a platform?" — and the answer is that this is a false choice. The trap is not HAVING products; it is making the layer depend on them. The shape that works (Circle: USDC the layer, Circle Agents the product; Merit: x402 infra the layer, echo the product):

  1. The layer stays neutral forever — open, no fee, no custody, anyone can run their own resolver, read receipts, and use the CLI without ever touching a product of ours.
  2. Products are built ON the layer, on the same terms anyone else could build them. We dogfood our own primitive and monetize the PRODUCT, never the rails. Candidate products, in rough order:
    • a verification bounty surface (our own first: hire agents to verify stellarlight directory rows — we are the first buyer, the jobs are real, the receipts are real);
    • a resolver service we operate (an instance of the open resolver — others can run competitors on the same layer, which is the point);
    • eventually a reputation read surface — only after the design phase resolves (reputation-design-questions.md).
  3. The test for any product: if we shut it down tomorrow, the layer and everyone else's products keep working. If a product fails that test, it has captured the layer and must be re-cut.

(Cut 2026-08-30: "hackathon payout rails" — owner call. Humans paying humans prize money is not agent commerce; the thesis is people paying AGENTS for work. Escrowed payouts remain possible ON the layer for anyone who wants them; they are not our product.)

What this doc forbids

  • Building payment features as if payments were the product. They're the floor.
  • Reputation from self-declared or volume signals (Circle's explicit trap).
  • Coupling to one rails provider. The adapter boundary is load-bearing.
  • Taking a fee or custody. That trades the whole position away.

Status (2026-08-30)

Flagship: agreement ✓, escrow rails ✓ (TW adapter, testnet), job lifecycle ✓, resolver ✓ (both outcomes proven on testnet). Reputation: design phase — the last flagship pillar, deliberately parked for deep planning (reputation-design-questions.md); underwriting-grade or not at all. Supporting cast: pay/session/vault/receipts/MCP all built and testnet-proven. Mainnet gated on the escrow contract's audit (the standing SDF ask). Published: npm stellar-pay@0.1.8, public repo, public catalog branch feed — breaking changes to the CLI verbs, exit codes, MCP tool names or catalog.json shape now need a version bump.