StateSet iCommerce: Infrastructure for Autonomous Commerce

A Technical Paper on Embedded, Verifiable Commerce Systems for AI Agents

Abstract

StateSet iCommerce is a comprehensive infrastructure stack enabling autonomous AI agents to conduct commerce operations with cryptographic verifiability. The system comprises five integrated components: (1) an embedded commerce engine providing 700+ API methods across 32 commerce domains, compiled to 10 language runtimes; (2) a distributed event sequencer implementing Verifiable Event Sync (VES) with Merkle commitments and end-to-end encryption; (3) Set Chain, an Ethereum Layer-2 optimistic rollup for on-chain settlement and proof verification; (4) the x402 HTTP-native payment protocol for stablecoin micropayments between AI agents; and (5) a multi-channel messaging gateway connecting commerce agents to 9 communication platforms. This paper presents the architecture, implementation details, and design rationale for building commerce infrastructure where AI agents are first-class participants in economic transactions. Keywords: embedded databases, event sourcing, AI agents, commerce, blockchain, Merkle trees, optimistic rollups, MCP, x402, vector search, messaging gateway

1. Introduction

1.1 The Problem

Traditional commerce platforms were designed for human operators accessing centralized services via network APIs. This architecture introduces several limitations for autonomous AI agents:

Latency: Network round-trips add 50-500ms per operation
Availability: Agents cannot operate without network connectivity
Auditability: No cryptographic proof that operations occurred correctly
Cost: Per-API-call pricing creates unpredictable marginal costs
Trust: Agents must trust centralized providers for data integrity
Payments: No native mechanism for agent-to-agent economic settlement
Communication: No unified channel for agent-customer interaction across platforms

As AI agents increasingly participate in economic activity—managing inventory, processing orders, coordinating supply chains, handling customer service across messaging platforms—these limitations become critical barriers.

1.2 Our Contribution

We present StateSet iCommerce, a five-layer infrastructure stack addressing these challenges:

Layer	Component	Function
Compute	stateset-embedded	In-process commerce engine
Coordination	stateset-sequencer	Distributed event ordering
Settlement	Set Chain (L2)	On-chain verification
Payments	x402 Protocol	HTTP-native stablecoin payments
Communication	Messaging Gateway	9-channel agent interaction

The system enables:

Offline-first operation: Complete commerce functionality without network
Cryptographic verifiability: Merkle proofs for any transaction
Multi-agent coordination: Deterministic ordering across distributed agents with end-to-end encryption
Settlement finality: Ethereum-backed proof anchoring
Native payments: Stablecoin micropayments via HTTP 402
Omnichannel presence: AI agents operating across WhatsApp, Telegram, Discord, Slack, and more
Semantic search: Hybrid vector + BM25 search across all commerce entities
Voice interaction: Speech-to-text and text-to-speech for conversational commerce

1.3 Paper Organization

Section 2 describes the embedded commerce engine architecture. Section 3 details the Verifiable Event Sync protocol. Section 4 presents Set Chain and on-chain settlement. Section 5 introduces the x402 payment protocol. Section 6 discusses the Model Context Protocol integration for AI agents. Section 7 covers the multi-channel messaging gateway. Section 8 presents operational infrastructure including heartbeat monitoring, permission sandboxing, and persistent memory. Section 9 evaluates performance and security properties. Section 10 surveys related work, and Section 11 concludes.

2. Embedded Commerce Engine

2.1 Design Philosophy

The embedded commerce engine follows the SQLite model: a library that runs in the application’s process, storing state in a local file with zero external dependencies. This architecture provides:

Deterministic execution: Same inputs always produce identical outputs
Portable state: Single file contains complete operational data
Zero marginal cost: No per-operation pricing
Instant availability: No network connection required

2.2 System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                      stateset-icommerce                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────────────┐                                               │
│   │  stateset-core  │  Pure domain models (400+ types)              │
│   │   ~45,000 LOC   │  Zero I/O dependencies                       │
│   └────────┬────────┘  Business logic, traits, metrics              │
│            │                                                        │
│            ▼                                                        │
│   ┌─────────────────┐                                               │
│   │   stateset-db   │  Database abstraction layer                   │
│   │   ~55,000 LOC   │  SQLite + PostgreSQL backends                 │
│   └────────┬────────┘  70+ tables, 28 migrations                    │
│            │                                                        │
│            ▼                                                        │
│   ┌─────────────────┐                                               │
│   │stateset-embedded│  Unified high-level API                       │
│   │   ~39,000 LOC   │  700+ public methods                         │
│   └────────┬────────┘  Sync + Async, event emission, transactions   │
│            │                                                        │
├────────────┼────────────────────────────────────────────────────────┤
│            ▼                                                        │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                    Language Bindings (10)                    │   │
│   │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐   │   │
│   │  │Node.js │ │ Python │ │  WASM  │ │  Ruby  │ │  PHP   │   │   │
│   │  │ (NAPI) │ │ (PyO3) │ │(wasm)  │ │(Magnus)│ │(ext-rs)│   │   │
│   │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘   │   │
│   │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐   │   │
│   │  │  Java  │ │ Kotlin │ │ Swift  │ │  .NET  │ │   Go   │   │   │
│   │  │ (JNI)  │ │ (JNI)  │ │ (FFI)  │ │(P/Inv) │ │ (cgo)  │   │   │
│   │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘   │   │
│   └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

2.3 Domain Model

The core domain consists of 32 modules covering complete commerce and back-office operations: Commerce Operations:

Module	Entities	Key Operations
Customers	Customer, Address	CRUD, profile management
Products	Product, Variant, Attribute	Catalog, pricing, inventory links
Inventory	Item, Balance, Reservation	Multi-location tracking, reservations
Orders	Order, OrderItem, Status	Full lifecycle, fulfillment
Carts	Cart, CartItem	Shopping, checkout flow
Payments	Payment, Refund, Method	Multi-method processing
Returns	Return, ReturnItem, RMA	Return authorization workflow
Shipments	Shipment, Event, Tracking	Carrier integration
Promotions	Promotion, Coupon, Rule	Discounts, BOGO, tiered
Subscriptions	Plan, Subscription, Cycle	Recurring billing

Supply Chain & Warehouse:

Module	Entities	Key Operations
Warehouse	Warehouse, Zone, Location	Location hierarchy, bin management
Receiving	Receipt, ReceiptItem, PutAway	Inbound goods, put-away tracking
Fulfillment	Wave, PickTask, PackTask, ShipTask	Pick/pack/ship workflow
Lot Tracking	Lot, LotCertificate, LotTransaction	Traceability, COA/COC management
Serial Numbers	SerialNumber, SerialHistory	Unit-level tracking, warranty lookup
Backorders	Backorder, Allocation, Fulfillment	Priority queuing, allocation
Manufacturing	BOM, WorkOrder, Task	Bill of materials
Purchase Orders	PO, Supplier	Procurement
Quality	Inspection, NCR, QualityHold, DefectCode	Multi-stage QC, non-conformance

Financial:

Module	Entities	Key Operations
General Ledger	GlAccount, JournalEntry, GlPeriod	Double-entry, auto-posting, trial balance
Accounts Receivable	CreditMemo, WriteOff, CollectionActivity	AR aging, statements, collections
Accounts Payable	Bill, BillPayment, PaymentRun	AP aging, payment scheduling
Invoices	Invoice, Item, AR	Accounts receivable
Cost Accounting	CostLayer, CostAdjustment, CostVariance	FIFO/LIFO/weighted average, valuation
Credit	CreditAccount, CreditApplication, CreditHold	Credit review, risk rating
Tax	Jurisdiction, Rate, Exemption	US/EU/CA multi-jurisdiction
Currency	ExchangeRate, Money	35+ currencies

Platform:

Module	Entities	Key Operations
x402	PaymentIntent, PaymentReceipt, PaymentBatch	HTTP-native stablecoin payments
Vector Search	VectorSearchResult, EmbeddingMetadata	Hybrid semantic + BM25 search
Analytics	Summary, Forecast	Business intelligence
Warranties	Warranty, Claim	Coverage tracking
Forecasting	ForecastModel, DemandSignal	Demand planning
Sync	Outbox, SyncState	Event synchronization

Total: 400+ domain types with full serde serialization.

2.4 Database Layer

The database layer provides a unified interface over multiple backends: SQLite (Embedded)

Zero-configuration deployment
Single-file state portability
ACID transactions via WAL mode
~200μs typical query latency
FTS5 full-text search for BM25 ranking
BLOB-based vector embedding storage

PostgreSQL (Enterprise)

Horizontal scalability
Advanced query optimization
Point-in-time recovery
Connection pooling
True async operations via AsyncCommerce API

Schema Design Principles:

Normalized core entities: Customers, products, orders
Denormalized analytics: Pre-aggregated summary tables
Event tables: Append-only for audit trail
Version columns: Optimistic concurrency control
Vector tables: Embedding storage with metadata for semantic search
FTS5 tables: Full-text search indexes for BM25 ranking

Database Infrastructure:

Feature	Description
Saga Orchestration	Multi-step distributed transactions with rollback
Backup & Restore	Full backups (VACUUM INTO), SHA256 verification, retention policies
Idempotency Keys	Deduplication at the database level
Performance Indexes	Dedicated migration for query optimization
Parse Helpers	Type-safe row parsing with proper error propagation
Repository Macros	Code generation to eliminate duplicate implementations
32 Repository Traits	One trait per domain with full CRUD + domain operations

2.5 Vector Search

The embedded engine supports hybrid semantic + keyword search, feature-gated behind the vector flag:

┌─────────────────────────────────────────────────────────────────────┐
│                       Hybrid Search Pipeline                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Query: "red running shoes under $100"                              │
│              │                                                      │
│              ├──────────────────┬───────────────────┐               │
│              ▼                  ▼                   ▼               │
│   ┌──────────────┐   ┌──────────────┐    ┌──────────────┐         │
│   │   Semantic    │   │     BM25     │    │   Filters    │         │
│   │   (Cosine)    │   │    (FTS5)    │    │  (price<100) │         │
│   │  1536-dim     │   │  Tokenized   │    │  Structured  │         │
│   └──────┬───────┘   └──────┬───────┘    └──────┬───────┘         │
│          │                  │                   │                  │
│          └──────────────────┼───────────────────┘                  │
│                             ▼                                      │
│                  ┌──────────────────┐                               │
│                  │ Reciprocal Rank  │                               │
│                  │   Fusion (RRF)   │                               │
│                  └────────┬─────────┘                               │
│                           ▼                                        │
│                    Ranked Results                                   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Components:

Embedding Service: OpenAI text-embedding-3-small (1536 dimensions) for generating vectors
Vector Store: Pure Rust cosine similarity computation over SQLite BLOB columns
BM25 Store: SQLite FTS5 full-text search for keyword relevance
RRF Fusion: Reciprocal Rank Fusion combines semantic and keyword scores
Entity Coverage: Products, customers, orders, and inventory items

API:

// Index a product for search
commerce.vector().index_product(&product_id).await?;

// Hybrid search
let results = commerce.vector().search_products("red shoes", 10).await?;

2.6 Multi-Runtime Compilation

The Rust core compiles to 10 target runtimes:

Runtime	Technology	Use Case
Native Rust	Direct linking	High-performance backends
Node.js	NAPI-RS	JavaScript/TypeScript applications
Python	PyO3 + Maturin	Data science, ML pipelines
Browser	wasm-pack	Client-side applications
Edge	WASM	Cloudflare Workers, Vercel Edge
Ruby	Magnus	Rails applications
PHP	ext-php-rs	Laravel/WordPress integrations
Java	JNI	Enterprise JVM applications
Kotlin	JNI	Android, server-side Kotlin
Swift	C FFI	iOS/macOS applications
.NET/C#	P/Invoke	ASP.NET, Unity applications
Go	cgo	Go microservices

Each binding exposes the full 700+ method API with native type mappings.

2.7 Async Commerce API

For PostgreSQL deployments, a fully async API is provided:

// Feature-gated behind `postgres`
let commerce = AsyncCommerce::builder()
    .postgres_url("postgresql://localhost/stateset")
    .max_connections(20)
    .build()
    .await?;

let orders = commerce.orders().list(None, Some(50)).await?;
let customer = commerce.customers().get(&customer_id).await?;

The AsyncCommerce struct mirrors the synchronous Commerce API, providing AsyncOrders, AsyncCustomers, AsyncInventory, and all 32 domain accessors with true non-blocking I/O.

3. Verifiable Event Sync (VES)

3.1 Motivation

When multiple AI agents operate on commerce data—one managing inventory, another processing orders, a third handling returns—they must coordinate without central authority. VES provides:

Canonical ordering: Global sequence numbers eliminate ambiguity
Eventual consistency: Offline agents sync when reconnected
Conflict detection: Optimistic concurrency with explicit handling
Cryptographic proofs: Merkle trees enable verification
End-to-end encryption: Agent-to-agent encrypted communication groups
Key management: Ed25519/X25519 key generation, rotation, and registration

3.2 Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         VES Architecture                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────┐     ┌───────────────┐     ┌───────────────┐     │
│  │  Agent A      │     │  Agent B      │     │  Agent C      │     │
│  │  (Orders)     │     │  (Inventory)  │     │  (Returns)    │     │
│  │  ┌─────────┐  │     │  ┌─────────┐  │     │  ┌─────────┐  │     │
│  │  │ SQLite  │  │     │  │ SQLite  │  │     │  │ SQLite  │  │     │
│  │  │ Outbox  │  │     │  │ Outbox  │  │     │  │ Outbox  │  │     │
│  │  └────┬────┘  │     │  └────┬────┘  │     │  └────┬────┘  │     │
│  │  ┌────┴────┐  │     │  ┌────┴────┐  │     │  ┌────┴────┐  │     │
│  │  │Ed25519  │  │     │  │Ed25519  │  │     │  │Ed25519  │  │     │
│  │  │Keystore │  │     │  │Keystore │  │     │  │Keystore │  │     │
│  │  └────┬────┘  │     │  └────┬────┘  │     │  └────┬────┘  │     │
│  └───────┼───────┘     └───────┼───────┘     └───────┼───────┘     │
│          │                     │                     │             │
│          └─────────────────────┼─────────────────────┘             │
│                                │                                    │
│                    Encrypted Push/Pull                              │
│                                │                                    │
│                                ▼                                    │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    stateset-sequencer                        │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │   │
│  │  │   Ingest    │  │  Sequencer  │  │  Commitment Engine  │  │   │
│  │  │  (Dedup)    │──│  (Order)    │──│  (Merkle Roots)     │  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘  │   │
│  │  ┌─────────────┐  ┌─────────────┐                           │   │
│  │  │Key Registry │  │  Encryption │                           │   │
│  │  │ (Ed25519)   │  │   Groups    │                           │   │
│  │  └─────────────┘  └─────────────┘                           │   │
│  │                          │                    │              │   │
│  │                          ▼                    ▼              │   │
│  │  ┌─────────────────────────────────────────────────────┐    │   │
│  │  │              PostgreSQL Event Store                  │    │   │
│  │  │  events │ sequence_counters │ commitments            │    │   │
│  │  └─────────────────────────────────────────────────────┘    │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

3.3 Event Envelope

Every operation emits an event envelope:

pub struct EventEnvelope {
    // Identity
    pub event_id: Uuid,           // Global idempotency key
    pub command_id: Option<Uuid>, // Intent-level deduplication

    // Routing
    pub tenant_id: TenantId,      // Organization isolation
    pub store_id: StoreId,        // Store within tenant

    // Classification
    pub entity_type: EntityType,  // order, product, inventory...
    pub entity_id: String,        // Entity identifier
    pub event_type: EventType,    // order.created, inventory.adjusted...

    // Payload
    pub payload: serde_json::Value, // JSON event data
    pub payload_hash: Hash256,      // SHA-256 of canonical JSON

    // Ordering
    pub base_version: Option<u64>,  // OCC version at authoring
    pub sequence_number: Option<u64>, // Assigned by sequencer

    // Provenance
    pub created_at: DateTime<Utc>,
    pub source_agent: AgentId,
    pub signature: Option<Vec<u8>>,
}

3.4 Sequencing Algorithm

The sequencer assigns canonical sequence numbers:

Algorithm: EventSequencing
Input: EventBatch from agent
Output: IngestReceipt with assigned sequences

1. DEDUPLICATION
   for each event in batch:
     if event.event_id exists in events table:
       reject as DuplicateEventId
     if event.command_id exists in events table:
       reject as DuplicateCommandId

2. VALIDATION
   for each event in batch:
     computed_hash = SHA256(canonical_json(event.payload))
     if computed_hash != event.payload_hash:
       reject as InvalidPayloadHash
     validate schema for event.entity_type, event.event_type

3. SEQUENCE ALLOCATION (atomic)
   count = batch.events.length
   (start, end) = UPDATE sequence_counters
                  SET current_sequence = current_sequence + count
                  WHERE tenant_id = ? AND store_id = ?
                  RETURNING current_sequence - count, current_sequence - 1

4. STORAGE (atomic)
   for i, event in enumerate(batch.events):
     event.sequence_number = start + i
     INSERT INTO events (event)
       ON CONFLICT (event_id) DO NOTHING

5. RETURN IngestReceipt {
     batch_id: new_uuid(),
     events_accepted: count - rejected_count,
     assigned_sequence_start: start,
     assigned_sequence_end: end,
     head_sequence: end
   }

3.5 Merkle Commitment

Events are batched into Merkle trees for cryptographic commitment:

Merkle Tree Construction:

                    Root Hash
                   /         \
                  /           \
             H(01)             H(23)
            /     \           /     \
         H(0)     H(1)     H(2)     H(3)
          |        |        |        |
        Leaf0   Leaf1    Leaf2    Leaf3

Leaf[i] = SHA256(payload_hash || sequence || entity_type || entity_id)

BatchCommitment Structure:

pub struct BatchCommitment {
    pub batch_id: Uuid,
    pub tenant_id: TenantId,
    pub store_id: StoreId,
    pub prev_state_root: Hash256,  // State before batch
    pub new_state_root: Hash256,   // State after batch
    pub events_root: Hash256,      // Merkle root of events
    pub event_count: u32,
    pub sequence_range: (u64, u64),
    pub committed_at: DateTime<Utc>,
    pub chain_tx_hash: Option<Hash256>, // On-chain anchor
}

3.6 Optimistic Concurrency Control

VES uses optimistic concurrency without blocking:

OCC Flow:

1. Agent authors event with base_version = 5 (current entity version)
2. Event pushed to sequencer, stored with base_version = 5
3. Projector applies event:
   - Get current entity version (now = 7)
   - Check: base_version (5) != current (7)
   - CONFLICT DETECTED
4. Projector emits: event.rejected { reason: VersionConflict }
5. Event log remains immutable; rejection tracked
6. Agent receives rejection notification

Key Principle: Events are never rejected at sequencing time due to version conflicts. The event log is immutable. Conflicts are detected and recorded at projection time.

3.7 Conflict Resolution Strategies

When conflicts are detected, VES supports multiple resolution strategies:

Strategy	Behavior	Use Case
Remote-wins	Accept sequencer version	Default for inventory
Local-wins	Prefer local agent state	Agent-authoritative data
Merge	Field-level merge	Non-conflicting updates
Manual	Queue for human review	High-value transactions

Conflict resolution is configurable per entity type, allowing different strategies for different domains.

3.8 Key Management and Encryption

VES includes a complete cryptographic key management system: Key Generation and Registration:

Agent Key Lifecycle:

GENERATE: Ed25519 signing key + X25519 encryption key
REGISTER: Publish public keys to sequencer key registry
ROTATE: Time-based or usage-based rotation policies
REVOKE: Mark keys as revoked in registry

Encryption Groups:

Multi-agent groups with shared encryption contexts
X25519 key exchange for group secret derivation
Per-message encryption for sensitive commerce data (payment details, PII)
Group membership management (add/remove agents)

Rotation Policies:

Policy	Trigger	Description
Time-based	Configurable interval	Rotate keys every N hours/days
Usage-based	Operation count	Rotate after N signing operations
Manual	Admin action	Force rotation on demand

3.9 Local Outbox Pattern

Each agent maintains a local SQLite outbox:

CREATE TABLE outbox (
    local_seq INTEGER PRIMARY KEY AUTOINCREMENT,
    event_id TEXT UNIQUE NOT NULL,
    command_id TEXT,
    tenant_id TEXT NOT NULL,
    store_id TEXT NOT NULL,
    entity_type TEXT NOT NULL,
    entity_id TEXT NOT NULL,
    event_type TEXT NOT NULL,
    payload TEXT NOT NULL,
    payload_hash TEXT NOT NULL,
    base_version INTEGER,
    source_agent TEXT NOT NULL,
    created_at TEXT NOT NULL,
    -- Sync tracking
    sync_status TEXT DEFAULT 'pending',
    remote_sequence INTEGER,
    synced_at TEXT,
    rejection_reason TEXT
);

Sync Flow:

Mutation occurs locally → event appended to outbox
Agent pushes pending events to sequencer
Sequencer returns IngestReceipt with sequence numbers
Agent updates outbox with remote_sequence, synced_at
Agent pulls events from other agents
Events applied locally, entity versions updated

4. Set Chain: On-Chain Settlement

4.1 Overview

Set Chain is an Ethereum Layer-2 optimistic rollup built on the OP Stack, providing cryptographic finality for commerce events. Chain Parameters:

Parameter	Value
Chain ID	84532001
Block Time	2 seconds
Gas Limit	30M per block
Settlement Layer	Ethereum (Sepolia/Mainnet)
Native Token	ETH

4.2 Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        Set Chain Architecture                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                    stateset-sequencer                          │ │
│  │                    (Batch Commitments)                         │ │
│  └────────────────────────────┬──────────────────────────────────┘ │
│                               │                                     │
│                     GET /v1/commitments/pending                     │
│                               │                                     │
│                               ▼                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                      set-anchor                                │ │
│  │                    (Rust Service)                              │ │
│  │  ┌─────────────────────────────────────────────────────────┐  │ │
│  │  │ Poll → Validate → Submit → Notify                       │  │ │
│  │  │  │         │         │         │                        │  │ │
│  │  │  │         │         │         └─► POST /anchored       │  │ │
│  │  │  │         │         └─► SetRegistry.commitBatch()      │  │ │
│  │  │  │         └─► Min events, hash verification            │  │ │
│  │  │  └─► Sequencer API                                      │  │ │
│  │  └─────────────────────────────────────────────────────────┘  │ │
│  └────────────────────────────┬──────────────────────────────────┘ │
│                               │                                     │
│                    Ethereum Transaction                             │
│                               │                                     │
│                               ▼                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                   Set Chain L2 (OP Stack)                      │ │
│  │  ┌─────────────────────────────────────────────────────────┐  │ │
│  │  │                    SetRegistry.sol                       │  │ │
│  │  │  - commitBatch(batchId, roots, sequences)               │  │ │
│  │  │  - verifyInclusion(batchId, leafHash, proof)            │  │ │
│  │  │  - getLatestStateRoot(tenantId, storeId)                │  │ │
│  │  └─────────────────────────────────────────────────────────┘  │ │
│  │  ┌─────────────────────────────────────────────────────────┐  │ │
│  │  │                   SetPaymaster.sol                       │  │ │
│  │  │  - Gas sponsorship for merchants                        │  │ │
│  │  │  - Tiered limits (Starter/Growth/Enterprise)            │  │ │
│  │  └─────────────────────────────────────────────────────────┘  │ │
│  └────────────────────────────┬──────────────────────────────────┘ │
│                               │                                     │
│                     Batch Submission (L2 → L1)                      │
│                               │                                     │
│                               ▼                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                 Ethereum L1 (Sepolia/Mainnet)                  │ │
│  │  OptimismPortal │ L2OutputOracle │ SystemConfig                │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

4.3 SetRegistry Contract

The SetRegistry stores batch commitments and enables proof verification:

contract SetRegistry is UUPSUpgradeable, OwnableUpgradeable {

    struct BatchCommitment {
        bytes32 eventsRoot;      // Merkle root of events
        bytes32 prevStateRoot;   // State root before batch
        bytes32 newStateRoot;    // State root after batch
        uint64 sequenceStart;    // First sequence in batch
        uint64 sequenceEnd;      // Last sequence in batch
        uint32 eventCount;       // Number of events
        uint256 committedAt;     // Block timestamp
    }

    // Storage
    mapping(bytes32 => BatchCommitment) public batches;
    mapping(bytes32 => bytes32) public latestStateRoot;  // tenant+store → root
    mapping(bytes32 => uint64) public headSequence;      // tenant+store → seq
    mapping(address => bool) public authorizedSequencers;

    function commitBatch(
        bytes32 batchId,
        bytes32 tenantId,
        bytes32 storeId,
        bytes32 eventsRoot,
        bytes32 prevStateRoot,
        bytes32 newStateRoot,
        uint64 sequenceStart,
        uint64 sequenceEnd,
        uint32 eventCount
    ) external onlyAuthorizedSequencer {
        // Validate state continuity
        bytes32 key = keccak256(abi.encodePacked(tenantId, storeId));
        require(prevStateRoot == latestStateRoot[key], "State discontinuity");

        // Store commitment
        batches[batchId] = BatchCommitment({
            eventsRoot: eventsRoot,
            prevStateRoot: prevStateRoot,
            newStateRoot: newStateRoot,
            sequenceStart: sequenceStart,
            sequenceEnd: sequenceEnd,
            eventCount: eventCount,
            committedAt: block.timestamp
        });

        // Update latest state
        latestStateRoot[key] = newStateRoot;
        headSequence[key] = sequenceEnd;

        emit BatchCommitted(batchId, tenantId, storeId, eventsRoot);
    }

    function verifyInclusion(
        bytes32 batchId,
        bytes32 leafHash,
        bytes32[] calldata proof,
        uint256 leafIndex
    ) external view returns (bool) {
        bytes32 computedRoot = leafHash;
        for (uint256 i = 0; i < proof.length; i++) {
            if (leafIndex % 2 == 0) {
                computedRoot = keccak256(abi.encodePacked(computedRoot, proof[i]));
            } else {
                computedRoot = keccak256(abi.encodePacked(proof[i], computedRoot));
            }
            leafIndex /= 2;
        }
        return computedRoot == batches[batchId].eventsRoot;
    }
}

4.4 Anchor Service

The Rust anchor service bridges sequencer to chain:

pub struct AnchorService {
    sequencer_client: SequencerClient,
    registry_client: SetRegistryClient,
    config: AnchorConfig,
}

impl AnchorService {
    pub async fn run(&self) -> Result<()> {
        loop {
            // 1. Fetch pending commitments
            let pending = self.sequencer_client
                .get_pending_commitments()
                .await?;

            // 2. Filter by minimum events threshold
            let eligible: Vec<_> = pending
                .into_iter()
                .filter(|c| c.event_count >= self.config.min_events)
                .collect();

            // 3. Submit each to SetRegistry
            for commitment in eligible {
                match self.submit_commitment(&commitment).await {
                    Ok(tx_hash) => {
                        // 4. Notify sequencer of success
                        self.sequencer_client
                            .notify_anchored(&commitment.batch_id, &tx_hash)
                            .await?;

                        self.metrics.anchored_batches.inc();
                    }
                    Err(e) => {
                        self.metrics.failed_anchors.inc();
                        // Retry on next iteration
                    }
                }
            }

            tokio::time::sleep(self.config.poll_interval).await;
        }
    }
}

4.5 Settlement Finality

The system provides progressive finality guarantees:

Stage	Latency	Guarantee
Local SQLite	~1ms	Single-agent consistency
Sequencer	~100ms	Global ordering
L2 Block	~2s	Chain inclusion
L1 Batch	~10min	Optimistic finality
Challenge Period	~7 days	Cryptographic finality

Verification Flow:

User requests proof for event E
Sequencer returns Merkle proof from batch B
User calls SetRegistry.verifyInclusion(B, E.leafHash, proof)
Contract recomputes root, compares to stored eventsRoot
Returns true if event is included in anchored batch

5. x402 Payment Protocol

5.1 Overview

The x402 protocol enables HTTP-native stablecoin micropayments between AI agents. Using the HTTP 402 (Payment Required) status code, agents can negotiate and settle payments inline with commerce API calls.

5.2 Protocol Flow

┌─────────────────────────────────────────────────────────────────────┐
│                       x402 Payment Flow                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Agent A (Buyer)                    Agent B (Seller)                │
│       │                                  │                          │
│       │  1. GET /api/products/123         │                          │
│       │─────────────────────────────────►│                          │
│       │                                  │                          │
│       │  2. HTTP 402 Payment Required    │                          │
│       │  {                               │                          │
│       │    asset: "USDC",                │                          │
│       │    amount: "0.001",              │                          │
│       │    network: "set-chain",         │                          │
│       │    recipient: "0x...",           │                          │
│       │    validity: 300                 │                          │
│       │  }                               │                          │
│       │◄─────────────────────────────────│                          │
│       │                                  │                          │
│       │  3. Sign PaymentIntent           │                          │
│       │  (Ed25519 signature)             │                          │
│       │                                  │                          │
│       │  4. GET /api/products/123        │                          │
│       │  X-Payment: <signed intent>      │                          │
│       │─────────────────────────────────►│                          │
│       │                                  │                          │
│       │  5. Verify → Settle → Respond    │                          │
│       │  X-Payment-Receipt: <receipt>    │                          │
│       │◄─────────────────────────────────│                          │
│       │                                  │                          │
└─────────────────────────────────────────────────────────────────────┘

5.3 Supported Networks

Network	Chain ID	Assets	Status
Set Chain	84532001	ssUSD, USDC	Production
Arc	—	ssUSD	Production
Base	8453	USDC	Production
Ethereum	1	USDC, USDT	Production
Arbitrum	42161	USDC	Production
Optimism	10	USDC	Production
Solana	—	USDC	Production

Testnets are supported for all networks.

5.4 Core Types

pub struct X402PaymentIntent {
    pub version: String,              // "x402/1.0"
    pub asset: X402Asset,             // USDC, ssUSD, etc.
    pub amount: String,               // Decimal amount
    pub network: X402Network,         // Target chain
    pub recipient: String,            // Recipient address
    pub validity_seconds: u64,        // Payment window
    pub nonce: String,                // Replay protection
    pub domain_separator: String,     // EIP-712 domain
    pub signature: Vec<u8>,           // Ed25519 signature
}

pub struct X402PaymentReceipt {
    pub intent_hash: Hash256,         // Hash of signed intent
    pub tx_hash: Option<Hash256>,     // On-chain settlement tx
    pub settled_at: DateTime<Utc>,
    pub network: X402Network,
    pub status: PaymentStatus,        // Pending, Settled, Failed
}

pub struct X402PaymentBatch {
    pub batch_id: Uuid,
    pub intents: Vec<X402PaymentIntent>,
    pub merkle_root: Hash256,         // Batch Merkle root
    pub total_amount: String,
}

5.5 Agent Wallet Integration

Agent wallets are derived from VES signing keys, enabling unified identity across event signing and payment settlement:

VES Ed25519 Key → Derive payment address
                → Sign x402 intents
                → Verify receipts

Multi-chain balance checking allows agents to inspect their holdings across all supported networks via the stateset-pay CLI.

6. Model Context Protocol Integration

6.1 MCP Architecture

The CLI exposes commerce operations via the Model Context Protocol (MCP), enabling AI agents to invoke tools directly:

┌─────────────────────────────────────────────────────────────────────┐
│                   Agent SDK Integration (v0.3.1)                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                    @stateset/cli                               │ │
│  │  ┌─────────────────────────────────────────────────────────┐  │ │
│  │  │              claude-harness.js (62KB)                    │  │ │
│  │  │  - Multi-agent routing + skills injection               │  │ │
│  │  │  - Session management + persistent memory               │  │ │
│  │  │  - Voice mode + multi-provider switching                │  │ │
│  │  │  - Sync integration + event capture                     │  │ │
│  │  └─────────────────────────────────────────────────────────┘  │ │
│  │  ┌─────────────────────────────────────────────────────────┐  │ │
│  │  │              mcp-server.js (221KB)                       │  │ │
│  │  │  - MCP tools across 32 domains                          │  │ │
│  │  │  - Permission gating (--apply flag)                     │  │ │
│  │  │  - Schema validation + tool composition                 │  │ │
│  │  │  - Telemetry integration                                │  │ │
│  │  └─────────────────────────────────────────────────────────┘  │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                    Specialized Agents                          │ │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐      │ │
│  │  │checkout│ │ orders │ │  inv   │ │returns │ │  sync  │      │ │
│  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘      │ │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌─────────┐                │ │
│  │  │ promo  │ │  subs  │ │  tax   │ │analytics│                │ │
│  │  └────────┘ └────────┘ └────────┘ └─────────┘                │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                    Skills System (38)                          │ │
│  │  Domain knowledge injected per-agent from SKILL.md files      │ │
│  │  accounts-payable │ fulfillment │ general-ledger │ quality    │ │
│  │  warehouse │ receiving │ lots-and-serials │ vector-search     │ │
│  │  cost-accounting │ credit │ backorders │ autonomous-engine    │ │
│  │  ... and 26 more                                              │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │                    AI Providers (4)                            │ │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐                 │ │
│  │  │ Claude │ │ OpenAI │ │ Gemini │ │ Ollama │                 │ │
│  │  │ (Full) │ │ (Chat) │ │ (Chat) │ │(Local) │                 │ │
│  │  └────────┘ └────────┘ └────────┘ └────────┘                 │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

6.2 Tool Categories

MCP Tools by Domain:

Domain	Examples
Customers	list_customers, get_customer, create_customer
Orders	create_order, ship_order, cancel_order
Products	list_products, create_product
Inventory	get_stock, adjust_inventory, reserve_inventory
Returns	create_return, approve_return
Carts/Checkout	create_cart, add_cart_item, complete_checkout
Payments	create_payment, process_refund
Analytics	get_sales_summary, get_demand_forecast
Currency	convert_currency, set_exchange_rate
Tax	calculate_tax, calculate_cart_tax
Promotions	create_promotion, validate_coupon
Subscriptions	create_subscription, pause_subscription
Warehouse	create_warehouse, assign_location
Fulfillment	create_wave, assign_pick_task
Quality	create_inspection, record_ncr
Lots/Serials	create_lot, assign_serial
General Ledger	post_journal_entry, get_trial_balance
Accounts Payable	create_bill, schedule_payment
Accounts Receivable	apply_payment, generate_statement
Cost Accounting	record_cost_layer, get_valuation
Sync	sync_status, sync_push, sync_pull

6.3 Skills System

The CLI includes a skills system that injects domain-specific knowledge into agent prompts:

┌─────────────────────────────────────────────────────────────────────┐
│                        Skills Architecture                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  skills/                                                            │
│  ├── general-ledger/                                                │
│  │   └── SKILL.md          # GL domain expertise, double-entry      │
│  │                           accounting rules, period management    │
│  ├── fulfillment/                                                   │
│  │   └── SKILL.md          # Pick/pack/ship workflows, wave         │
│  │                           planning, carrier integration          │
│  ├── quality/                                                       │
│  │   └── SKILL.md          # Inspection types, NCR handling,        │
│  │                           quality hold procedures                │
│  └── ... (38 total)                                                 │
│                                                                     │
│  Infrastructure:                                                    │
│  ├── loader.js             # Load skills from filesystem            │
│  ├── parser.js             # Parse SKILL.md files                   │
│  ├── registry.js           # In-memory skill registry               │
│  ├── injector.js           # Inject into agent system prompts       │
│  └── marketplace.js        # Browse/install community skills        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Each SKILL.md file contains structured domain knowledge: entity descriptions, workflow steps, troubleshooting guides, and usage examples. When an agent is routed to handle a request, its relevant skills are injected into the system prompt, giving it deep domain expertise. 38 Built-in Skills: accounts-payable, accounts-receivable, analytics, autonomous-engine, autonomous-runbook, backorders, checkout, cost-accounting, credit, currency, customer-service, customers, embedded-sdk, engine-setup, events, fulfillment, general-ledger, inventory, invoices, lots-and-serials, manufacturing, mcp-tools, orders, payments, products, promotions, quality, receiving, returns, shipments, storefront, subscriptions, suppliers, sync, tax, vector-search, warehouse, warranties.

6.4 Multi-Provider AI Support

The CLI supports multiple AI providers with a unified interface:

Provider	Models	MCP Tools	Mode
Claude	claude-sonnet-4-20250514	Full	Agent SDK + MCP
OpenAI	gpt-4o, gpt-4, o1	None	Chat-only
Gemini	gemini-2.0-flash, gemini-2.0-pro	None	Chat-only
Ollama	llama3, mistral, etc.	None	Chat-only (local)

Claude operates as the primary agent with full MCP tool access. Non-Claude providers operate in chat-only mode, providing conversational assistance without direct commerce operations. This allows users to choose their preferred model while maintaining full functionality through Claude.

6.5 Voice Mode

The CLI supports voice-based interaction for conversational commerce:

stateset-chat --voice --tts-provider elevenlabs --stt-provider whisper

Component	Provider	Description
Speech-to-Text	OpenAI Whisper	Audio transcription
Text-to-Speech	ElevenLabs	Natural voice synthesis
Session Management	VoiceModeController	Per-session state, 30-min TTL

Voice sessions maintain state with automatic cleanup of stale sessions.

6.6 Permission Model

All write operations require explicit opt-in:

// Read operations - always allowed
stateset "list orders"
stateset "what's my inventory for SKU-001?"

// Write operations - blocked by default
stateset "create an order for alice@example.com"
// → Shows preview, does not execute

// Write operations - enabled with --apply
stateset --apply "create an order for alice@example.com"
// → Executes operation, captures event to outbox

6.7 Agent Routing

The harness automatically routes requests to specialized agents:

const AGENT_KEYWORDS = {
  'checkout': ['cart', 'checkout', 'add to cart', 'buy'],
  'orders': ['order', 'ship', 'tracking', 'fulfill'],
  'inventory': ['stock', 'inventory', 'reserve'],
  'returns': ['return', 'rma', 'refund'],
  'sync': ['sync', 'push events', 'outbox', 'sequencer'],
  // ...
};

function routeToAgent(request) {
  // Score each agent based on keyword matches
  // Return agent with highest score
  // Default to 'customer-service' (all tools)
}

6.8 Event Capture Integration

When sync is configured, commerce operations automatically emit events:

// In claude-harness.js
const rawSyncConfig = loadSyncConfig();
if (rawSyncConfig) {
  commerce = wrapCommerceWithEvents(commerce, syncConfig);
}

// Every mutation now:
// 1. Executes the operation
// 2. Appends event to _ves_outbox
// 3. Available for sync_push to sequencer

7. Multi-Channel Messaging Gateway

7.1 Overview

The messaging gateway enables AI commerce agents to operate across 9 communication platforms, providing omnichannel customer service, order management, and proactive notifications.

7.2 Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    Messaging Gateway Architecture                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐           │
│  │WhatsApp│ │Telegram│ │Discord │ │ Slack  │ │ Signal │           │
│  └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘           │
│      │          │          │          │          │                 │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐                      │
│  │ GChat  │ │WebChat │ │iMessage│ │ Teams  │                      │
│  └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘                      │
│      │          │          │          │                            │
│      └──────────┴──────────┴──────────┘                            │
│                         │                                          │
│                         ▼                                          │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                     Gateway Core                             │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │   │
│  │  │ Session  │  │Middleware│  │ Identity │  │  Reply   │    │   │
│  │  │  Store   │  │  Stack   │  │ Resolver │  │ Pipeline │    │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │   │
│  │  │  Event   │  │ Handoff  │  │  Rich    │  │ Command  │    │   │
│  │  │  Bridge  │  │  Queue   │  │ Messages │  │ Registry │    │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │   │
│  └──────────────────────────┬──────────────────────────────────┘   │
│                             │                                      │
│                             ▼                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                  Commerce Engine + MCP                       │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

7.3 Channel Support

Channel	Protocol	Status	Features
WhatsApp	Cloud API	GA	Rich media, templates, quick replies
Telegram	Bot API	GA	Inline keyboards, commands, groups
Discord	Gateway + REST	GA	Slash commands, embeds, threads
Slack	Events + Web API	GA	Blocks, modals, slash commands
Signal	signal-cli	GA	Encrypted messaging
Google Chat	Spaces API	GA	Cards, dialogs
WebChat	WebSocket	GA	Embeddable widget, real-time
iMessage	AppleScript	Experimental	macOS only
Teams	Bot Framework	Experimental	Adaptive cards

7.4 Gateway Infrastructure

Session Store: SQLite-backed persistent sessions with per-conversation state, allowing agents to maintain context across messages and platform reconnections. Middleware Stack: Koa-style onion model with composable middleware:

Rate limiting (per-user, per-channel)
Content filtering (profanity, PII detection)
Language detection
Request logging and metrics

Identity Resolution: Maps platform-specific user IDs to commerce customer records, enabling personalized service across channels. Event Bridge: Connects commerce engine events to channel notifications—when an order ships, the customer receives a notification on their preferred channel. Handoff Queue: AI-to-human escalation system for cases requiring human judgment, with full conversation context transfer. Plugin System: Extensible architecture allowing custom plugins for channel-specific functionality.

7.5 Orchestrator

The multi-channel orchestrator launches and manages gateway instances from configuration:

# Launch all configured channels
stateset-channels

# Launch specific channels
stateset-whatsapp
stateset-discord
stateset-telegram
stateset-slack

8. Operational Infrastructure

8.1 Heartbeat Monitor

The heartbeat monitor provides proactive health checking for commerce operations:

┌─────────────────────────────────────────────────────────────────────┐
│                      Heartbeat Monitor                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌────────────────┐                                                 │
│  │ HeartbeatMonitor│  (EventEmitter, configurable interval)         │
│  └───────┬────────┘                                                 │
│          │                                                          │
│          ├── low-stock          Items below threshold                │
│          ├── abandoned-carts    Stale carts past timeout            │
│          ├── revenue-milestone  Revenue target monitoring            │
│          ├── pending-returns    Returns aging beyond threshold       │
│          ├── overdue-invoices   Overdue B2B invoices                 │
│          └── subscription-churn Cancellation rate monitoring         │
│                    │                                                │
│                    ▼                                                │
│          ┌─────────────────┐                                        │
│          │AutonomousEngine │  Trigger automated responses           │
│          └────────┬────────┘                                        │
│                   ▼                                                 │
│          ┌─────────────────┐                                        │
│          │  Event Bridge   │  Route to notification channels        │
│          └────────┬────────┘                                        │
│                   ▼                                                 │
│          ┌─────────────────┐                                        │
│          │Channel Notifier │  WhatsApp, Slack, Discord, etc.        │
│          └─────────────────┘                                        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

6 Built-in Commerce Checkers:

Checker	Trigger	Action
`low-stock`	Stock below threshold	Alert, auto-reorder
`abandoned-carts`	Cart idle > timeout	Recovery notification
`revenue-milestone`	Target reached/missed	Dashboard alert
`pending-returns`	Return aging > days	Escalation
`overdue-invoices`	Invoice past due	Collection notification
`subscription-churn`	Cancellation spike	Retention campaign

HTTP API:

GET  /heartbeat/status              - Overall health
GET  /heartbeat/checks              - All checker states
POST /heartbeat/checks/:id/run      - Trigger immediate check
POST /heartbeat/checks/:id/enable   - Enable checker
POST /heartbeat/checks/:id/disable  - Disable checker

8.2 Permission Sandboxing

Fine-grained permission control for API access: Permission Levels:

none (0) < read (1) < preview (2) < write (3) < delete (4) < admin (5)

Features:

API key authentication (Bearer token + query parameter)
Per-route permission levels with longest-prefix matching
Per-HTTP-method overrides
Sandbox mode blocking dangerous operations (browser automation, shell execution)
Timing-safe key comparison
Every MCP tool mapped to a required permission level

8.3 Persistent Memory

SQLite-backed conversation memory for maintaining context across sessions:

Feature	Description
Per-conversation summaries	Automatic summarization of interactions
Fact extraction	Key facts stored for future reference
Token tracking	Usage monitoring per conversation
Keyword search	Find relevant past interactions
Vector retrieval	Semantic similarity search over memory
Auto-cleanup	Configurable retention policies

8.4 Browser Automation

Chrome DevTools Protocol (CDP) integration for web interaction:

Headless Chrome spawning and lifecycle management
Navigation, DOM queries, JavaScript evaluation
Screenshot capture
No Puppeteer dependency (pure CDP implementation)
Use cases: storefront testing, catalog sync, web scraping

8.5 Daemon Mode

Systemd service manager for production deployments:

stateset-daemon start     # Launch gateway as service
stateset-daemon stop      # Stop service
stateset-daemon logs      # View logs
stateset-daemon health    # Health check

Includes Tailscale VPN management and SSH tunnel support for secure remote access.

8.6 Scaffold Server

Code generation system for bootstrapping e-commerce storefronts:

stateset scaffold --template next-commerce

Generates complete, runnable storefronts with commerce engine integration, reducing time-to-first-store.

8.7 Prometheus Metrics

Feature-gated observability (metrics feature flag):

// Operation latency histograms
pub static ref OPERATION_LATENCY: HistogramVec;
// Operation counters (total + failed)
pub static ref OPERATION_TOTAL: CounterVec;
pub static ref OPERATION_FAILED: CounterVec;
// Active reservation gauges
pub static ref ACTIVE_RESERVATIONS: Gauge;

Metrics are exported in Prometheus text format for integration with Grafana, Datadog, and other monitoring tools.

9. Evaluation

9.1 Performance

Embedded Engine Benchmarks:

Operation	SQLite	PostgreSQL
Create Order	1.2ms	3.5ms
List Orders (100)	0.8ms	2.1ms
Inventory Adjustment	0.9ms	2.8ms
Tax Calculation	0.3ms	0.3ms
Cart Checkout	4.5ms	8.2ms
Vector Search (1000 products)	~15ms	~20ms
Hybrid Search (RRF)	~25ms	~30ms

Sequencer Throughput:

Metric	Value
Events/second (sustained)	10,000+
Batch size	100-1000 events
Sequencing latency (p99)	50ms
Merkle tree construction	~5ms/1000 events

L2 Settlement:

Metric	Value
Block time	2 seconds
commitBatch gas	~150,000
verifyInclusion gas	~30,000
L1 batch submission	~10 minutes

9.2 Security Properties

Cryptographic Guarantees:

Event Integrity: SHA-256 payload hashes prevent tampering
Inclusion Proofs: Merkle trees enable O(log n) verification
Ordering Finality: Sequence numbers are immutable once assigned
State Continuity: Each batch links to previous state root
Agent Authentication: Ed25519 signatures with key rotation
Encryption Groups: X25519-based end-to-end encryption for sensitive data
Payment Security: x402 signed intents with replay protection via nonces

Attack Resistance:

Attack	Mitigation
Event replay	UUID event_id deduplication
Intent replay	command_id deduplication
Payment replay	Nonce-based x402 intent deduplication
Sequencer equivocation	State root chain verification
Data tampering	Merkle proofs, on-chain anchoring
Agent impersonation	Ed25519 signing with key registry
Unauthorized access	Permission sandboxing, API key auth
Channel injection	Middleware content filtering

9.3 Scalability

Horizontal Scaling:

Component	Strategy
Embedded Engine	Per-agent instances, no coordination
Sequencer	Read replicas, partition by tenant
Event Store	PostgreSQL partitioning by sequence
L2 Settlement	OP Stack inherent scalability
Messaging Gateway	Per-channel horizontal scaling

State Growth:

Timeframe	Events	Storage (est.)
1 month	10M	5 GB
1 year	120M	60 GB
5 years	600M	300 GB

Event archival and pruning strategies maintain operational efficiency.

10.1 Embedded Databases

SQLite pioneered the embedded database model, demonstrating that client-server architecture is unnecessary for most applications. iCommerce applies this principle to commerce. DuckDB extends embedded analytics, inspiring our embedded forecasting capabilities.

10.2 Event Sourcing

EventStore and Kafka provide event streaming infrastructure. VES differs by:

Targeting agent-to-agent coordination
Providing cryptographic commitments
Supporting offline-first operation
Including end-to-end encryption groups

10.3 Commerce Platforms

Shopify, Stripe, and BigCommerce provide SaaS commerce infrastructure. iCommerce differs by:

Embedded architecture (no network dependency)
Agent-first design (MCP tools, not dashboards)
Verifiable execution (Merkle proofs)
Native stablecoin payments (x402)

10.4 Layer-2 Solutions

Optimism and Arbitrum provide general-purpose L2 scaling. Set Chain specializes for commerce with:

SetRegistry for event anchoring
SetPaymaster for merchant gas sponsorship
Integration with off-chain sequencer
x402 payment settlement

10.5 Agent Payment Protocols

x402 builds on the HTTP 402 status code to enable machine-to-machine payments. Unlike traditional payment processors that require human-facing checkout flows, x402 operates entirely at the protocol level, enabling autonomous agents to negotiate and settle payments as part of standard HTTP request/response cycles.

10.6 Conversational Commerce

Twilio, MessageBird, and Vonage provide messaging APIs. The StateSet messaging gateway differs by:

Deep commerce engine integration (not just messaging)
AI-native design (agents as first-class participants)
Event-driven notifications from commerce operations
Identity resolution across platforms

11. Conclusion

StateSet iCommerce represents a new paradigm for commerce infrastructure: embedded, verifiable, and agent-first. The five-layer architecture provides:

Local autonomy via the embedded engine with 32 commerce domains
Global coordination via Verifiable Event Sync with end-to-end encryption
Cryptographic finality via Set Chain settlement
Native payments via the x402 HTTP payment protocol
Omnichannel presence via the 9-channel messaging gateway

As AI agents become primary participants in economic activity, infrastructure must evolve beyond human-operated dashboards and rate-limited APIs. iCommerce provides the foundation for this autonomous commerce future—from warehouse operations and quality control to general ledger accounting and stablecoin payments, all accessible to AI agents through a unified, verifiable, embedded engine.

11.1 Future Work

Near-term (2026):

Zero-knowledge validity proofs for event batches
Agent-to-agent negotiation protocol
Cross-chain settlement bridges
Expanded vector search with custom embedding models
Additional messaging channels (Matrix, RCS)

Medium-term (2026-2027):

Decentralized identity integration
Federated learning across tenants
On-device ML models for demand prediction
Real-time collaborative editing of commerce data

Long-term (2027+):

Fully autonomous supply chain orchestration
Cross-border compliance automation
Global commerce network federation
Autonomous agent marketplaces with x402 settlement

References

SQLite Consortium. “SQLite: A Self-Contained SQL Database Engine.” https://sqlite.org
Ethereum Foundation. “Optimistic Rollups.” https://ethereum.org/en/developers/docs/scaling/optimistic-rollups/
Anthropic. “Model Context Protocol Specification.” https://modelcontextprotocol.io
Merkle, R.C. “A Digital Signature Based on a Conventional Encryption Function.” CRYPTO 1987.
Lamport, L. “Time, Clocks, and the Ordering of Events in a Distributed System.” CACM 1978.
Coinbase. “x402: HTTP-Native Payments Protocol.” https://www.x402.org
OpenAI. “Text Embedding Models.” https://platform.openai.com/docs/guides/embeddings

Appendix A: System Statistics

Component	Metric	Value
stateset-core	Lines of Code	~45,000
stateset-db	Lines of Code	~55,000
stateset-embedded	Lines of Code	~39,000
Total Rust (3 crates)	Lines of Code	~139,000
Node.js binding	Technology	NAPI-RS
Python binding	Technology	PyO3
Ruby binding	Technology	Magnus
PHP binding	Technology	ext-php-rs
Java binding	Technology	JNI
Kotlin binding	Technology	JNI
Swift binding	Technology	C FFI
.NET binding	Technology	P/Invoke
Go binding	Technology	cgo
WASM binding	Technology	wasm-pack
CLI (mcp-server)	Size	221 KB
CLI (harness)	Size	62 KB
Domain Modules	Count	32
Domain Types	Count	400+
Database Tables	Count	70+
Database Migrations	Count	28
API Methods	Count	700+
Language Bindings	Count	10
Commerce Skills	Count	38
AI Providers	Count	4
Messaging Channels	Count	9
Heartbeat Checkers	Count	6
CLI Programs	Count	26+
Sequencer	Lines of Code	~5,000
Set Chain Contracts	Lines of Code	~1,000
Anchor Service	Lines of Code	~2,250

Appendix B: API Summary

Embedded Engine (per domain)

Commerce Operations:

customers:       list, get, getByEmail, create, update, delete, count
products:        list, get, getBySku, create, update, delete, listVariants
inventory:       getStock, create, adjust, reserve, release, confirm
orders:          list, get, create, updateStatus, ship, cancel, addItem
carts:           list, get, create, addItem, updateItem, removeItem, checkout
payments:        list, get, create, markCompleted, markFailed, refund
returns:         list, get, create, approve, reject, complete
promotions:      list, get, create, activate, deactivate, validateCoupon
subscriptions:   listPlans, createPlan, subscribe, pause, resume, cancel
shipments:       list, get, create, addEvent, updateTracking

Supply Chain & Warehouse:

warehouse:       list, get, create, addZone, addLocation, getInventory, move
receiving:       list, get, create, receiveItems, putAway, complete
fulfillment:     createWave, listWaves, assignPick, completePick, pack, ship
lots:            list, get, create, split, merge, transfer, traceForward, traceBack
serials:         list, get, create, bulkCreate, transfer, lookupWarranty
backorders:      list, get, create, allocate, fulfill, getSummary
manufacturing:   listBOMs, createBOM, createWorkOrder, completeTask
purchase_orders: list, get, create, receive, close
quality:         createInspection, recordResult, createNCR, placeHold, releaseHold

Financial:

general_ledger:  createAccount, postEntry, getTrialBalance, getBalanceSheet,
                 getIncomeStatement, openPeriod, closePeriod
accounts_recv:   getAging, createCreditMemo, writeOff, applyPayment,
                 generateStatement, createCollection
accounts_pay:    createBill, schedulePay, createPaymentRun, getAging
invoices:        list, get, create, markPaid, markVoid
cost_accounting: recordLayer, adjust, getValuation, getVariance
credit:          createAccount, applyCredit, reviewApplication, placeHold
tax:             calculate, calculateCart, getRate, listJurisdictions
currency:        convert, getRate, setRate, format

Platform:

x402:            createIntent, signIntent, verifyReceipt, batchSettle
vector:          indexProduct, searchProducts, indexCustomer, searchCustomers
analytics:       getSales, getTopProducts, getForecast, getHealth
warranties:      list, get, create, fileClaim, resolveClaim
forecasting:     getDemand, generateForecast, getSeasonality
sync:            status, push, pull, outbox, retryFailed, entityHistory, full

Sequencer API

POST /api/v1/events/ingest        - Batch event ingestion
GET  /api/v1/events               - List events by sequence
GET  /api/v1/head                 - Get current head sequence
GET  /api/v1/commitments/:id      - Get batch commitment
GET  /api/v1/commitments/:id/proof - Get inclusion proof
GET  /api/v1/entities/:type/:id   - Get entity history
POST /api/v1/keys/register        - Register agent public key
GET  /api/v1/keys/:agent_id       - Get agent public key
POST /api/v1/groups/create        - Create encryption group
POST /api/v1/groups/:id/members   - Add group member

MCP Sync Tools

sync_status         - Get sync health and statistics
sync_push           - Push pending events to sequencer
sync_pull           - Pull events from sequencer
sync_outbox         - List local outbox events
sync_retry_failed   - Reset failed events for retry
sync_entity_history - Get entity event history
sync_full           - Push then pull (full sync)

Heartbeat API

GET  /heartbeat/status             - Overall health status
GET  /heartbeat/checks             - All checker states
POST /heartbeat/checks/:id/run     - Trigger immediate check
POST /heartbeat/checks/:id/enable  - Enable checker
POST /heartbeat/checks/:id/disable - Disable checker

Gateway API

POST /gateway/send                 - Send message to channel
GET  /gateway/sessions             - List active sessions
GET  /gateway/sessions/:id         - Get session details
POST /gateway/handoff              - Escalate to human agent
GET  /gateway/metrics              - Channel metrics

StateSet iCommerce v0.3.1 January 2026

Get started

Platform

StateSet One

StateSet Response

StateSet ResponseCX

StateSet iCommerce

StateSet Commerce

StateSet Sandbox

StateSet ACP

StateSet Sequencer

StateSet UCP

StateSet Cloud

Tools

​StateSet iCommerce: Infrastructure for Autonomous Commerce

​Abstract

​1. Introduction

​1.1 The Problem

​1.2 Our Contribution

​1.3 Paper Organization

​2. Embedded Commerce Engine

​2.1 Design Philosophy

​2.2 System Architecture

​2.3 Domain Model

​2.4 Database Layer

​2.5 Vector Search

​2.6 Multi-Runtime Compilation

​2.7 Async Commerce API

​3. Verifiable Event Sync (VES)

​3.1 Motivation

​3.2 Architecture

​3.3 Event Envelope

​3.4 Sequencing Algorithm

​3.5 Merkle Commitment

​3.6 Optimistic Concurrency Control

​3.7 Conflict Resolution Strategies

​3.8 Key Management and Encryption

​3.9 Local Outbox Pattern

​4. Set Chain: On-Chain Settlement

​4.1 Overview

​4.2 Architecture

​4.3 SetRegistry Contract

​4.4 Anchor Service

​4.5 Settlement Finality

​5. x402 Payment Protocol

​5.1 Overview

​5.2 Protocol Flow

​5.3 Supported Networks

​5.4 Core Types

​5.5 Agent Wallet Integration

​6. Model Context Protocol Integration

​6.1 MCP Architecture

​6.2 Tool Categories

​6.3 Skills System

​6.4 Multi-Provider AI Support

​6.5 Voice Mode

​6.6 Permission Model

​6.7 Agent Routing

​6.8 Event Capture Integration

​7. Multi-Channel Messaging Gateway

​7.1 Overview

​7.2 Architecture

​7.3 Channel Support

​7.4 Gateway Infrastructure

​7.5 Orchestrator

​8. Operational Infrastructure

​8.1 Heartbeat Monitor

​8.2 Permission Sandboxing

​8.3 Persistent Memory

​8.4 Browser Automation

​8.5 Daemon Mode

​8.6 Scaffold Server

​8.7 Prometheus Metrics

​9. Evaluation

​9.1 Performance

​9.2 Security Properties

​9.3 Scalability

​10. Related Work

​10.1 Embedded Databases

​10.2 Event Sourcing

​10.3 Commerce Platforms