SPECIFICATION 3.2•TRANCHELOCK PROTOCOL ARCHITECTURE•ONCHAIN / OFFCHAIN BOUNDARIES

Protocol Documentation

Technical specification for milestone PDA state machines, isolated test assertion sandboxes, Google Gemini structured criteria reasoning, and Solana Ed25519 instruction introspection.

Architectural Topology

Autonomous coding agents require compute capital and milestone rewards, but sponsors cannot safely disburse complete funding upfront. Traditional crypto escrows rely on human multisig or centralized arbiters, introducing friction and counterparty risk.

TrancheLock introduces programmatic milestone escrows on Solana. Capital is locked upfront in a PDA vault, locking committed escrow capital for the autonomous agent. Capital releases automatically when the agent's work satisfies deterministic private test suites verified in a sandbox, evaluated by Gemini structured criteria reasoning, and attested via an Ed25519 oracle signature verified by Solana instruction introspection.

INTER-LAYER COMMUNICATION PIPELINEONCHAIN / OFFCHAIN SEPARATION

[ONCHAIN]

Sponsor Escrow Deposit

Locks escrow tokens (TLUSD/USDC) in Token Vault PDA. Commits private test suite SHA-256 hashes.

[OFFCHAIN VERIFIER]

Sandbox & Gemini Audit

Pytest executes in an isolated sandbox runner. Gemini evaluates structured Pydantic criteria.

[ONCHAIN RUNTIME]

Ed25519 Introspection

Solana verifies 153-byte payload in ix[n-1]. Tranche tokens disburse to Agent ATA.

Vault PDA State Machine

Each escrow vault is a Program Derived Address (PDA) derived from seeds: [b"tranche_vault", sponsor.key(), token_mint.key()]. Associated token funds reside in a secondary token vault derived from [b"token_vault", vault.key()].

#[account]
pub struct TrancheVault {
    pub sponsor: Pubkey,                      // 32 bytes: Escrow funder authority
    pub agent: Pubkey,                        // 32 bytes: Recipient agent wallet
    pub verifier_oracle: Pubkey,              // 32 bytes: Authorized Ed25519 signer
    pub token_mint: Pubkey,                   // 32 bytes: Allowlisted token mint (TLUSD / USDC)
    pub milestone_spec_hashes: [[u8; 32]; 4], // 128 bytes: Private test suite hashes
    pub total_tranches: u8,                   // 1 byte: Number of tranches (1..=4)
    pub current_tranche: u8,                  // 1 byte: Monotonic sequence counter
    pub tranche_amounts: [u64; 4],            // 32 bytes: Base token units per tranche
    pub tranche_status: [u8; 4],              // 4 bytes: 0=Locked, 1=Released, 2=Refunded
    pub expires_at: i64,                      // 8 bytes: Expiration Unix timestamp
    pub bump: u8,                             // 1 byte: Vault PDA bump
    pub vault_bump: u8,                       // 1 byte: Token vault PDA bump
}

Private Spec Commitments

To prevent test suite gaming, overfitting, or prompt injection, acceptance test suites are kept strictly verifier-side:

Sponsor computes: milestone_spec_hash = SHA-256(private_test_suite) and commits it onchain during vault initialization.
Agent only receives public interface definitions and guidance criteria, never the private acceptance tests.
Upon submission, the verifier validates the private test suite on disk matches the committed onchain spec hash before starting the sandbox.

Dual-Layer Verifier Architecture

TrancheLock combines deterministic software assertion testing with Google Gemini structured criteria reasoning:

Layer 1: Deterministic Sandbox

Executes pytest inside an isolated subprocess runner with stripped environment variables and process timeout. Extracts exit code, duration, passed/failed test names, and stderr traces.

Layer 2: Gemini Structured Reasoning

Evaluates observable deterministic evidence against sponsor acceptance criteria using structured Pydantic schemas. If tests fail, returns structured diagnostics to agent.

153-Byte Canonical Buffer Scheme

When 100% of milestone criteria are verified, the verifier oracle signs an exact 153-byte payload tightly binding release parameters:

[00..32]  : vault_pda (32 bytes Pubkey)
[32]      : milestone_idx (1 byte u8)
[33..65]  : agent_wallet (32 bytes Pubkey)
[65..97]  : submission_hash (32 bytes SHA-256 of source snapshot)
[97..129] : milestone_spec_hash (32 bytes SHA-256 of test suite)
[129..137]: tranche_amount (8 bytes little-endian u64)
[137..145]: expires_at (8 bytes little-endian i64)
[145..153]: nonce (8 bytes little-endian u64)

Instruction Introspection (Sysvar)

Solana transactions executing release_tranche must contain an Ed25519SigVerify precompile instruction immediately preceding the release instruction:

load_current_index_checked(&instructions_sysvar)? confirms current instruction position.
Verifies instruction current_index - 1 is native ed25519_program::ID.
Verifies data header specifies num_signatures == 1.
Matches oracle public key bytes against vault.verifier_oracle.
Matches message bytes against reconstructed canonical 153-byte payload.

Timelock Clawback & Expiration

If an agent abandons work or becomes unresponsive, sponsors are protected by the timelock clawback:

Released Funds Inviolable: Any capital already disbursed to the agent cannot be clawed back under any circumstances.
Refund of Unreleased Capital: The sponsor can call clawback() strictly after clock.unix_timestamp > vault.expires_at.
Completed Vault Protection: Clawback fails with NoFundsToClawback if all tranches have been settled.

Token Allowlisting

To ensure deterministic escrow settlement, TrancheLock operates with verified 6-decimal token mints on Solana Devnet:

DEVNET TLUSD (ACTIVE TEST MINT):Solana Explorer →

7oKiSro2j98G3NigDYzb6EfisnnAxhg3DTTio6yf6xjW

Decimals: 6 • Primary Devnet Escrow Token

CIRCLE DEVNET USDC:Solana Explorer →

4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU

Decimals: 6 • Supported Devnet Mint