Core

System Architecture

Five-layer architecture: consumer interface, AP2 authorization with versioned adapter, Soroban policy enforcement, x402 settlement, and Stellar network. Each layer composable and independently replaceable.

Layer Model

REAPP is five composable layers. The key design principle is that each layer can change independently. If AP2 releases a breaking v0.2 spec, only the adapter implementation changes — not the SDK, not the contracts, not the settlement layer. If a better facilitator emerges, swap the facilitator URL. If Stellar adds native features, update the settlement layer only.

REAPP Five-Layer Architecture
Layers 4 and 3 are the primary REAPP contribution. Layers 2 and 1 are existing infrastructure composed without modification. Layer 5 is the developer-facing surface.

Adapter-First Validator Architecture

The AP2 compliance validator is the highest-complexity single component in the stack. It is explicitly placed behind a versioned adapter interface — no other SDK component imports AP2 directly. This is the structural answer to both AP2 spec volatility and the AP2 vs ACP standards war.

Three adapter implementations are planned or contingency-scoped: the current AP2 v0.1 adapter (shipping with T1 PoC), a future AP2 v0.2+ adapter (activated via adapter swap when the spec stabilizes), and an ACP contingency adapter (scoped but not planned — triggered only if ACP adoption materially surpasses AP2).

AP2ValidatorAdapter — Versioned Interface Design
The SDK only ever calls the adapter interface. AP2 implementation details are fully encapsulated. Schema version pinning plus a conformance test suite catch upstream changes before they reach production.
// Nothing in @reapp/sdk imports AP2 directly
import type { AP2ValidatorAdapter } from '@reapp/sdk/adapter';

// At initialization — adapter is injected
const agent = createReappAgent({
  mandate,
  signer,
  mandateContract: CONTRACT_ADDRESS,
  validator: new AP2ValidatorAdapterV0_1({ schemaVersion: '0.1.2' }),
  //         ↑ swappable — SDK is adapter-agnostic
});

Validator Gate Chain

Seven sequential gates run before any signing happens. All seven must pass. A single failure returns an explicit rejection with reason code — no ambiguity, no partial state. The Soroban call is the final gate because it has side effects (counter update) — all stateless checks run first.

Validator Gate Chain — 7 Sequential Checks
Fail-fast ordering: cheapest checks first, Soroban write last. Every rejection returns a typed error with reason code. The agent SDK surfaces these as structured exceptions.

Mandate-to-Receipt Audit Linkage

Every REAPP payment produces a permanent, on-chain audit chain linking the original user mandate to the Stellar settlement receipt. The linkage is written atomically — both the mandate hash and transaction hash are recorded in the same Soroban operation or neither is. There is no partial state.

Mandate-to-Receipt Audit Chain
Verifiers reconstruct the full chain from mandate_id → mandate_hash → tx_hash → Stellar ledger record. The entire chain is on-chain and does not require REAPP infrastructure to verify.

Soroban Contract Data Model

MandateRegistry Contract — Entity Relationship
Five entities, four foreign key relationships. SETTLEMENT_RECORD is the audit linkage table — keyed by (mandate_hash, tx_hash) as a persistent storage entry that never expires.

Security Model

Six identified threat vectors with explicit mitigations. The fail-closed policy is the most important architectural decision: when mandate interpretation is ambiguous — missing field, unexpected value, schema version mismatch — the SDK rejects the payment by default. Agents do not fail open.

Threat Surface and Mitigations
Prompt injection is the highest-likelihood near-term risk. The facilitator-agnostic design ensures a facilitator compromise cannot force SDK changes. The Soroban fail-closed policy covers contract-level edge cases.
Security honest note

The Soroban contracts handling real user funds do not have a formal audit in the T4 budget. The security model above covers the threat surface with architectural mitigations, but a formal engagement with a recognized Soroban security firm is not funded. The team relies on: internal threat model review, OpenZeppelin audited building blocks, a community audit request submitted separately to the Stellar ecosystem, and a bug bounty at mainnet launch. Conservative spending defaults reduce blast radius if a vulnerability is found post-deployment.

← PreviousSoroban Smart Accounts
Next →Agent Patterns