Protocol Specification

0. End-to-End Example

A complete transaction lifecycle showing all artifacts and their hashes.

{
  "canonical_version": 1,
  "contract_hash": "a1b2c3d4e5f6...",
  "workflow_hash": "f6e5d4c3b2a1...",
  "workflow_version": 1,
  "settlement_mode": "deterministic",
  "settlement_on_pass": "release",
  "settlement_on_fail": "refund",
  "settlement_on_error": "approval_required",
  "amount_cents": 10000,
  "currency": "usd",
  "buyer_agent_id": "agent_buyer_123",
  "seller_agent_id": "agent_seller_456"
}

verified_contract_hash: "sha256:7f8e9d0c1b2a3..."

{
  "api_endpoint": "https://api.example.com/v1/data",
  "documentation_url": "https://docs.example.com",
  "test_credentials": { "api_key": "test_..." }
}

delivery_hash: "sha256:3e4f5a6b7c8d9..."

{
  "canonical_version": 1,
  "contract_hash": "sha256:7f8e9d0c1b2a3...",
  "workflow_hash": "f6e5d4c3b2a1...",
  "run_id": "run_abc123",
  "outcome": "PASSED",
  "outcome_reason": "All checks passed",
  "step_results": [
    { "step_id": "check_api", "status": "completed", "output_hash": "..." },
    { "step_id": "validate_schema", "status": "completed", "output_hash": "..." }
  ],
  "final_context_hash": "sha256:9a8b7c6d5e4f..."
}

verification_hash: "sha256:2d3e4f5a6b7c8..."

{
  "canonical_version": 1,
  "contract_hash": "sha256:7f8e9d0c1b2a3...",
  "verification_hash": "sha256:2d3e4f5a6b7c8...",
  "settlement_type": "full_release",
  "release_amount_cents": 10000,
  "refund_amount_cents": 0,
  "settled_at": "2026-03-05T12:00:00Z",
  "released_to_agent_id": "agent_seller_456",
  "settlement_method": "deterministic"
}

settlement_hash: "sha256:1a2b3c4d5e6f7..."

1. Verified Contract Schema

A verified contract is the root object of any FinalTX transaction. Its canonical hash captures the complete agreement: terms, verification workflow, and settlement rules.

Canonical Fields (v1)

interface VerifiedContractFields {
  // Version (always first)
  canonical_version: 1;
  
  // Contract terms (SHA-256 hash of normalized terms)
  contract_hash: string;
  
  // Verification workflow (SHA-256 hash + version)
  workflow_hash: string | null;
  workflow_version: number | null;
  
  // Settlement rules
  settlement_mode: 'deterministic' | 'approval_required' | 'hybrid' | 'mediation';
  settlement_on_pass: 'release' | 'approval_required' | 'partial_release';
  settlement_on_fail: 'refund' | 'approval_required' | 'mediation' | 'partial_refund';
  settlement_on_error: 'approval_required' | 'mediation' | 'refund';
  settlement_partial_release_percent: number | null;
  settlement_partial_refund_percent: number | null;
  
  // Payment
  amount_cents: number;
  currency: string; // lowercase, trimmed
  
  // Parties
  buyer_agent_id: string | null;
  seller_agent_id: string | null;
  mediator_agent_id: string | null;
}

Canonicalization Rules

• 1.Fields are sorted alphabetically before hashing
• 2.Strings are lowercased and trimmed
• 3.Null/undefined values are normalized to null
• 4.Numbers are stored as integers (no floating point)
• 5.JSON serialization uses no whitespace

2. Verification Report Schema

The verification report is the output of running the verification workflow. It provides deterministic proof of the verification outcome.

interface VerificationReport {
  canonical_version: 1;
  
  // Links to contract
  contract_hash: string;
  workflow_hash: string;
  
  // Execution metadata
  run_id: string;
  started_at: string; // ISO 8601
  completed_at: string; // ISO 8601
  duration_ms: number;
  
  // Outcome
  outcome: 'PASSED' | 'FAILED' | 'INDETERMINATE';
  outcome_reason: string;
  
  // Step results (deterministic order by step_id)
  step_results: Array<{
    step_id: string;
    status: 'completed' | 'failed' | 'skipped';
    output_hash: string; // SHA-256 of step output
  }>;
  
  // Final context hash (for replay verification)
  final_context_hash: string;
}

Replay Guarantee

A workflow run can be replayed with identical inputs. If the workflow definition is deterministic, the replay MUST produce the same final_context_hash.

3. Settlement Receipt Schema

The settlement receipt is the final artifact proving value transfer.

interface SettlementReceipt {
  canonical_version: 1;
  
  // Links to prior artifacts
  contract_hash: string;
  verification_hash: string;
  
  // Settlement details
  settlement_type: 'full_release' | 'full_refund' | 'partial';
  release_amount_cents: number;
  refund_amount_cents: number;
  
  // Timestamps
  settled_at: string; // ISO 8601
  dispute_window_ends_at: string | null; // ISO 8601
  
  // Parties
  released_to_agent_id: string | null;
  refunded_to_agent_id: string | null;
  
  // Method
  settlement_method: 'deterministic' | 'approval' | 'mediation';
  approved_by_agent_id: string | null;
  mediated_by_agent_id: string | null;
}

4. Hashing Algorithm

All canonical hashes use SHA-256 with deterministic JSON serialization.

function hashCanonical(obj: Record<string, unknown>): string {
  // 1. Sort keys alphabetically
  const sortedKeys = Object.keys(obj).sort();
  
  // 2. Build deterministic object
  const deterministic: Record<string, unknown> = {};
  for (const key of sortedKeys) {
    deterministic[key] = obj[key];
  }
  
  // 3. Serialize to JSON (no whitespace)
  const json = JSON.stringify(deterministic);
  
  // 4. Hash with SHA-256
  return crypto
    .createHash('sha256')
    .update(json, 'utf8')
    .digest('hex');
}

5. Trust Artifact Chain

The trust chain links all artifacts from transaction definition to final settlement.

6. Replay Modes

Workflow runs can be replayed for dispute resolution. Two modes are supported:

7. On-Chain Settlement

Canonical format for signed settlement verdicts used in EVM and Solana smart contract settlement.

Settlement Verdict Schema

interface SignedSettlementVerdict {
  verdict: {
    verdict_id: string;              // "ftx_vrd_01JXXXXX"
    version: string;                 // "1.0"
    contract_id: string;
    decision: "release" | "refund";
    release_amount_wei: string;      // Amount to seller (minus 1% fee on release)
    refund_amount_wei: string;       // Amount to buyer (full amount on refund)
    platform_fee_amount_wei: string; // 1% fee (0 on refund)
    nonce: string;                   // Unique per verdict for replay protection
    issued_at: string;               // ISO 8601
    expires_at: string;              // 7 days from issuance
  };
  verdict_hash_sha256: string;       // SHA-256 of canonical verdict JSON
  chain_family: "evm" | "solana";
  chain_id: string;                  // EVM: "1", "8453"; Solana: "mainnet-beta"
  verifying_contract: string;        // Vault contract address
  signature: string;                 // 65-byte hex (EVM) or 64-byte hex (Solana)
  signer_address: string;            // FinalTX attestor address
  chain_specific_payload: {
    evm_typed_data_digest?: string;  // EIP-712 digest (EVM only)
    solana_message_bytes?: string;   // Ed25519 message (Solana only)
  };
}

Fee Calculation

locked_amount = 1.0 ETH
platform_fee  = locked * 0.01  // 0.01 ETH
release_amt   = locked - fee   // 0.99 ETH

locked_amount = 1.0 ETH
platform_fee  = 0              // No fee on refund
refund_amt    = locked         // 1.0 ETH

Supported Chains

8. Version Compatibility

Rules for schema evolution and backward compatibility.

Breaking Changes (Bump Canonical Version)

• xRemoving or renaming a canonical field
• xChanging the hashing algorithm
• xChanging field normalization rules
• xChanging array sorting order

Non-Breaking Changes (Same Version)

• +Adding a new optional field with default value
• +Adding new enum values (with graceful handling)
• +Adding new step types to workflows

Version Support Policy

When a new canonical version is released, the previous version remains supported for at least 12 months. Existing transactions continue using their original version.