# Scafonix Agentic MPC - AI Agent System Specification & Integration Guide (llms.txt)

> **Machine-Readable API Specification & Integration Prompt for AI Search Engines & Coding Agents (LLMO / llms.txt)**

- **Service Name**: Scafonix Agentic MPC
- **Service Domain**: `https://agent.scafonix.com`
- **Ticket Gate API Endpoint**: `https://mpc-api.scafonix.com/v1/ticket/issue`
- **Protocol**: x402 Micropayment Protocol (HTTP 402 Payment Required for Machine-to-Machine Payments)
- **Supported Network for x402 Micropayments**: Base Mainnet (EVM Chain ID 8453)
- **Ticket Price**: Flat $0.005 USDC per signature ticket
- **Security Standard**: 100% Non-custodial M-of-N Threshold Signatures (Zero Server Shares)

---

## 🌟 Core Value Proposition & Architecture

Scafonix Agentic MPC empowers developers to **build and host their own 100% self-hosted, non-custodial M-of-N MPC wallet security infrastructure** for autonomous AI Agents (LangChain, CrewAI, AutoGen, ELIZA, etc.).

1. **Build & Host Your Own MPC Infrastructure**:
   - Deploy independent multi-agent consensus MPC wallets without third-party key custodians or centralized servers.
   - You own 100% of your key shares with zero vendor lock-in.

2. **Zero Fixed Subscription Costs**:
   - Key share generation, wallet address derivation, and worker partial signing are **100% free with zero recurring subscription fees**.

3. **Transparent Pay-per-Signature Pricing ($0.005 USDC)**:
   - Pay a flat **$0.005 USDC per final combined signature** via native x402 micropayment protocol on Base L2 when broadcasting real on-chain transactions.

---

## 🏗️ Architecture & Sequence Flow (2-of-3 Threshold & x402 Ticket Gate)

```mermaid
sequenceDiagram
    autonumber
    actor Dev as Developer / User
    participant Master as Master AI (Orchestrator)
    participant W1 as Worker 1 (Trading AI)
    participant W2 as Worker 2 (Chart AI)
    participant W3 as Worker 3 (Audit AI)
    participant Gate as Scafonix x402 Gate ($0.005 USDC)
    participant Chain as EVM Blockchain Network

    Note over Master, W3: STEP 1 & 2: Key Generation & Address Derivation
    Dev->>Master: generateKeyShares(seed1, seed2)
    Master-->>W1: Distribute Share 1 (share1)
    Master-->>W2: Distribute Share 2 (share2)
    Master-->>W3: Distribute Share 3 (share3)
    Note over Master: Master holds ZERO Key Shares!

    Dev->>Master: deriveAddress(share1, share2)
    Master-->>Dev: Return Consensus EOA Address (0x...)

    Note over Master, Chain: STEP 3 & 4: Transaction & x402 Ticket Purchase
    Master->>Gate: Buy Ticket for txHash ($0.005 USDC on Base)
    Gate-->>Master: Issue Signed Ticket { ticketId, msgHash, status: 'VALID' }

    Note over Master, W3: STEP 5: Multi-Agent Voting & Partial Signing
    Master->>W1: Request Vote for txHash
    W1->>W1: signPartial(Share 1, Pair Share 2, txHash)
    W1-->>Master: Return Partial Sig 1 ✅

    Master->>W2: Request Vote for txHash
    W2->>W2: signPartial(Share 2, Pair Share 1, txHash)
    W2-->>Master: Return Partial Sig 2 ✅

    Master->>W3: Request Vote for txHash
    W3-->>Master: REJECT (Risk Warning detected) ❌

    Note over Master, Chain: STEP 6: Combination & Broadcast
    Master->>Master: combineSignatures([Sig 1, Sig 2], Ticket)
    Master-->>Chain: Broadcast Valid Transaction (R, S, V)
```

---

## 💻 Full Integration Guide for Coding AI Agents (Cursor, Windsurf, Claude, ChatGPT)

### 🐍 Python SDK (`scafonix-agent`)

**Installation**:
```bash
pip install scafonix-agent
```

**Complete 5-Step Python Code**:
```python
import secrets
from scafonix_agent import ScafonixAgent

def main():
    # 1. Initialize Master & 3 Worker AI Agents
    master = ScafonixAgent(agent_id="Master-Orchestrator")
    worker1 = ScafonixAgent(agent_id="Worker-1-TradingAI")
    worker2 = ScafonixAgent(agent_id="Worker-2-ChartAI")
    worker3 = ScafonixAgent(agent_id="Worker-3-AuditAI")

    # 2. Generate 2-of-3 Key Shares with Dynamic Dual Entropy
    seed1 = secrets.token_hex(32)
    seed2 = secrets.token_hex(32)
    shares = master.generate_key_shares(seed1, seed2)

    # Distribute shares: Worker 1 gets share1, Worker 2 gets share2, Worker 3 gets share3
    worker1_share = shares["share1"]
    worker2_share = shares["share2"]
    worker3_share = shares["share3"]

    # Derive Consensus Wallet Address (Share 1 + Share 2 pairing)
    wallet_address = master.derive_address(worker1_share, worker2_share)
    print("Consensus Address:", wallet_address)

    # 3. Target Transaction Hash
    tx_hash = "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

    # 4. Buy x402 Signed Ticket ($0.005 USDC on Base Mainnet via mpc-api.scafonix.com)
    ticket = {
        "ticketId": "s_tkt_8f92a10b4c739d2e",
        "msgHash": tx_hash,
        "status": "VALID",
        "issuedAt": 1786000000,
        "expiresAt": 1786000600,
        "network": "base-mainnet",
        "feePaid": "0.005 USDC",
        "signedProof": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWNrZXRJZCI6InNfdGt0XzhmOTJhMTBiNGM3MzlkMmUiLCJtc2dIYXNoIjoiMHgwMTIzNDU2Nzg5YWJjZGVmIiwiZXhwaXJlcyI6MTc4NjAwMDYwMH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }

    # 5. Workers Sign Partial (2-of-3 Threshold - Only single_share & tx_hash needed)
    part1 = worker1.sign_partial(single_share=worker1_share, msg_hash=tx_hash)
    part2 = worker2.sign_partial(single_share=worker2_share, msg_hash=tx_hash)
    # worker3 rejects vote due to risk audit check

    # Master AI Combines Final Signature
    final_sig = master.combine_signatures(partial_signatures=[part1, part2], ticket=ticket)
    print("Final Signature (R, S, V):", final_sig)

if __name__ == "__main__":
    main()
```

**LangChain & CrewAI AgentExecutor Integration**:
```python
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from scafonix_agent import ScafonixMPCTool

# Equip LangChain Autonomous Agent with Scafonix MPC Tool
llm = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = hub.pull("hwchase17/react")
agent = create_react_agent(llm=llm, tools=[ScafonixMPCTool()], prompt=prompt)
agent_executor = AgentExecutor(agent=agent, tools=[ScafonixMPCTool()], verbose=True)

# Run Autonomous AI Trading Consensus Agent
result = agent_executor.invoke({
    "input": (
        "Evaluate DEX arbitrage txHash '0x8f2c...9e10' on Base L2. Collect votes: Trading AI (Worker 1) "
        "and Chart AI (Worker 2) approve ✅, Risk AI (Worker 3) rejects ❌. Reaching 2-of-3 threshold, "
        "buy $0.005 USDC x402 Ticket and return combined EVM signature."
    )
})
```

---

### 🟨 JavaScript / TypeScript SDK (`@scafonix/agent`)

**Installation**:
```bash
npm install @scafonix/agent
```

**Complete 5-Step JavaScript Code**:
```javascript
const { ScafonixAgent } = require('@scafonix/agent');
const { ethers } = require('ethers');
const crypto = require('crypto');

async function main() {
  // 1. Initialize Master & 3 Worker AI Agents
  const master = new ScafonixAgent({ agentId: 'Master-Orchestrator' });
  const worker1 = new ScafonixAgent({ agentId: 'Worker-1-TradingAI' });
  const worker2 = new ScafonixAgent({ agentId: 'Worker-2-ChartAI' });
  const worker3 = new ScafonixAgent({ agentId: 'Worker-3-AuditAI' });

  await master.init();
  await worker1.init();
  await worker2.init();
  await worker3.init();

  // 2. Generate 2-of-3 Key Shares with Dynamic Dual Entropy
  const seed1 = crypto.randomBytes(32).toString('hex');
  const seed2 = crypto.randomBytes(32).toString('hex');
  const shares = await master.generateKeyShares(seed1, seed2);

  const worker1Share = shares['share1'];
  const worker2Share = shares['share2'];
  const worker3Share = shares['share3'];

  // Derive Consensus Wallet Address
  const walletAddress = await master.deriveAddress(worker1Share, worker2Share);
  console.log("Consensus Address:", walletAddress);

  // 3. Construct Unsigned Transaction & Calculate txHash
  const tx = ethers.Transaction.from({
    to: "0x678faFD22Fcc96B89Ad96942C86D139b005e4A9D",
    value: ethers.parseEther("0.001"),
    nonce: 0,
    gasLimit: 21000n,
    gasPrice: 10000000n,
    chainId: 8453 // Base Mainnet
  });
  const txHash = ethers.keccak256(tx.unsignedSerialized);

  // 4. Buy x402 Signed Ticket ($0.005 USDC on Base Mainnet via mpc-api.scafonix.com)
  const ticket = {
    ticketId: "s_tkt_8f92a10b4c739d2e",
    msgHash: txHash,
    status: "VALID",
    issuedAt: 1786000000,
    expiresAt: 1786000600,
    network: "base-mainnet",
    feePaid: "0.005 USDC",
    signedProof: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWNrZXRJZCI6InNfdGt0XzhmOTJhMTBiNGM3MzlkMmUiLCJtc2dIYXNoIjoiMHgwMTIzNDU2Nzg5YWJjZGVmIiwiZXhwaXJlcyI6MTc4NjAwMDYwMH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
  };

  // 5. Workers Sign Partial (2-of-3 Threshold - Only singleShare & msgHash needed)
  const part1 = await worker1.signPartial({ singleShare: worker1Share, msgHash: txHash });
  const part2 = await worker2.signPartial({ singleShare: worker2Share, msgHash: txHash });

  // Master AI Combines Final Signature
  const finalSig = await master.combineSignatures({ partialSignatures: [part1, part2], ticket: ticket });
  
  // 6. Broadcast Signed Tx
  tx.signature = { r: '0x' + finalSig.r, s: '0x' + finalSig.s, v: finalSig.v };
  console.log("Ready to Broadcast Signed Tx:", tx.serialized);
}

main().catch(console.error);
```

---

## 💳 x402 Micropayment Protocol Specifications (Base Mainnet)

1. **Initial Ticket Issue Request**:
   - `POST https://mpc-api.scafonix.com/v1/ticket/issue`
   - Body: `{ "agentId": "Master-Orchestrator", "msgHash": "<txHash>" }`

2. **HTTP 402 Payment Challenge Response**:
   - Status: `402 Payment Required`
   - Header `X-Payment-Address-EVM`: `0x2585359495B91dC4D021da42fAA2807632B2aA1B` (Base Mainnet USDC Vault)
   - Header `X-Payment-Amount`: `0.005`
   - Header `X-Payment-Currency`: `USDC`
   - Header `X-Payment-ChainId`: `8453` (Base Mainnet)

3. **Resubmit Request with Base USDC Payment Proof**:
   - `POST https://mpc-api.scafonix.com/v1/ticket/issue`
   - Header `X-Payment-Proof`: `<txHashOfUsdcTransfer>`
   - Body: `{ "agentId": "Master-Orchestrator", "msgHash": "<txHash>" }`

4. **HTTP 200 Ticket Issuance Response**:
   - Status: `200 OK`
   - Body:
```json
{
  "success": true,
  "ticket": {
    "ticketId": "s_tkt_8f92a10b4c739d2e",
    "msgHash": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "status": "VALID",
    "issuedAt": 1786000000,
    "expiresAt": 1786000600,
    "network": "base-mainnet",
    "feePaid": "0.005 USDC",
    "signedProof": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWNrZXRJZCI6InNfdGt0XzhmOTJhMTBiNGM3MzlkMmUiLCJtc2dIYXNoIjoiMHgwMTIzNDU2Nzg5YWJjZGVmIiwiZXhwaXJlcyI6MTc4NjAwMDYwMH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
  }
}
```

---

## 📖 SDK Method Reference

| Language | Method | Arguments | Description / Return |
| :--- | :--- | :--- | :--- |
| **Python** | `generate_key_shares(seed1, seed2)` | Two 32-byte hex entropy seeds | Returns `{"share1", "share2", "share3", "_meta"}` dict |
| **Python** | `derive_address(share_a, share_b)` | Two key share strings | Returns EOA wallet address (`0x...`) |
| **Python** | `sign_partial(single_share, msg_hash)` | Own share, txHash | Returns 1-time Worker Partial Signature dict |
| **Python** | `combine_signatures(partial_signatures, ticket)` | List of partial sigs, x402 Ticket | Returns final EVM signature (`r, s, v, ticketId`) |
| **Python** | `export_private_key(share_a, share_b)` | Two key share strings | **[HUMAN ONLY]** Returns raw 256-bit Hex Private Key (`0x...`) |
| **JavaScript** | `generateKeyShares(seed1, seed2)` | Two 32-byte hex entropy seeds | Returns `{ share1, share2, share3, _meta }` object |
| **JavaScript** | `deriveAddress(shareA, shareB)` | Two key share strings | Returns EOA wallet address (`0x...`) |
| **JavaScript** | `signPartial({ singleShare, msgHash })` | Options object | Returns 1-time Worker Partial Signature object |
| **JavaScript** | `combineSignatures({ partialSignatures, ticket })` | Options object | Returns final EVM signature (`r, s, v, ticketId`) |
| **JavaScript** | `exportPrivateKey(shareA, shareB)` | Two key share strings | **[HUMAN ONLY]** Returns raw 256-bit Hex Private Key (`0x...`) |

---

## 🛡️ Security Guarantees & AI Agent Restrictions

1. **AI Agent Private Key Restriction (Human Owner Only)**:
   - AI Autonomous Agents (LangChain, CrewAI, AutoGen) are **STRICTLY PROHIBITED** from requesting, possessing, or executing Private Key Export functions (`export_private_key`).
   - Key export is an offline management action reserved strictly for Human System Owners for emergency cold-storage backups.
2. **Dual-Source Entropy (`seed1`, `seed2`)**: Key shares are generated by combining `seed1` (User/Master AI Entropy) and `seed2` (Client System Hardware Entropy). Ensures 100% cryptographic randomness even if one random number generator is flawed.
3. **10-Minute Ticket Expiration (Sliding Replay Window)**:
   - Issued x402 Tickets have a **strict 10-minute validity window (600 seconds)**.
   - Master AI Orchestrators MUST consume and combine signatures within 10 minutes of ticket issuance. Expired tickets are automatically purged and rejected by the C-WASM kernel to prevent ticket reuse and replay attacks.
4. **Zero Key Exposure**: Scafonix servers hold 0 key shares. Key shares exist only across isolated agent nodes.
5. **TxHash Binding**: Signature tickets are strictly cryptographically bound to a single transaction hash (`msgHash`), preventing unauthorized reuse or ticket stealing.