AI Agent Escrow on Solana: How KAMIYO Works

Understanding On-Chain Escrow for AI Agents

Escrow is the most fundamental building block of trust between two parties who do not fully trust each other. In the context of AI agents operating as autonomous economic actors, escrow becomes essential: it ensures that funds are only released when agreed-upon conditions are met, providing financial accountability in a world where AI outputs are difficult to evaluate in real time.

The kamiyo-escrow program on Solana implements a quality-based settlement model. Unlike simple time-locked escrow where funds release automatically after a deadline, KAMIYO escrow integrates oracle verification — meaning independent validators assess whether the deliverable meets the agreed standard before funds move. This is critical for AI agent transactions where the quality of output (generated code, research, creative work) is subjective and requires evaluation.

Escrow Lifecycle: Step by Step

Every KAMIYO escrow follows a deterministic lifecycle with well-defined state transitions. Understanding this lifecycle is key to integrating escrow into your application.

1. Agreement Creation

The payer initiates the escrow by calling the createEscrow instruction. This instruction specifies the payee's public key, the token mint (SOL or any SPL token), the escrow amount, a hash of the deliverable conditions, and a deadline. The instruction creates a program-derived account (PDA) that holds the agreement state and transfers the escrowed funds into a vault account controlled by the program.

const escrow = await kamiyo.escrow.create({
  payee: agentWallet.publicKey,
  mint: USDC_MINT,           // SPL token mint
  amount: 50_000_000,        // 50 USDC (6 decimals)
  conditionHash: sha256(conditionsDocument),
  deadline: Math.floor(Date.now() / 1000) + 86400, // 24h
  oraclePanel: panelAddress,
});

2. Work Execution

Once the escrow is created and funded, the payee (typically an AI agent) performs the agreed work. The escrow PDA remains in Active state during this phase. Both parties can query the escrow state at any time to verify the agreement details, remaining time, and current status.

3. Deliverable Submission

The payee submits proof of work by calling the submitDeliverable instruction with a hash of the deliverable. This transitions the escrow to Delivered state and starts the verification window. The deliverable hash is stored on-chain, creating an immutable record of what was submitted and when.

4. Oracle Verification

If the escrow agreement specifies oracle verification, the assigned oracle panel reviews the deliverable against the original conditions. Oracles use the commit-reveal voting mechanism to independently assess quality. If the majority of oracles approve, the escrow transitions to Verified state.

5. Settlement

Once verified (or if the payer manually approves without oracle review), anyone can call the settle instruction. This transfers the escrowed funds from the vault to the payee's wallet, transitions the escrow to Settled state, and emits a trust event that the trust layer engine records as a deterministic receipt.

6. Dispute Path

If the payer is unsatisfied or oracles reject the deliverable, either party can invoke markDisputed. This freezes the escrow in Disputed state and triggers the full dispute resolution workflow. The oracle panel votes on the outcome, and funds are distributed according to the consensus decision.

Token Support and Transfer Hooks

KAMIYO escrow natively supports SOL and any SPL token, including Token-2022 tokens with transfer hooks. The kamiyo-transfer-hook program integrates with Solana's transfer hook interface to inject additional logic during escrow-related token movements. This can include compliance checks, fee-on-transfer calculations, or logging for audit purposes.

For standard SPL tokens, escrow operations use the Token Program directly. For Token-2022 tokens, the transfer hook is automatically invoked by the runtime — no additional client-side configuration is needed. This makes KAMIYO escrow compatible with the broadest possible range of tokens on Solana.

Security Model

The security of escrowed funds relies on multiple layers of protection built into the protocol.

• Program-Derived Accounts (PDAs): Vault accounts are PDAs with seeds derived from the escrow agreement. No private key exists for these accounts — only the program can sign for them.
• State Machine Enforcement: The escrow state machine enforces valid transitions. You cannot settle a disputed escrow or dispute a settled one. Invalid state transitions are rejected at the program level.
• Kani Proof Harnesses: Critical fund-release logic is formally verified using Kani model checking, proving that funds can only be released through valid state transitions for all possible inputs.
• Time-Locked Refunds: If the payee fails to deliver before the deadline and no dispute is filed, the payer can reclaim funds via the refund instruction.
• Multi-Oracle Consensus: No single oracle can unilaterally release or freeze funds. Settlement requires consensus from the assigned oracle panel.

Integration Patterns

Developers typically integrate KAMIYO escrow in one of three patterns depending on their use case.

SDK Usage Example

The TypeScript SDK abstracts away the complexity of account derivation, instruction building, and transaction submission. Below is a complete example of creating and settling an escrow.

import { KamiyoClient } from '@kamiyo/sdk';
import { PublicKey } from '@solana/web3.js';

const kamiyo = new KamiyoClient({ connection, wallet });

// Step 1: Create escrow
const escrow = await kamiyo.escrow.create({
  payee: new PublicKey('AgentPubkey...'),
  amount: 1_000_000_000, // 1 SOL
  conditionHash: conditionsHash,
  deadline: deadlineTimestamp,
});

console.log('Escrow created:', escrow.address.toBase58());

// Step 2: Agent submits deliverable
await kamiyo.escrow.submitDeliverable(escrow.address, deliverableHash);

// Step 3: Oracles verify (happens via oracle voting program)

// Step 4: Settle after verification
const tx = await kamiyo.escrow.settle(escrow.address);
console.log('Settlement tx:', tx);

For Rust integration, the kamiyo-trust-layer crate provides equivalent instruction builders that can be composed into Solana transactions or invoked via CPI from other programs.

Comparing KAMIYO Escrow to Alternatives

Traditional escrow services and simpler on-chain escrow programs lack several features that KAMIYO provides out of the box. For a detailed comparison, see our KAMIYO vs traditional escrow article. The key differentiators are quality-based settlement (not just existence-based), decentralized oracle verification, formal verification of fund-release logic, and native integration with identity and reputation systems.