Escrow Design

Specify escrow before writing a program

A future Solana escrow program could hold customer-funded SOL until a bounded service is accepted or refunded. This is a new implementation, not a capability of the recorded transfer-only candidate. Solana Pay describes payment request conventions; it is not automatically an escrow, recurring stream, dispute system or off-ramp. Pick the primitive that matches the contract rather than borrowing a familiar product name.

Define accounts and authority

Write the account model before the UI. A job account might identify customer, worker, evaluator, price in lamports, deadline, status, input/output digests and settlement constraints. Program-owned accounts and PDA derivation need review for ownership, signer requirements and uniqueness. Amount arithmetic must use checked operations and fit the chosen integer type. Rent and transaction fees need explicit accounting alongside the service price.

Define who can fund, assign, submit a result, accept, reject, cancel, refund and close each account. A malicious caller should not settle another user's job or redirect its payout. Every instruction needs state and authority checks. Upgrade authority is another trust boundary: if an operator can change the program, users should know that before funds are escrowed. Calling the system decentralized does not remove this authority.

Make deadlines actionable

A deadline stored on-chain does not execute a refund by itself. Someone must submit an instruction, potentially through a crank or user action. Specify which state allows refund, which time source is checked and what happens when acceptance and refund transactions race. Design idempotent outcomes and reject invalid repeated transitions. Do not promise funds return automatically after five minutes without an actual execution mechanism.

Disputes need a policy that addresses unavailable evaluators, ambiguous service results and partial delivery. A program can enforce an authority's signed decision, but it cannot independently measure every off-chain storage or AI task. Start with a small, disclosed evaluator model if that is the practical pilot, then improve it based on observed failures. Concealing the verifier's role creates a stronger-sounding but less trustworthy product.

Test adversarial transitions

Test wrong signer, wrong account owner, wrong PDA, overflow, duplicate settle, settle before acceptance, refund before deadline and conflicting state changes. Test balances before and after instructions and account closing behavior. A happy-path devnet transfer is not a smart-contract audit. Preserve program source, toolchain, deployment address, upgrade authority and tests for the actual deployed revision.

Connect the Android review boundary

When the app later interacts with escrow instructions, its transaction decoder must support and display those instructions accurately. The current System Program transfer review should refuse unknown program content. Do not add an escrow program and then bypass exact-message review because the instruction is more complex. Every new supported action needs readable account roles, amount, authority and failure semantics.

The launch gate should include program review, devnet end-to-end funding and refund, wallet return checks, durable mobile state and settlement observation. Mainnet use comes later with a separate decision and qualified artifact. Until then, diagrams and tutorials should call this an escrow specification or prototype, not a deployed reward system.

---

Wiki home · Qualification updates · Sources and credits