Xochi Technical Appendix

Appendix to the Xochi Whitepaper. API specs, fee tables, solver requirements, and glossary.

Table of Contents

• A. Intent API Endpoints
• B. EIP-712 Intent Signatures
• C. Complete Fee Matrix
• D. Solver Specifications
• E. Xochi's ZK Compliance Oracle Proof Types
• F. Trust Score Providers
• G. Glossary
• H. Widget SDK (Upcoming)
• I. Formal Derivations
• J. Execution Specifications

A. Intent API Endpoints

Auth roles (defined in the glossary): Member (passkey JWT), Guest (x402 micropayment), or both. JWT and x402 are alternatives, not additive: send Authorization for Member, send X-PAYMENT for Guest. Routes marked "Member or Guest" accept both. Routes marked "Member" require JWT; the Mandate path (Member-signed envelope authorizing an Agent, presented as X-Xochi-Delegation) is live. Public routes need no auth.

For machine-readable specs see /openapi.yaml (opens in new tab) (V1 surface, 10 endpoints) and /.well-known/agents.json (opens in new tab) (full x402 catalog with prices).

Market Orders

POST /api/intent/quote          # Get solver quotes              [Member or Guest, x402: $0.0001]
POST /api/intent/execute        # Execute signed intent           [Member or Guest, x402: $0.01]
GET  /api/intent/:id            # Get intent details              [Member or Guest, x402: $0.0001]
GET  /api/intent/:id/status     # Get execution status            [Member or Guest, x402: $0.0001]
GET  /api/intent/history        # User trade history              [Member or Guest, x402: $0.0001]

Limit Orders

POST /api/intent/limit-quote    # Quote for limit order           [Member or Guest, x402: $0.0001]
POST /api/intent/limit-submit   # Submit limit order              [Member or Guest, x402: $0.01]
GET  /api/intent/limit-orders   # List active limits              [Member or Guest, x402: $0.0001]
DELETE /api/intent/limit/:id    # Cancel limit order              [Member]

Trust & Privacy

POST /api/attestation           # Submit attestation              [Member]
GET  /api/attestation           # Get attestations                [Member]
POST /api/tier-proof/verify     # Verify tier proof               [Member]
GET  /api/tier-proof            # Get tier proofs                 [Member]

Settlements

POST /api/settlement/claim      # Claim shielded settlement       [Member or Guest, x402: $0.005]
GET  /api/settlement            # Query settlements for a wallet  [Member or Guest, x402: $0.0001]

Solver Revenue

POST /api/solver/deposit        # Batch settlement from Riddler   [Member]
GET  /api/solver/stats          # Revenue tracking                [public]
GET  /api/solver/history        # Recent solver fills             [public]

Stealth Addresses (ERC-5564/6538)

L1 privacy via one-time receiving addresses. Open to every wallet, no trust-score gate (privacy is free by default).

GET  /api/stealth/meta-address  # Lookup stealth meta-address     [Member or Guest, x402: $0.0001]
POST /api/stealth/register      # Register stealth meta-address   [Member]
GET  /api/stealth/announcements # Query announcements by view tag [Member]
POST /api/stealth/announcements # Index new announcement          [Member]
POST /api/stealth/claim         # Gasless stealth claim           [Member]

Prices

GET  /api/prices                # Token prices, USD, 60s edge cache  [public]

Capabilities

GET  /api/capabilities          # Solver capability matrix (chains/tokens/bounds)  [public]

Real-time

WS   /ws                        # Intent status updates           [Member]

Riddler Solver API (/xochi/*)

Xochi's own API surface on the Riddler solver. Own schema, own fee tiers, own settlement targets.

POST /xochi/quote              # Quote with tier-based fees + stealth info
POST /xochi/execute            # Execute signed intent (EIP-712)
POST /xochi/claim              # Gasless stealth claim (ERC-4337)
GET  /xochi/status/:intent_id  # Intent status with stealth/counterfactual fields
GET  /xochi/chains             # Supported chains
GET  /xochi/routes             # Supported routes
GET  /xochi/health             # Health check

Stealth claim flow: When settlement type is "stealth", tokens land at a counterfactual ERC-4337 SimpleAccount. The recipient calls /xochi/claim with their stealth keys and a destination address (Safe, EOA). The server derives the stealth signing key, builds a Pimlico-sponsored UserOperation, and submits it to the bundler. Account deployment + token transfer happen atomically in one gasless step.

Quote response includes claimInfo for stealth settlements:

{
  "claimInfo": {
    "factoryAddress": "0x91E60e0613f8E48b12EFC11BcAfB4dDA7763EC23",
    "salt": 0
  }
}

Announcement metadata (109 bytes, ERC-5564 extension):

view_tag(1) || token(20) || selector(4) || amount(32) || factory(20) || salt(32)

B. EIP-712 Intent Signatures

Xochi Frontend Intent (existing)

const intentTypes = {
  Intent: [
    { name: "sellToken", type: "address" },
    { name: "buyToken", type: "address" },
    { name: "sellAmount", type: "uint256" },
    { name: "minBuyAmount", type: "uint256" },
    { name: "deadline", type: "uint256" },
    { name: "privacyTier", type: "uint8" },
    { name: "nonce", type: "uint256" },
  ],
};

Riddler XochiIntent (solver-side)

Signed by the user's wallet when executing via the /xochi/execute endpoint. The wallet signs the solver-served typed data verbatim; the struct is solver-versioned and VM-agnostic (a leg can be a base58 Tron address, so token/recipient fields are strings). Current version is v3. Domain: name "Xochi", a deploy-scoped version (e.g. "3-prod"), chainId = origin chain, and salt = keccak256(version); no verifyingContract.

const xochiIntentTypes = {
  XochiIntent: [
    { name: "intentId", type: "string" },
    { name: "quoteId", type: "string" },
    { name: "wallet", type: "address" }, // signer is always an EVM key
    { name: "recipient", type: "string" }, // VM-agnostic payout address
    { name: "fromChainId", type: "uint256" },
    { name: "toChainId", type: "uint256" },
    { name: "fromToken", type: "string" }, // string, not address (base58 TRC-20)
    { name: "toToken", type: "string" },
    { name: "fromAmount", type: "uint256" },
    { name: "toAmount", type: "uint256" },
    { name: "settlementPreference", type: "string" },
    { name: "deadline", type: "uint256" },
  ],
};

C. Complete Fee Matrix

Trading Fees by Tier

Fees are shown stablecoin / volatile (ETH/WETH). Each total decomposes into a never-discounted solver cost layer plus a tier-discounted venue + routing layer. The MEV rebate is retired; the solver shares 15% of price improvement instead (see Settlement Types).

Privacy Level Fees

The deeper privacy levels (Private, Sovereign) are gated by trust score; L1 stealth is open to all. The effective fee equals your trust tier's base fee. Higher trust unlocks deeper privacy at a lower rate.

Open and Public are flat-rate tiers: Open pays users -0.02% plus analytics (loss leader), Public is free. For Standard through Sovereign, the fee is determined by trust tier (see Trading Fees table above). Users with trust scores above the minimum for their chosen privacy level pay their trust tier rate.

Settlement Types

FX Fees

Other Fees

Partner Revenue Share

D. Solver Specifications

Standard Solver Requirements

FX Solver Requirements

Slashing Events

Solver Onboarding

1. Stake collateral (amount TBD)
2. Submit compliance attestation (jurisdiction, license type)
3. Pass technical integration test
4. 7-day probation period (limited volume)
5. Full activation

Riddler: Current Performance

Riddler (protocol solver) is the primary active solver. External solver onboarding is open and permissionless. Contact team for integration support.

E. Xochi's ZK Compliance Oracle Proof Types

Signed variants (0x07, 0x08) bind a secp256k1 ECDSA signature in-circuit over the screening payload, plus chain_id and oracle_address (audit F-6) to prevent cross-chain or cross-deployment replay. The multi-signed variant (0x09) aggregates M independent signers under AND-semantics with a runtime threshold_m; jurisdictions configure a minimum (JurisdictionConfig.minMultiProviderThreshold: EU=1, US=2, UK=1, SG=2, UAE=2). Per-jurisdiction requireSignedSignals decides whether unsigned proofs are acceptable: US (BSA), Singapore, and UAE (VARA) require signed; EU (AMLD6) and UK (MLR) accept either. The signer_pubkey_hash public input is validated against an on-chain registry, so a compromised provider can be rotated without redeploying circuits.

Formal derivations for the unsigned circuits in Appendix I. Signed-variant circuits share the public-input shape of their base circuit (0x07 with 0x01, 0x08 with 0x02) plus the in-circuit signature check; 0x09 extends 0x07 with M parallel signer slots.

Jurisdiction Thresholds

F. Trust Score Providers

Humanity (Max 25 points)

Identity (Max 35 points)

Reputation (Max 20 points)

Compliance (Max 40 points)

Diminishing Returns

• 1st provider in category: 100% of points
• 2nd provider: 25% of points
• 3rd+ providers: 10% of points

Score Reachability

Maximum achievable: ~120 points. Most retail users reach Trusted or Verified. Institutional tier requires licensed compliance providers (Chainalysis) and is designed for entities, not individuals.

G. Glossary

Aztec: Zero-knowledge L2 for private smart contract execution on Ethereum. Unlike EVM chains where all execution is public and replayed by every node, Aztec splits transactions into a private phase (executed locally) and a public phase (executed on-network). Private state is encrypted and only visible to its owner. Alpha Network live (v4.x, March 2026). Explicitly experimental: known proving system vulnerability (v5 fix targeting July 2026), state not migrated between releases, ~$6.5M max safe value. 3,500+ sequencers, 50+ provers. Uses AIP-20/AIP-721 token standards (not ERC-20/721). Xochi connects via pxe-bridge (opens in new tab).

PXE (Private eXecution Environment): Aztec's local runtime for the private half of transactions. The PXE holds encrypted notes (Aztec's UTXO-like balance model), executes private contract functions locally, generates zero-knowledge proofs of correct execution, and submits those proofs to the Aztec network. The network never sees the plaintext inputs. pxe-bridge embeds a PXE and wraps it in JSON-RPC so that EVM solvers can create shielded notes without understanding Aztec's privacy model.

CCTP: Circle's Cross-Chain Transfer Protocol for native USDC transfers.

EIP-712: Ethereum standard for typed structured data hashing and signing.

Intent: User-signed message expressing desired trade outcome without specifying execution path.

MEV: Maximal Extractable Value. Profit from reordering, inserting, or censoring transactions.

Riddler: Xochi's protocol solver. Live on Ethereum, Optimism, Base, Arbitrum, Polygon, Robinhood Chain (USDG). <6s P95, ~2.1s delivery. Integrated with LiFi and Across.

Solver: Entity that fills intents by sourcing liquidity and executing trades.

Stealth Address: One-time receiving smart account derived via ECDH from a meta-address. ERC-5564 defines announcements; ERC-6538 defines the registry. Provides L1 settlement privacy.

Xochi's ZK Compliance Oracle: Zero-knowledge compliance proofs that verify regulatory conditions (AML, sanctions, thresholds) without revealing transaction data. Formalized as ERC-8262 (opens in new tab). Formerly referred to as ZKSAR (the name used in the legal documentation).

Additional Terms

Account Abstraction (AA, ERC-4337): Ethereum standard that lets smart contracts act as wallets. Enables gasless transactions (someone else pays the gas), batched operations, and custom authentication logic. Xochi uses it for stealth settlement so recipients can claim tokens without holding ETH.

Agent: Automated principal that holds its own keypair and transacts through Xochi as a Guest (anonymous, x402 pay-per-call) or under a Member's Mandate. See Member, Mandate, Guest below.

AML: Anti-Money Laundering. Regulations requiring financial institutions to detect and report suspicious activity.

Basis Points (bps): 1 bps = 0.01%. Used for expressing small fee percentages. 24 bps = 0.24% (the Standard-tier stablecoin fee).

CEX: Centralized exchange (Binance, Coinbase). Custodial platform where the operator holds user funds.

Counterfactual: A smart contract whose address is deterministic (computable in advance) but not yet deployed on-chain. It exists "in theory" until someone sends a transaction that deploys it. Xochi uses counterfactual SimpleAccounts for stealth settlement.

DCA: Dollar-Cost Averaging. Recurring purchases of an asset at fixed intervals to smooth out price volatility.

DEX: Decentralized exchange. Non-custodial trading venue where swaps execute via smart contracts. Examples: Uniswap, Curve.

ECDH: Elliptic Curve Diffie-Hellman. A key exchange protocol used in stealth address derivation. Allows two parties to generate a shared secret from their public keys without prior communication.

Everclear: Netting protocol for cross-chain transfers. When two opposing flows exist (A sends to B, C sends from B to A), they cancel out, reducing on-chain transactions.

Flash Loan: Uncollateralized loan borrowed and repaid within a single blockchain transaction. If repayment fails, the entire transaction reverts. Used to amplify solver capacity without custody risk.

Frontrunning: Trading ahead of a known pending transaction to profit from the expected price movement.

Gas: The unit of computational cost on Ethereum. Users pay gas fees (in ETH) to compensate validators for processing transactions. "Gasless" means a third party (paymaster) covers the fee.

Guest: An Agent transacting through Xochi without a Member account. Pays per call via x402 micropayments. Capped at Standard tier privacy.

Iceberg Order: A large order split into smaller visible pieces. Only one slice is shown at a time; when it fills, the next slice appears. Hides the full order size.

KYC: Know Your Customer. Identity verification required by financial regulations.

L1: Layer 1. The base blockchain (Ethereum mainnet). Transactions settle here with full finality.

L2: Layer 2. Chains that execute transactions off L1 and post compressed proofs back to it. Cheaper and faster than L1. Examples: Optimism, Arbitrum, Aztec.

Mandate: An EIP-712 envelope signed by a Member that authorizes a specific Agent wallet to act on the Member's behalf within scoped limits (max amount, expiry, call count). Presented per-request as X-Xochi-Delegation; the server verifies it without persisting any (Agent, Member) link. Revoked by the delegator via POST /api/auth/mandate/revoke. Live.

Member: A human authenticated via XID (passkey). Earns Trust Score through attestations, can issue Mandates to Agents.

Mempool: The queue of pending transactions waiting to be included in a block. Public on most chains, which is why MEV bots can see and frontrun your trades.

Meta-address: A public key pair (spending + viewing) from which stealth addresses are derived. Published once; used to generate unlimited one-time receiving addresses (ERC-6538).

MiCA: Markets in Crypto-Assets. EU regulation for crypto-asset service providers, effective 2024.

Noir: A domain-specific language for writing zero-knowledge circuits, developed by Aztec. Compiles to arithmetic circuits proven by Barretenberg (the proving backend). UltraHonk is the proof system. BN254 is the elliptic curve.

Nullifier: A value derived from a note that, when revealed, marks the note as spent. Prevents double-spending without revealing which note was consumed.

OTC: Over-the-counter. Direct trades between two parties, typically for large sizes ($100K+), negotiated outside public order books.

Pimlico: An ERC-4337 paymaster and bundler service. Sponsors gas for Xochi's gasless stealth claims.

Privacy Pool (category): Any anonymity-set primitive that lets a user prove membership or non-membership in a set without revealing which element. Examples: Railgun, Panther, 0xbow's Privacy Pools. Operates at the deposit layer; does not hide trade execution.

Privacy Pools (0xbow): Specific product implementing deposit set membership proofs ("my deposit isn't in the sanctioned set"). Live on mainnet since March 2025. Composes with Xochi: clean withdrawal from Privacy Pools, then private execution via Xochi.

Private Execution Venue: Xochi's category. A trading venue that hides the swap itself, not just the wallet or deposit history. Distinct from privacy pools (deposit layer) and privacy L1s (separate chains).

SAR: Suspicious Activity Report. A filing that financial institutions submit to regulators when they detect potentially illicit activity.

Sandwich Attack: An MEV attack where a bot inserts a buy order before your trade and a sell order after it, profiting from the price impact your trade creates.

Schnorr Account: An Aztec account type using Schnorr signatures for authentication. pxe-bridge derives a deterministic Schnorr account from the configured secret key.

Shielded Note: Xochi's term for what Aztec docs call a "private note" or just a "note". An encrypted UTXO that only the owner's PXE can decrypt and spend.

Slippage: The difference between the expected price of a trade and the price at execution. Caused by market movement or insufficient liquidity.

TWAP: Time-Weighted Average Price. An execution strategy that splits a large order into equal-sized slices over a time window to reduce market impact.

USDG: Global Dollar. A regulated USD stablecoin issued by Paxos. Native stablecoin of Robinhood Chain, which has no USDC; Riddler settles USDC<->USDG cross-asset corridors to and from it.

UTXO: Unspent Transaction Output. A balance model (used by Bitcoin, Aztec) where funds are represented as discrete "notes" rather than account balances. Spending a note consumes it entirely and creates new notes for the recipient and change.

VARA: Virtual Assets Regulatory Authority. Dubai's crypto regulator, operating under Law No. (4) of 2022.

VASP: Virtual Asset Service Provider. Any entity that conducts virtual asset transactions on behalf of others. Defined by FATF and adopted by VARA, MiCA, and other frameworks.

View Key: A cryptographic key that allows a third party to see (but not spend) private transaction data. Some privacy protocols use view keys for auditability. Xochi's ZK Compliance Oracle avoids this by proving compliance without creating viewable data.

x402: HTTP 402 Payment Required protocol for pay-per-call API access (https://x402.org (opens in new tab)). Xochi accepts x402 USDC payments on writes ($0.005-$0.01) and reads ($0.0001) so Guests can transact without a Member account. JWT and x402 are alternatives, not additive.

Zero-Knowledge Proof (ZKP): A cryptographic proof that a statement is true without revealing the underlying data. Example: proving your age is over 18 without revealing your birthdate.

H. Widget SDK (Upcoming)

Installation

npm install @xochi/widget-react

Basic Usage

import { XochiWidget } from "@xochi/widget-react";

<XochiWidget
  appCode="my-dapp"
  theme="dark"
  partnerFee={{ bps: 25, recipient: "0x..." }}
  onTradeComplete={(tx) => console.log(tx)}
/>;

Configuration

interface XochiWidgetParams {
  appCode: string;
  chainId?: number;
  enabledChains?: number[]; // [1, 42161, 10, 8453]
  defaultPrivacy?: PrivacyTier; // "standard" | "shielded" | "private" | "sovereign"
  partnerFee?: { bps: number; recipient: string };
  theme?: "light" | "dark" | CustomTheme;
  mode?: "swap" | "fx" | "fx-api";
  pairs?: string[]; // For FX mode: ["USDC/EURC"]
  batchEnabled?: boolean; // For fx-api mode
  webhookUrl?: string; // For fx-api mode
  exportFormat?: "csv" | "json"; // For reconciliation
}

Events

const listeners = {
  onQuoteReceived: (quote: Quote) => void,
  onTradeComplete: (result: TradeResult) => void,
  onTradeFailed: (error: Error) => void,
  onPrivacyTierChange: (tier: PrivacyTier) => void,
};

Partner Tiers

I. Formal Derivations

Mathematical specifications for the Xochi ZK Compliance Oracle. Each section defines a predicate proven in zero knowledge: the verifier learns only the public inputs, never the private witness.

Reference implementation: ERC-8262 (opens in new tab). Proof system: UltraHonk (Barretenberg). Circuit language: Noir. Merkle depth: 20 (capacity: $2^{20}$ leaves).

Hash functions. All commitments use Pedersen hash over the BN254 curve via fixed-arity wrappers ($H_2, H_3, H_4, H_6, H_8, H_{16}, H_{32}$). Domain separation between contexts is achieved by prepending an explicit domain-tag field constant to the hash input. The reference implementation defines eight tags (internal Merkle nodes, set-bound leaves, value leaves, subject-bound leaves, credential hashes, signed-variant payload, multi-signed slot payload, and signer pubkey commitment); three further commitments (provider set, config, transaction set) are fixed-arity hashes over a single context and rely on the input layout itself for distinctness. Pedersen does not separate domains by arity alone: trailing-zero generators collapse to identity, so $H_n([a, b, 0, \ldots, 0]) = H_m([a, b])$ for $m < n$ without an explicit tag. Migration to Poseidon2 is planned when stable high-level APIs are available in Noir.

I.1 Risk Score

Given $n \leq 8$ screening providers, each returning a signal $s_i \in [0, 100]$ with published weight $w_i \in [1, 10000]$:

$R = \frac{\left(\sum_{i=1}^{n} s_i \cdot w_i\right) \cdot 100}{\sum_{i=1}^{n} w_i}$

$R$ is in basis points: 0 = 0.00%, 10000 = 100.00%. Integer division truncates (max error $< 1$ bps).

Overflow bound. Worst case: $n = 8$, $s_i = 100$, $w_i = 10000$.

$8 \times 100 \times 10000 \times 100 = 800{,}000{,}000 < 2^{32} - 1 = 4{,}294{,}967{,}295$

All intermediate values fit in u32. No modular reduction occurs.

Commitment. The prover commits to the provider set via $\text{provider\_set\_hash} = H_{16}(\text{id}_1, w_1, \ldots, \text{id}_8, w_8)$ and to the weight configuration via $\text{config\_hash} = H_8(w_1, \ldots, w_8)$. The verifier checks these against published on-chain values. The prover also supplies $W = \sum w_i$ and the circuit verifies $W$ matches the sum, preventing denominator spoofing.

I.2 Compliance (Circuit 0x01)

Proves a risk score is below a jurisdiction's high-risk filing threshold.

Public inputs: jurisdiction $j \in \{0,1,2,3,4\}$, provider_set_hash, config_hash, timestamp $t$, result $m \in \{0,1\}$.

Private inputs: signals $\{s_i\}$, weights $\{w_i\}$, weight sum $W$, provider IDs $\{p_i\}$, provider count $n$.

Predicate:

$m = \begin{cases} 1 & \text{if } R < T_j \\ 0 & \text{otherwise} \end{cases}$

where $R$ is the risk score (I.1) and $T_j$ is the jurisdiction threshold:

Constraints:

1. $1 \leq n \leq 8$
2. $\forall i < n: s_i \leq 100 \land w_i > 0 \land p_i \neq 0$
3. $\forall i \geq n: s_i = 0 \land w_i = 0 \land p_i = 0$
4. $W = \sum_{i=1}^{8} w_i$
5. $\text{provider\_set\_hash} = H_{16}(p_1, w_1, \ldots, p_8, w_8)$
6. $\text{config\_hash} = H_8(w_1, \ldots, w_8)$
7. $t > 1609459200 \land t < 2^{40}$ (after 2021, before year ~36812)

I.3 Risk Score (Circuit 0x02)

Standalone risk score proof supporting threshold and range predicates. Like Compliance (I.2), this circuit commits to the provider set, preventing a prover from fabricating signals from unverified providers.

Public inputs: proof_type $\tau$, direction $d$, lower bound $\ell$, upper bound $u$, result $r$, config_hash, provider_set_hash.

Private inputs: signals $\{s_i\}$, weights $\{w_i\}$, weight sum $W$, provider IDs $\{p_i\}$, provider count $n$.

Predicate:

$r = \begin{cases} R > \ell & \text{if } \tau = \texttt{0x01} \land d = 1 \text{ (GT)} \\ R < \ell & \text{if } \tau = \texttt{0x01} \land d = 2 \text{ (LT)} \\ \ell \leq R \leq u & \text{if } \tau = \texttt{0x02} \text{ (range)} \end{cases}$

Constraints:

1. $1 \leq n \leq 8$
2. $\forall i < n: s_i \leq 100 \land w_i > 0 \land p_i \neq 0$
3. $\forall i \geq n: s_i = 0 \land w_i = 0 \land p_i = 0$
4. $W = \sum_{i=1}^{8} w_i$
5. $\text{config\_hash} = H_8(w_1, \ldots, w_8)$
6. $\text{provider\_set\_hash} = H_{16}(p_1, w_1, \ldots, p_8, w_8)$

I.4 Pattern Detection (Circuit 0x03)

Proves a transaction set exhibits no structuring, velocity, or round-amount anomalies.

Public inputs: analysis_type $a$, result $r$ (true = clean), reporting threshold $T$, time window $\Delta t$, tx_set_hash.

Private inputs: amounts $\{v_k\}$, timestamps $\{t_k\}$, count $n \leq 16$.

Commitment: $\text{tx\_set\_hash} = H_{32}(v_1, t_1, v_2, t_2, \ldots, v_{16}, t_{16})$

Constraints:

1. $1 \leq n \leq 16$
2. $\Delta t > 0$
3. $\forall k < n: t_k > 1609459200 \land t_k < 2^{40}$ (timestamp sanity on active transactions)
4. $\forall k \geq n: v_k = 0 \land t_k = 0$ (inactive slots zeroed)

Overflow bound. The floor calculation $T \cdot 90$ must not overflow u64. The circuit enforces $T \leq \lfloor 2^{64} / 90 \rfloor = 204{,}962{,}515{,}653{,}461{,}695$.

Structuring ($a = 1$). Let $F = \lfloor T \cdot 90 / 100 \rfloor$ (floor at 90% of threshold). Count suspicious transactions:

$C_s = \left|\{k : F \leq v_k < T\}\right|$

$r = \left(C_s < \left\lceil n/2 \right\rceil\right)$

Clean if fewer than half of transactions cluster just below the reporting threshold.

Velocity ($a = 2$). Let $t_{\max} = \max_k t_k$. Count transactions in the window:

$C_v = \left|\{k : t_k \geq t_{\max} - \Delta t\}\right|$

$r = (C_v \leq 10)$

Round amounts ($a = 3$). Count amounts divisible by 1000:

$C_r = \left|\{k : v_k \bmod 1000 = 0\}\right|$

$r = (C_r \cdot 100 < n \cdot 80)$

Clean if fewer than 80% of transactions are round numbers.

I.5 Attestation (Circuit 0x04)

Proves the submitter holds a valid, unexpired credential issued by an authorized provider. Each provider maintains a per-provider Merkle tree of credentials they have issued; the on-chain registry binds each tree root to the issuing provider_id, and the Solidity validator checks that the proof's claimed provider_id matches the registered provider for the supplied root.

Public inputs: provider ID $p$, credential type $\kappa \in [1,4]$, result $r$, credential root $\rho$ (the provider's per-provider credentials tree), current timestamp $t_c$, submitter $\sigma$. Credential types: 1 = KYC Basic, 4 = Institutional. Types 2 and 3 are reserved for future use (e.g., KYC Enhanced, Accredited Investor).

Private inputs: attribute $\alpha$, expiry $t_e$, Merkle index $i$, Merkle path $\pi$.

Credential hash (single-round Pedersen with explicit domain tag, binding the credential to a specific submitter at issuance time):

$h = H_6(\texttt{DOMAIN\_CREDENTIAL},\; p,\; \sigma,\; \kappa,\; \alpha,\; t_e)$

Leaf: $L = H_2(\texttt{DOMAIN\_LEAF\_VALUE},\; h)$ (value-style leaf hash with explicit tag).

Predicate:

$r = (t_c < t_e) \land (1 \leq \kappa \leq 4)$

with the implicit constraint $\text{MerkleVerify}(L, i, \pi) = \rho$ enforced by hard assert: the proof cannot be produced if the leaf is not in the tree. Forging a credential requires either breaking Pedersen preimage resistance on the leaf hash or publishing a new root, which only the provider's authorized publisher EOA can do.

I.6 Membership (Circuit 0x05)

Proves an element belongs to a set (allowlist, approved counterparties).

Public inputs: Merkle root $\rho$, set ID $\text{sid}$, timestamp $t$, result $r$.

Private inputs: element $e$, Merkle index $i$, Merkle path $\pi$.

Leaf binding: $L = H_2(e, \text{sid})$ (prevents cross-set membership claims).

Predicate:

$r = \left(\text{MerkleRoot}(L, i, \pi) = \rho\right)$

where MerkleRoot walks from leaf to root using little-endian index bits to determine left/right child placement at each level.

I.7 Non-Membership (Circuit 0x06)

Proves an element is NOT in a sorted set (sanctions list exclusion). Uses an indexed Merkle tree.

Public inputs: Merkle root $\rho$, set ID $\text{sid}$, timestamp $t$, result $r$.

Private inputs: element $e$, adjacent leaves $e_{\text{lo}}, e_{\text{hi}}$, their Merkle indices and paths.

Adjacency proof:

$r = (e_{\text{lo}} < e < e_{\text{hi}}) \land \text{MerkleVerify}(e_{\text{lo}}) \land \text{MerkleVerify}(e_{\text{hi}})$

where leaf hashes are bound to set_id: $L_{\text{lo}} = H_2(e_{\text{lo}}, \text{sid})$, $L_{\text{hi}} = H_2(e_{\text{hi}}, \text{sid})$.

Truncation defense. The BN254 scalar field is ~254 bits. Ordering comparisons use u64 casts, which truncate. Without range checks, an attacker could craft a 254-bit field element that differs from a real leaf but produces the same u64 after truncation, falsely proving non-membership of a value that IS in the tree. The circuit enforces:

$e, e_{\text{lo}}, e_{\text{hi}} < 2^{64}$

This makes truncation a no-op: the u64 cast preserves the full value.

I.8 Trust Score Aggregation

Trust scores are computed off-chain from verified attestations across four categories.

Category caps:

Diminishing returns. Within each category, the $j$-th attestation contributes a fraction of its base points $b_j$:

$d(j) = \begin{cases} 1.00 & j = 1 \\ 0.25 & j = 2 \\ 0.10 & j \geq 3 \end{cases}$

Category score:

$C_c = \min\!\left(M_c,\; \sum_{j=1}^{k} b_j \cdot d(j)\right)$

where attestations within each category are sorted by $b_j$ descending (greedy: highest-value first).

Total trust score:

$T = \sum_{c} C_c$

Maximum achievable: ~120. Tier thresholds:

I.9 Fee Function

Trust tier and asset class determine the fee. Privacy level determines data retention and is gated by trust score. There is no additive privacy premium. Each total decomposes into a never-discounted solver cost layer plus a tier-discounted venue + routing layer (the MEV rebate is retired; the solver shares 15% of price improvement).

Base fee (piecewise on trust score $T$ and asset class $a \in \{\text{stable}, \text{volatile}\}$):

$\text{base}(T, \text{stable}) = \begin{cases} 0.24\% & T \in [0, 24] \\ 0.21\% & T \in [25, 49] \\ 0.17\% & T \in [50, 74] \\ 0.14\% & T \in [75, 99] \\ 0.12\% & T \geq 100 \end{cases} \qquad \text{base}(T, \text{volatile}) = \begin{cases} 0.40\% & T \in [0, 24] \\ 0.35\% & T \in [25, 49] \\ 0.29\% & T \in [50, 74] \\ 0.25\% & T \in [75, 99] \\ 0.22\% & T \geq 100 \end{cases}$

Privacy level access requires minimum trust score $T_{\min}(\ell)$:

Effective fee (trust $T$, privacy level $\ell$, asset class $a$):

$F(T, \ell, a) = \begin{cases} -0.02\% & \ell = \text{Open} \\ 0\% & \ell = \text{Public} \\ \text{base}(T, a) & \ell \in \{\text{Standard}, \text{Stealth}, \text{Private}, \text{Sovereign}\} \land T \geq T_{\min}(\ell) \end{cases}$

Open and Public are flat-rate loss leaders. For Standard through Sovereign, the fee is trust- and asset-based. Higher trust earns both deeper privacy access and a lower total. An Institutional user (100+) pays 0.12% (stable) / 0.22% (volatile) at any privacy level. A Standard user (0-24) pays 0.24% (stable) / 0.40% (volatile) at Standard, the only level they can access.

Additional revenue: 15% of intent surplus (price improvement over quoted amount), plus solver spread captured by Riddler.

I.10 Spoofability Score and Weight Updates

Each screening provider $i$ carries a spoofability score:

$S_i = \alpha \cdot \frac{F_i}{N_i} + \beta \cdot \frac{1}{C_i} + \gamma \cdot D_i$

where:

• $F_i / N_i$: flagged-to-total address ratio (empirical sybil rate)
• $C_i$: forgery cost normalized to USD
• $D_i \in [0, 1]$: incident severity index
• $\alpha = 0.5$, $\beta = 0.3$, $\gamma = 0.2$, with $\alpha + \beta + \gamma = 1$

Effective weight:

$W_i^{\text{eff}} = W_i^{\text{base}} \cdot (1 - \delta \cdot S_i)$

$\delta = 0.4$ caps the maximum downward adjustment at 40%.

Recovery. After two consecutive improved review periods (each cycle must improve on the immediately prior one), a provider regains up to 20% of lost weight per cycle:

$W_i^{(t+1)} = W_i^{(t)} + 0.20 \cdot (W_i^{\text{base}} - W_i^{(t)})$

Convergence. After a single incident with no further degradation, recovery to within 1% of base weight takes $\lceil \log_{0.8}(0.01 / \delta \cdot S_i) \rceil$ cycles. For maximum penalty ($\delta \cdot S_i = 0.4$): $\lceil \log_{0.8}(0.025) \rceil = \lceil 16.5 \rceil = 17$ cycles (8.5 years at bi-annual cadence). For typical penalties ($\delta \cdot S_i \leq 0.1$): $\leq 5$ cycles (2.5 years).

Review cadence: bi-annual (January/July). Adjustments published 14 days before effect.

I.11 Security Properties

Soundness. A computationally bounded prover cannot produce a valid proof for $m = 1$ (meets threshold) when $R \geq T_j$. Inherited from UltraHonk (~128-bit security). Applies to all six circuits.

Zero-knowledge. The verifier learns only the public inputs. Individual signals, weights, provider identifiers, transaction amounts, timestamps, credential contents, and set elements remain hidden. Pedersen commitments are computationally hiding under the discrete log assumption on BN254.

Replay prevention. On-chain, proofs are keyed on $\text{keccak256}(\text{proof} \| \text{proofType})$. The same proof bytes submitted for different proof types are treated as distinct.

Proof-of-innocence. Attestations are stored on-chain with the original proof hash, provider set hash, and timestamp. If an address is later flagged, the historical attestation proves it was clean at $T = t_{\text{proof}}$.

I.12 Known Limitations

1. Proof front-running (partial fix). Compliance (0x01) and risk_score (0x02) proofs now include submitter as a public input. The Oracle enforces submitter == msg.sender, so these proofs cannot be front-run. Attestation (0x04), membership (0x05), and non-membership (0x06) proofs still lack submitter binding. An attacker who observes one of these in the mempool can submit it first, burning the replay slot.
2. Timestamp staleness. The circuit enforces $t > 2021$ but no recency bound. A proof generated weeks ago remains valid. The SDK applies an optional recency check (maxProofAge, default 3600s), but this is client-side only.
3. Pattern time_window. The prover chooses $\Delta t$. The circuit enforces $\Delta t > 0$, but a malicious prover can set $\Delta t = 1$ to trivially pass velocity checks. On-chain enforcement of a minimum $\Delta t$ is not yet implemented. The SDK enforces a minimum of 86,400 seconds (24 hours) at the application layer, and the solver relay rejects clearance tokens where the associated proof used $\Delta t$ below this minimum. However, these are off-chain checks that can be bypassed by a forked SDK. Moving minimum $\Delta t$ enforcement into the circuit itself is a priority update. This matters for settlement splitting (XIP-1): the anti-structuring requirement at finalization depends on a valid pattern proof, but until on-chain enforcement ships, the solver relay is the last line of defense.

J. Execution Specifications

Technical details for intent execution, inventory management, and settlement. Complements Section 6 of the whitepaper.

Inventory Check

Before self-filling an intent, Riddler computes available inventory on the destination chain:

$\text{Available} = \text{Balance} - \text{Target Threshold} - \text{Rebalancing Reserved} - \text{Intent Reserved}$

A safety buffer is applied based on trade size:

Minimum remaining after fill: $1,000 USD. Supported self-fill tokens: USDC, USDT, USDG, WETH.

Bridge Routing Priority

When self-fill is insufficient, Riddler routes through external liquidity in priority order based on urgency:

Everclear is excluded from high-urgency and emergency scenarios due to the 15-30 minute netting window. CEX routing uses Binance (primary) and Coinbase (preferred for Base).

Flash Loan Integration (Planned)

For same-chain fills where Riddler lacks inventory:

Block N:
  1. Borrow X tokens from Aave/Compound flash loan pool
  2. Transfer X tokens to user's stealth account (fill the intent)
  3. Receive user's sell tokens (from PERMIT2/ERC-3009 authorization)
  4. Repay flash loan + fee
  5. Net profit = spread - flash loan fee - gas

Cross-chain: flash loans cover the fill on the destination chain. The sell-side tokens on the origin chain are received via the user's authorization (PERMIT2 or ERC-3009). Bridge capital is still required for the duration of the cross-chain transfer.

Settlement Splitting

Two kinds, at different layers. They compose.

Compliance proof splitting (XIP-1 (opens in new tab), Draft): breaks a trade into N sub-settlements, each with its own compliance proof, linked by a tradeId in a SettlementRegistry contract. Splitting is deterministic (uniform amounts, remainder on the last sub-trade). Randomized and logarithmic distributions were considered and rejected: the compliance circuit doesn't take amounts as input, so noisy amounts buy nothing. Finalization requires a pattern detection proof (circuit 0x03) to prevent structuring. Minimum split threshold: 10 ETH.

Stealth address splitting (planned): puts each sub-settlement into a separate stealth account.

1. Derive N stealth keys from recipient's meta-address (varying ephemeral secrets)
2. Compute N counterfactual SimpleAccount addresses (salt = 0, 1, ..., N-1)
3. Split sub-trade amount equally across N accounts
4. Submit N announcements (ERC-5564, 109 bytes each)
5. Recipient scans and claims from each account independently

Gas cost scales linearly with N. Recommended threshold: $100K+ trades.

Venue routing (XIP-2 (opens in new tab), Draft): each sub-trade from XIP-1 can be routed independently to public (L1), stealth (ERC-5564), or shielded (Aztec L2) based on the user's trust score and a gas budget. Users who need trade-size privacy use shielded venues. That's the only settlement path where amounts aren't visible on-chain (the solver still sees them during execution).

Fill Rejection

When an intent exceeds available liquidity (inventory + external sources), the API returns:

{
  "error": "INSUFFICIENT_LIQUIDITY",
  "availableAmount": "50000000000",
  "requestedAmount": "100000000000",
  "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "chain": 1
}

The frontend can display the available amount and offer to fill at the reduced size (partial fill support planned).

Last updated: April 2026