Metadata-Version: 2.4
Name: scafonix-agent
Version: 1.0.19
Summary: Next-Generation Non-Custodial M-of-N MPC Security & x402 USDC Payment Infrastructure for Autonomous AI Agents
Author-email: Scafonix Team <contact@scafonix.com>
Project-URL: Homepage, https://agent.scafonix.com
Keywords: mpc,ai-agent,agentic-web,x402,usdc,non-custodial,scafonix
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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:

![Scafonix Agentic MPC Sequence Flow](https://raw.githubusercontent.com/Scafonix/scafonix-mpc/main/agent/packages/pypi/Scafonix%20Agentic%20MPC%20Sequence%20Flow.png)

---

## 💻 Installation

```bash
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)`:

```python
{
    "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:

```python
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 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"
    }

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

    # Worker 2 (Chart AI): APPROVE ✅ (Generates Partial Signature 2 with its single_share)
    part2 = worker2.sign_partial(
        single_share=worker2_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()
```

---

## 🦜 LangChain & CrewAI Agent Integration (1-Line Tool Registration)

Equip your LangChain or CrewAI autonomous agents with `ScafonixMPCTool` for production-grade agentic consensus:

```python
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from scafonix_agent import ScafonixMPCTool

# 1. Instantiate Scafonix MPC Tool
mpc_tool = ScafonixMPCTool()

# 2. Equip LangChain Agent with Scafonix MPC Security
llm = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = hub.pull("hwchase17/react")

agent = create_react_agent(llm=llm, tools=[mpc_tool], prompt=prompt)
agent_executor = AgentExecutor(agent=agent, tools=[mpc_tool], verbose=True)

# 3. Autonomous AI Trading Consensus: Evaluate & Sign Trade on Base L2
result = agent_executor.invoke({
    "input": (
        "Evaluate high-yield DEX arbitrage txHash '0x8f2c...9e10' on Base L2. "
        "Collect consensus votes: Trading AI (Worker 1) and Chart AI (Worker 2) approve trade ✅, "
        "Risk AI (Worker 3) flags volatility ❌. Reaching 2-of-3 threshold, purchase $0.005 USDC x402 Ticket "
        "and combine signatures into a valid EVM transaction."
    )
})

print("🚀 Autonomous Trade Executed:", result["output"])
```

---

## 🗝️ Human Owner Emergency Private Key Export (No x402 Ticket Required)

Human System Owners can independently export the raw 256-bit EOA Private Key (`0x...`) for emergency backup or cold storage.

> [!CAUTION]
> **AI AGENT RESTRICTION RULE**: This method is strictly reserved for **Human System Owners**. Autonomous AI Agents are prohibited from possessing or invoking key export functions.

```python
from scafonix_agent import ScafonixAgent

master = ScafonixAgent(agent_id="Human-Owner-Admin")

# Supply any 2 threshold key shares (e.g. share1 and share2)
raw_private_key = master.export_private_key(worker1_share, worker2_share)
print("🔑 Raw EOA Private Key:", raw_private_key)  # 0x...64-char hex
```

---

## 📖 API Reference Summary

| Method | Parameters | Description / Return Value |
| :--- | :--- | :--- |
| `generate_key_shares(seed1, seed2)` | Two 32-byte hex entropy seeds | `{"share1", "share2", "share3", "_meta"}` dictionary |
| `derive_address(share_a, share_b)` | Two key share strings | On-chain EOA Wallet Address (`0x...`) |
| `sign_partial(single_share, msg_hash)` | Own share, txHash | 1-time Worker Partial Signature (`partialS, r, v`) |
| `combine_signatures(partial_signatures, ticket)` | List of partial signatures, x402 Ticket | On-chain Final Signature (`r, s, v, ticketId`) |
| `export_private_key(share_a, share_b)` | Two key share strings | **[HUMAN ONLY]** Raw 256-bit Hex Private Key (`0x...`) |

---

## 📄 License

MIT © [Scafonix Team](https://agent.scafonix.com)
