External Market Resolvers#

SUPERSEDED HISTORICAL DESIGN — excluded from readiness claims.

This page preserves a former adapter/registered-resolver design and must not be used as the current Reclaim implementation contract. The current standalone verifier uses internal secp256k1_recover plus Seesaw V1 tags 0x52–0x56. The former 0x38–0x3F, 0x4A–0x4C, and 0x4F families are permanent tombstones. Current integrations must use SDK Reclaim guidance, the instruction inventory, and executable source. The historical values and diagrams below are retained as provenance only.

Seesaw separates external fact verification from trading and custody. A standalone resolver adapter understands a source such as Kalshi or Polymarket, verifies claims about that source, and calls a small source-agnostic interface in the core program. The core program creates markets, matches orders, accounts for fees, records payouts, handles redemption, and closes accounts without learning the source's API or proof format.

This page explains the actors, keys, signatures, account ownership, creation and resolution flows, creator economics, governance, recovery paths, and trust boundaries behind that design. It also records which prelaunch decisions are approved and which facts still depend on authentic Reclaim evidence.

Why split the system#

External markets combine two very different responsibilities:

1. Determine whether an external statement is authentic.
2. Safely custody collateral and settle positions from that statement.

Putting both responsibilities in the core would make every new data source a core upgrade. It would also mix API parsing, witness rotation, and proof-format changes into the same program that owns markets and vaults. Instead, Seesaw uses a resolver boundary:

Adding another source should require a new or extended adapter plus a resolver registry entry, not a change to the core trading engine. Adding another outcome shape remains separate core engine work. Source and shape are deliberately orthogonal.

Roles and identities#

Several addresses participate in the lifecycle. They are not interchangeable.

The core market stores two different identities:

market.creator            = creator_payer
market.resolver_authority = adapter resolver-authority PDA

The creator is the immutable economic beneficiary. The resolver is the immutable external-lifecycle authority. Changing the payer or selecting another creator cannot create a second canonical mirror because external market identity continues to derive from the resolver and canonical external-reference hash.

Three different kinds of signature#

The word "signature" refers to three independent mechanisms in this system.

Solana transaction signature#

A wallet signs an outer Solana transaction. In the canonical creation flow, creator_payer is both the only wallet signer and the transaction fee payer. Every preparation transaction may therefore require one wallet signature, even when the full preparation workflow spans several transactions.

A separately sponsored fee payer would add another transaction signature. The program cannot and need not enforce who paid the network fee; official builders make creator_payer the fee payer to preserve the single-signature flow.

Reclaim witness signatures#

Witnesses produce Ethereum-compatible secp256k1 signatures over a canonical claim. Those signatures are instruction data. They increase transaction bytes and verification compute, but they are not Solana transaction signers.

PDA signature#

The adapter derives a resolver-authority PDA and uses invoke_signed when it calls the core. Solana marks the PDA as a signer for that CPI. No private key, wallet prompt, or additional transaction signature exists for a PDA.

A creation transaction can therefore contain one wallet signature, three embedded witness signatures, and one runtime PDA signature while still asking the user for only one Solana wallet approval.

Ownership boundary#

Account ownership follows responsibility:

The adapter never owns the core market vault. The core never parses Reclaim JSON or stores witness private material.

Market creation, end to end#

Creating a large external market is a proof-gated, resumable workflow. The individual transactions remain simple enough for current Solana limits while the receipt makes interrupted preparation recoverable.

1. Obtain a definition proof#

The creator or mirror service requests a claim about a canonical external market. A definition claim may bind the platform, canonical reference, question, open status, closing information, outcome kind, and any immutable shape semantics required by the market.

At least three configured witnesses must sign byte-identical claim data. The adapter does not combine signatures from different claims even when each claim looks individually plausible.

2. Verify the proof in the adapter#

The adapter reconstructs the expected provider, parameters, and context from a governed template and typed instruction fields. It does not trust arbitrary caller-supplied JSON or an unverified identifier.

Verification includes:

• canonical provider, parameters, context, and identifier derivation;
• the authentic Ethereum signed-message preimage and digest;
• signature parsing, recovery IDs, canonical low-s rules, and recovered Ethereum addresses;
• a threshold of distinct current-epoch witnesses, or a permitted previous epoch during its bounded overlap;
• checked freshness and future-skew limits;
• action, adapter program, core program, platform, canonical reference, market, question, kind, leg count, epoch, and semantic-fact bindings.

Authentic Task 5B evidence must freeze the byte grammar before this contract is treated as production-compatible. A newline, JSON escape, casing rule, timestamp unit, or hexadecimal prefix can change the signed message.

3. Begin a proof-gated preallocation#

After definition verification, the adapter's separate BeginMirrorPreallocation instruction CPIs core BeginExternalMarketPreallocation (0x4F). The adapter resolver-authority PDA and creator_payer are both observed as signers by core, but only the creator supplies a wallet signature.

Core creates a PreallocationReceipt binding at least:

• the canonical market and resolver;
• the immutable creator_payer;
• the canonical external-reference hash;
• expected orderbook capacity and trader-ledger target;
• creation and reclaim timing;
• active, consumed, or reclaimed status.

The frozen receipt is exactly 384 bytes (EXTPREAL, version 1) at ["seesaw","external_preallocation",market]. It commits every field of the 206-byte open payload: kind, legs, platform/template, reference hash and bytes/length, question hash, and close time. It also commits market, resolver, creator, capacity 512, seats 1,025, created_at, and checked permissionless_reclaim_at = created_at + 86,400.

Requiring adapter authorization at this boundary prevents a wallet from cheaply reserving a unique external reference without first presenting a valid definition proof.

4. Grow large accounts#

Deep orderbooks and trader ledgers can exceed the amount safely grown in one instruction. Receipt-aware ensure instructions allow the creator to prepare canonical, zeroed accounts over multiple transactions.

Every growth step verifies that:

• the receipt is the canonical receipt for the market;
• its creator equals the signing payer;
• its resolver and target sizes match;
• the child account is the canonical PDA;
• existing bytes remain wholly zero;
• growth is monotonic and within the selected supported tier.

An official builder may use a same-transaction preparation fast path only when the complete measured transaction fits. Correctness cannot depend on pending larger-transaction proposals.

5. Open the market#

The adapter's CreateMirror calls the revised core OpenExternalMarket instruction. Core observes two distinct roles:

• resolver-authority PDA: signer and lifecycle authorization;
• creator_payer: signer, writable payer, and economic identity.

The core uses creator_payer to fund final market, metadata, vault, mint, and escrow creation. It stores that address as market.creator while preserving the adapter PDA as market.resolver_authority.

Successful creation consumes the receipt only after all validation and account initialization succeed. A failed instruction rolls back every state change from that transaction.

Reclaiming an interrupted preparation#

Transactions that committed before a later failure cannot be retroactively rolled back. Instead, core provides an atomic reclaim operation for a market that was never initialized.

Reclaim requires:

• a canonical active receipt;
• the receipt's creator as signer, or any signer at/after the fixed 86,400-second boundary; destination always remains the recorded creator;
• a vacant, never-initialized market account;
• canonical core-owned orderbook and ledger PDAs;
• receipt-approved sizes;
• wholly zero prepared child data within the approved targets;
• no live market or metadata discriminator.

Core then zeroes and closes the prepared children and receipt atomically. Every lamport goes to the receipt's immutable creator. The caller cannot redirect the recipient, and adapter governance cannot seize the refund.

Open and reclaim both write-lock the receipt and prepared accounts. Solana's account locking serializes the race: either creation consumes the receipt or reclaim closes it, never both.

Creator economics#

The creator pays the material SOL cost of preparing the orderbook and trader ledger. The design therefore assigns both creator fees and recoverable rent to that same immutable address.

Creator fees#

Creator fees are settlement tokens accumulated from trading. Trading instructions do not accept an arbitrary creator-fee destination. Resolution or the permissionless claim path may transfer accrued creator fees only to a token account whose mint matches the market settlement mint and whose authority is market.creator.

This keeps a client-controlled fee recipient out of trading transactions while still rewarding the party that funded the market.

Rent recovery#

After the terminal delay and liability gates pass, CloseMarket returns all recoverable account lamports to market.creator. The implemented external close path authenticates and closes:

• MarketAccount;
• MarketMeta;
• deep orderbook;
• trader ledger;
• settlement vault;
• YES escrow;
• NO escrow.

Classic Tokenkeg YES and NO mints cannot be closed. Their two rent deposits are the intentionally disclosed residual creation cost. External markets remain on Tokenkeg rather than introducing a separate Token-2022 lifecycle and extension surface. Documentation and product quotes must say all recoverable rent, not literally all creation rent.

Residual settlement-token dust or unsolicited vault donations follow the existing authenticated creator sweep. A donor cannot use a direct token transfer to change protocol liabilities or the creator identity.

Trading remains inside core#

After creation, ordinary trading does not call the resolver adapter:

creator creates market
traders mint, place, match, cancel, and withdraw in core
adapter returns only for authenticated halt or resolution

An unavailable proof service therefore does not prevent ordinary cancellation or withdrawal. Once a terminal result is recorded, redemption and closure are also core operations.

The core continues to fail closed on unknown market kinds. Binary and scalar K2 markets use the complementary order book; a future categorical kind must use its separately reviewed engine and cannot fall through into binary logic.

Normal halt and resolution#

A keeper watches open external markets and gathers proofs when their source status changes. The keeper is untrusted: it chooses when to submit a claim but cannot manufacture the required witness threshold or redirect a correctly bound claim.

Halt#

When a source leaves its permitted open state before finality, the keeper submits a leave-open proof. The adapter verifies it and CPIs core HaltMarket. Halting blocks new placement and matching but preserves cancellation, withdrawal, later resolution, redemption, and recovery.

Resolution#

When the source finalizes, the keeper submits a final-outcome or typed scalar observation proof. The adapter verifies it and directly CPIs core SubmitResolution. Core checks the market's committed resolver, validates the payout shape, and records the result exactly once with proof provenance and the actual nonzero template version.

Canonical K2 examples are:

For scalar markets, core stores the validated complementary vector. It must not reinterpret a graded result as legacy 50/50 merely because the lifecycle outcome byte uses the existing terminal bridge.

Direct CPI and transaction capabilities#

Direct proof verification followed by core CPI is the selected baseline. It keeps proof verification and the fund-moving outcome write atomic and avoids a verified-claim scratch account, second transaction, expiry, rent, and replay lifecycle.

Production activation is conditional on authentic Task 5B vectors fitting the current cluster envelope:

• serialized transaction no larger than 1,232 bytes;
• compute no larger than the current 1.4M-CU transaction ceiling;
• account set within runtime lock limits.

The fixture-only two-program measurement showed provisional headroom but did not freeze authentic Reclaim bytes or the production adapter ABI.

Future larger v1 transactions are an off-chain capability, not an on-chain market feature. The adapter instruction and proof contract remain unchanged. Official builders may select a larger envelope only after Solana publishes and activates an official feature identifier and the connected SDK/RPC support it. The proposed increase in total block compute does not increase a single transaction's compute ceiling.

If authentic direct CPI does not fit current limits, the release fails closed and returns to an explicit scratch-PDA-versus-wait decision. It must not depend silently on an unactivated network proposal.

Governance exists to maintain trust roots#

External trust inputs cannot all remain immutable for the life of the adapter: witnesses rotate, keys can be compromised, APIs change, and proof templates may need replacement. Adapter governance manages those inputs through explicit, timelocked proposal accounts.

Governance may be authorized to:

• rotate the witness set and epoch;
• append immutable template versions;
• enable or disable templates;
• pause new adapter activity;
• rotate governance;
• propose a halted-market administrative resolution when authentic proof production is permanently unavailable.

Governance does not sign routine creation, proof resolution, halt, trade, redeem, or close instructions. Under the creator-funded design it does not receive creator fees or market rent.

Proposal lifecycle#

A governance proposal commits to an action tag, nonce, payload length, payload hash, proposer, creation time, execution eligibility, and expiration. Execution must revalidate the exact payload and timing, and a proposal becomes consumed after one successful execution. Unauthorized, early, expired, cancelled, altered, or replayed proposals fail without partial state changes.

Initial governance bootstrap#

An uninitialized configuration cannot safely accept the first arbitrary signer. The initial-governance mechanism must prevent initialization front-running. The recommended design compiles an expected cold multisig public address into the release build and requires that address to sign Initialize; subsequent rotation uses the governed on-chain path.

The production bootstrap choice is still awaiting its Phase C freeze. A verified program-upgrade-authority bootstrap remains the principal alternative. No secret key is ever compiled into the program.

Witness rotation#

The witness registry holds current and previous sets. A rotation atomically moves current to previous, installs a new current set, increments the epoch, and sets a bounded previous-epoch validity deadline.

During overlap, claims may satisfy the complete threshold and membership rules for either epoch. Witnesses from different epochs cannot be mixed into one threshold. After overlap expiry, the previous set fails closed.

The exact timestamp unit, claim epoch interpretation, overlap period, freshness, and future-skew values remain authentic-vector and policy freezes.

Template governance#

Templates define the exact external fact witnesses attest. The adapter reconstructs parameters from typed inputs and governed immutable renderer bytes; it never treats arbitrary caller JSON as the canonical request.

Templates are tuple-keyed by platform, claim kind, and version. Versions begin at one and are append-only. Governance can add a new version or change its enabled status but cannot rewrite historical renderer bytes. Live markets may resolve through any enabled version compatible with their platform and claim kind, and the actual resolution version is recorded in core provenance.

This permits controlled recovery from an external API change without silently changing what an old template meant.

Administrative resolution#

If an external outcome is publicly known but proof production becomes permanently impossible, governance may propose an exact payout for a halted market. This path is deliberately slower and more visible than proof resolution.

The design requires:

• a halted external market;
• the adapter's configured governance authority;
• an exact market, payout, reason hash, and execution time in the proposal;
• a delay of at least 24 hours;
• an active, unchanged, unconsumed proposal;
• ordinary core resolver authorization through the adapter PDA;
• explicit administrative provenance and template-version sentinel zero.

Governance cannot instantly resolve an actively trading market or label an administrative result as witness proof. The delay gives operators and users a window to inspect, cancel, pause, or escalate a bad proposal.

Resolver registration and wind-down#

Core governance registers the adapter program and resolver-authority PDA with a kind mask. Adapter governance and core registry governance are separate: adapter governance maintains proof policy; core governance decides whether the core continues trusting callbacks from that adapter.

Routine off-boarding proceeds from Active to Open-disabled, drains existing markets, and moves to Revoked only when no live market needs the adapter.

Emergency off-boarding first disables opens, halts affected markets through proof where possible, uses visible timelocked administrative resolution only where necessary, and then revokes the resolver. A delayed core expiry remains the final liveness fallback and records even-split expiry provenance.

Governance and upgrade authority are different#

In-program governance can perform only actions the adapter implements and must obey its delays and checks. A program upgrade authority can replace the code and is therefore more powerful.

Production security depends on protecting both. The recommended operational shape is a cold Squads multisig for adapter governance and upgrade authority during prelaunch, followed by an explicit post-audit decision to retain, timelock, or revoke upgradeability. Repository prose cannot substitute for the external authority and deployment evidence required at release.

Threat boundaries#

Timelocked admin recovery (C6)#

C6_RUNTIME_CERTIFICATE records the implemented proof-independent recovery path. Governance commits an exact public binary outcome after an observation window; any fee-paying signer may execute once the delay has elapsed. The adapter does not decide from a Reclaim proof on this path. It signs the normal core submission only through its already-registered immutable authority PDA.

The action-6 proposal payload is exactly 80 bytes:

market[32] | payout_numerators[8]u16_le[16] | reason_hash[32]

reason_hash must be nonzero. The provisional off-chain convention is SHA-256("seesaw:reclaim-admin-reason:v1\0" || normalized_public_evidence); the program checks neither normalization nor evidence authenticity. Valid payouts are YES [10000,0], NO [0,10000], or VOID [5000,5000], with legs 2–7 zero. ExecuteAdminResolve (0x08) is exactly 41 bytes: tag | nonce:u64_le | expected_proposal_hash[32].

Execution uses exactly nine accounts: writable Config and Proposal; permissionless writable signer Executor; writable stored ProposerRefund; writable core Market and MarketMeta; readonly core ResolverRegistry; readonly adapter Authority PDA; and readonly executable configured core program. Only Executor and authenticated ProposerRefund may alias. Pause does not block this recovery. The inclusive interval is execute_at <= now <= expires_at.

The core CPI is exactly 0x4B | payout[16] | provenance=1 | template_version=0u16_le, with Market writable, MarketMeta writable, ResolverRegistry readonly, and the adapter Authority PDA as the sole inner signer. Active and OpenDisabled registry entries behave identically; Revoked fails before CPI and market-kind masks do not gate recovery. The market must be binary, externally bound to that Authority, unresolved, and halted exactly 1.

Canonical failures remain stable: malformed instruction data is B001 InvalidInstruction; wrong ownership is B002 InvalidAccountOwner; wrong size is B003 InvalidAccountSize; a wrong discriminator is B004 InvalidAccountDiscriminator; a noncanonical PDA is B005 InvalidPda; authorization or governance-succession mismatch is B006 Unauthorized; a substituted program is B007 InvalidProgram; a non-action-6 proposal is B00A InvalidGovernanceAction; early execution is B00C ProposalNotReady; expiry is B00D ProposalExpired; a hash mismatch is B00E ProposalHashMismatch; replay or another finalized proposal is B00F ProposalFinalized; corrupt status, duplicate-authority, nonzero-unused-registry, or halted-value transitions are B023 InvalidTransition; and a returned core CPI failure maps to B024 CoreCpiFailed.

Success emits AdminResolutionProposed tag 10 before GovernanceProposed tag 1, then at execution AdminResolutionExecuted tag 11 before GovernanceExecuted tag 2. Core Market and MarketMeta may change only their frozen resolution allowlist. Creator identity, accumulated creator fees, every other Market/MarketMeta byte, their metadata, and their lamports remain exact. After normalizing the fee payer's exact transaction fee, all other supplied account metadata and balances remain exact except that the actual Proposal lamports move in full, and only, from Proposal to its stored proposer.

This does not distribute creator fees and accepts no creator token destination, mint, vault, treasury, System Program, rent-recipient, or sweep account. C6 therefore certifies structural absence plus creator/fee conservation. Wrong creator token destination/mint, exact creator-fee distribution, and full recoverable-rent return are C7 lifecycle assertions.

The emergency wind-down order is:

open_disabled -> halt -> propose -> minimum 24h delay -> execute -> revoke

This is exploratory feasibility evidence, not launch authorization. C3 proof verification, C4 mirror creation, C5 proof resolution/halt, C7 lifecycle, a production identity, deployment, registration, provider operation, C8 operational handoff, and all external signoffs remain open.

The dual-SBF runtime evidence is produced only by the explicit certificate command with BPF_OUT_DIR set. In ordinary standalone root suites, the two artifact-dependent cases emit C6_RUNTIME_CERTIFICATE_SKIP and return without claiming runtime evidence; the manifest and contract-only cases still execute. When BPF_OUT_DIR is present, missing, substituted, or hash-mismatched files remain hard failures and every dual-SBF assertion runs.

One deliberate evidence deviation is documented: an authentic locked-core semantic error cannot reach public B024 because adapter preflight is a strict superset of core 0x4B semantic rejection conditions. Fabricating one would require substituting the hashed core or exhausting runtime resources. The Task 4 injected-CPI seam certifies returned-error-to-B024 mapping and rollback; the real dual-SBF certificate proves exactly one successful authentic 0x4B.

Approved prelaunch decisions#

• extend core OpenExternalMarket with one creator_payer signer/writable account;
• use that account for final creation funding and immutable creator economics;
• preserve the resolver PDA as the separate lifecycle authority;
• use a proof-gated core PreallocationReceipt with atomic creator-bound reclaim;
• permit an atomic same-transaction preparation fast path only when measured to fit;
• close authenticated MarketMeta and all other recoverable accounts to the creator;
• keep classic Tokenkeg and disclose the two non-closeable mint rents;
• use direct proof-verification CPI only when authentic vectors meet current transaction limits;
• treat future v1 transaction envelopes as an off-chain capability;
• reopen authentic Task 5B under a local-fleet, public-network, sanitized- evidence scope with no deployment, registration, or on-chain transaction.

Frozen by the exploratory C1, C2, and C6 certificates are the adapter layouts, seeds, discriminants, error codes, and event transport for those implemented surfaces. They remain provisional and do not freeze the open phases.

Still requiring evidence or an explicit production freeze:

• authentic Kalshi and Polymarket proof bytes and signature fixtures;
• production adapter program ID and governance identity;
• initial governance bootstrap mechanism and production governance address;
• canonical reference, context, timestamp, freshness, epoch-overlap, and template-renderer rules;
• C3 authentic verification, C4 mirror creation, C5 proof resolution/halt, C7 lifecycle, and C8 operational handoff;
• authentic direct-CPI bytes, compute, and account-lock measurements;
• external platform/legal review, deployed authority evidence, and staging operations.

Evidence required before activation#

Implementation does not make the adapter production-ready by itself. Activation requires, at minimum:

• independently reviewed authentic proof fixtures;
• byte parity across Rust and every supported client;
• adapter and core SBF integration tests;
• current-envelope CU, transaction-byte, and account-lock evidence;
• negative and mutation tests for every binding, signature, epoch, timing, and replay rule;
• creator-fee and full recoverable-rent accounting tests;
• interrupted, partial, replayed, donated, reclaimed, and successfully consumed preallocation tests;
• two-program create, trade, halt, resolve, redeem, and close lifecycles;
• resolver disable and emergency wind-down drills;
• synchronized IDLs, SDKs, indexer, keeper, web, and mobile consumers;
• local and staging gates required by the production-readiness policy;
• recorded program ID, upgrade authority, governance authority, registration, platform review, and legal signoff.

Related material#

• Extensible market sources and types roadmap
• Phase C Reclaim adapter plan
• Phase 0 evidence record
• Oracle and resolver specification
• Account specification
• Instruction specification
• Protocol security invariants
• Documentation authority hierarchy