scafonix-agent

Build Your Own Self-Hosted M-of-N MPC Wallet Infrastructure with Zero Upfront Cost & Pay-per-Signature x402 Micropayments ($0.005 USDC)

scafonix-agent is the official Python SDK that empowers developers to build and deploy their own 100% self-hosted, non-custodial M-of-N MPC wallet security infrastructure for autonomous AI Agents (LangChain, CrewAI, AutoGen, ELIZA, etc.).

🌟 Key Value Proposition

• Build Your Own MPC Infrastructure: You can host and run your own independent, non-custodial multi-agent consensus MPC wallet system without relying on third-party key custodians or centralized servers.
• Zero Fixed Subscription Costs: Key share generation, wallet address derivation, and worker partial signing are 100% free with zero recurring subscription fees.
• Transparent Pay-per-Signature Pricing ($0.005 USDC): You only 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)

The following diagram illustrates how the Master AI, Worker AIs, and Scafonix x402 Ticket Gate interact during an M-of-N threshold signature transaction:

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: generate_key_shares(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: derive_address(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: sign_partial(Share 1, Pair Share 2, txHash)
    W1-->>Master: Return Partial Sig 1 ✅

    Master->>W2: Request Vote for txHash
    W2->>W2: sign_partial(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: combine_signatures([Sig 1, Sig 2], Ticket)
    Master-->>Chain: Broadcast Valid Transaction (R, S, V)

💻 Installation

pip install scafonix-agent

🎲 What are seed1 and seed2? (Dual Entropy Mechanism)

Scafonix Agentic MPC uses a Dual-Source Entropy Mixing Algorithm to guarantee cryptographic security even if one entropy source is compromised:

• seed1 (User / Master AI Entropy): A 32-byte (64-char hex) random string generated by your application, Master AI, or user secret (secrets.token_hex(32)).
• seed2 (Client / System Hardware Entropy): A 32-byte (64-char hex) random string generated by the client environment, OS hardware RNG, or secondary worker.

🛡️ Why Two Seeds?
If one random number generator (RNG) is compromised or flawed, the second independent seed guarantees 100% cryptographic randomness and zero key leak risk.

🔑 Return Data Structure Example

Dictionary structure returned when calling agent.generate_key_shares(seed1, seed2):

{
    "share1": "1-97c44a91cb12b926de7b01479e282a5b11f0eb6e5a5255443e7d172f552fecac",
    "share2": "2-3333333333333333333333333333333333333333333333333333333333333333",
    "share3": "3-8bce03f349a389019e3e580d1d855404c18f2b3df2cd77275a6c7cb80c70541e",
    "_meta": {"m": 2, "n": 3}
}

🚀 Quick Start: Complete 5-Step Agent Integration Guide

Copy and paste this ready-to-run 5-step Python integration workflow:

from scafonix_agent import ScafonixAgent

def main():
    # -------------------------------------------------------------
    # STEP 1. Initialize Master AI & 3 Worker AIs (2-of-3 Threshold)
    # -------------------------------------------------------------
    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")

    # -------------------------------------------------------------
    # STEP 2. Generate 2-of-3 Key Shares & Derive EVM Address
    # -------------------------------------------------------------
    # [IMPORTANT] DO NOT hardcode seeds in production! Generate unique random 32-byte hex seeds:
    import secrets
    seed1 = secrets.token_hex(32)
    seed2 = secrets.token_hex(32)

    shares = master.generate_key_shares(seed1, seed2)

    # [Isolated Worker Storage]
    worker1_share = shares["share1"]  # Worker 1 holds Share 1
    worker2_share = shares["share2"]  # Worker 2 holds Share 2
    worker3_share = shares["share3"]  # Worker 3 holds Share 3 (Master holds ZERO shares!)

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

    # -------------------------------------------------------------
    # STEP 3. Target Transaction Hash (32-byte Hex Hash)
    # -------------------------------------------------------------
    tx_hash = "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

    # -------------------------------------------------------------
    # STEP 4. Buy x402 Signed Ticket ($0.005 USDC on Base)
    # -------------------------------------------------------------
    ticket = {
        "ticketId": "tick_sample_999",
        "msgHash": tx_hash,
        "status": "VALID"
    }

    # -------------------------------------------------------------
    # STEP 5. 2-of-3 Voting: Workers Sign Partial & Master Combines
    # -------------------------------------------------------------
    # Worker 1 (Trading AI): APPROVE ✅ (Generates Partial Signature 1)
    part1 = worker1.sign_partial(
        single_share=worker1_share,
        pair_share_id=worker2_share,
        msg_hash=tx_hash
    )

    # Worker 2 (Chart AI): APPROVE ✅ (Generates Partial Signature 2)
    part2 = worker2.sign_partial(
        single_share=worker2_share,
        pair_share_id=worker1_share,
        msg_hash=tx_hash
    )

    # Worker 3 (Audit AI): REJECT ❌ (Suspicious risk detected - Does NOT sign)

    # Master AI combines 2 valid worker partial signatures + x402 Ticket -> Final (R, S, V)
    final_sig = master.combine_signatures(
        partial_signatures=[part1, part2],
        ticket=ticket
    )

    print("🎉 Final Valid Signature (R, S, V):", final_sig)

if __name__ == "__main__":
    main()

📖 API Reference Summary

📄 License

MIT © Scafonix Team