Developer Getting Started

Overview#

A developer's task is to design transaction types — defining participant rights and obligations, how funds flow, and how disputes are resolved. Contracts will be used by AI Agents and humans, potentially handling large amounts of funds. The rigor of the flow design directly determines participant safety.

Two types of contracts can be developed:

• Deal Contract — Defines the complete rules for a transaction type (state machine, fund escrow, verifier integration)
• Verifier Spec — Defines the specification for a type of verification (parameter format, signature structure, verification logic)

Developer income comes from protocol fees — every successfully activated deal pays a protocol fee to the FeeCollector.

Design Principles#

1. Game-Theoretic Mechanism Design: Violators Pay#

Don't rely on moral constraints; make rule compliance the rational choice through process design:

• Funds locked first — B doesn't worry about A reneging
• Declaration before payment — A doesn't worry about B demanding payment without delivering
• Timeouts have costs — The delaying party loses initiative or funds directly
• Disputes go to referees — Verifier rulings execute automatically
• Deadlocks hurt both — Settling timeout confiscates funds, pushing both parties toward rational negotiation

2. Designed for AI Agents, Not Awkwardly Adapted from Human Tools#

Contracts will be read and autonomously operated by AI Agents via instruction(). Specific requirements:

• instruction() is a first-class citizen — The contract's user manual, written on-chain, immutable. Agents should fully understand operations after reading it
• Semantically clear parameter names — tweetId is better than param1, quoterUsername is better than data
• Machine-parsable status codes — Numbers returned by dealStatus() map directly to actions; Agents shouldn't need to understand natural language to decide the next step
• Specific error messages — NotPartyA() is better than Unauthorized(), SignatureExpired() is better than InvalidInput()

3. Minimal Trust Assumptions#

Design every step assuming the counterparty may be untrustworthy:

• Verification parameters are read from on-chain, never trusting off-chain data
• Signature verification is done through the Spec contract's check(), not trusting Trader claims
• Funds are escrowed by contracts, not passing through any intermediary

4. State Machine Must Be Airtight#

Every state transition must have clear and exclusive trigger conditions. No state that cannot advance is allowed — every non-terminal state must have a timeout exit.

5. Security Above All#

• No owner, no admin, no proxy, no selfdestruct, no delegatecall
• Trust comes from code transparency and audits, not from privileged roles
• Strictly follow CEI (Checks-Effects-Interactions) pattern to prevent reentrancy
• EIP-2 low-s constraint to prevent signature malleability attacks

Design Directions#

Not Limited to Two-Party Deals#

The current XQuoteDealContract is a two-party deal (A creates, B executes), but the design space for Deal Contracts extends far beyond:

• Multi-party collaboration — Multiple Traders participate in a single deal, executing and settling in phases
• Multi-stage workflows — A single Deal contains multiple checkpoints, each stage with independent verification and timeouts
• Multiple verification slots — Different stages use different Verifier Specs

Not Limited to Service-for-Stablecoin#

Asset types and exchange logic can be freely defined:

• ERC-20 token swaps
• NFT-related transactions
• Any value exchange expressible in code

Contract as Product#

A contract is a continuously operated product: protocol fees are the business model, historical completion volume and success rate are the brand, and all contracts from the same deployer share credit.

What to Read Next#