Metadata-Version: 2.4
Name: scafonix-agent
Version: 1.0.3
Summary: Next-Generation Non-Custodial M-of-N MPC Security & x402 USDC Payment Infrastructure for Autonomous AI Agents
Author-email: Scafonix Team <support@scafonix.com>
Project-URL: Homepage, https://agent.scafonix.com
Project-URL: Bug Tracker, https://github.com/scafonix/scafonix-mpc/issues
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

> **Next-Generation Non-Custodial M-of-N MPC Security & x402 USDC Payment Infrastructure for Autonomous AI Agents**

`scafonix-agent`는 AI 에이전트(LangChain, CrewAI, AutoGen, ELIZA 등)에게 **100% Non-custodial M-of-N 다수결 서명 지갑**과 **x402 USDC 소액 결제 인프라**를 제공하는 공식 Python SDK입니다.

---

## 💻 Installation

```bash
pip install scafonix-agent
```

---

## 🔑 Return Data Structure (반환 데이터 구조 예시)

`agent.generate_key_shares("seed1", "seed2")` 호출 시 반환되는 딕셔너리(Dictionary) 구조 안내:

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

---

## 🚀 Quick Start: Complete 5-Step Agent Workflow (전체 5단계 활용 가이드)

개발자가 복사하여 즉시 실행할 수 있는 전체 5단계 Python 예시 코드입니다:

```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
    # -------------------------------------------------------------
    shares = master.generate_key_shares(
        "8bce03f349a389019e3e580d1d855404c18f2b3df2cd77275a6c7cb80c70541e",
        "97c44a91cb12b926de7b01479e282a5b11f0eb6e5a5255443e7d172f552fecac"
    )

    # [각 Worker의 키 조각 격리 보관]
    worker1_share = shares["share1"]  # Worker 1 보유
    worker2_share = shares["share2"]  # Worker 2 보유
    worker3_share = shares["share3"]  # Worker 3 보유 (Master는 0개 보유!)

    # 온체인 EOA 지갑 주소 확인
    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): 승인 ✅ (부분 서명 생성)
    part1 = worker1.sign_partial(
        single_share=worker1_share,
        pair_share_id=worker2_share,
        msg_hash=tx_hash
    )

    # Worker 2 (Chart AI): 승인 ✅ (부분 서명 생성)
    part2 = worker2.sign_partial(
        single_share=worker2_share,
        pair_share_id=worker1_share,
        msg_hash=tx_hash
    )

    # Worker 3 (Audit AI): "위험 요소 발견으로 거절" ❌ (서명 안함)

    # Master AI 결합: 3명 중 2명(Worker 1, 2)의 서명 + x402 Ticket으로 온체인 최종 서명 (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 (핵심 메서드 요약)

| 메서드 명칭 | 파라미터 설명 | 반환값 설명 |
| :--- | :--- | :--- |
| `generate_key_shares(seed1, seed2)` | 32바이트 엔트로피 시드 2개 | `{"share1", "share2", "share3", "_meta"}` 딕셔너리 |
| `derive_address(share_a, share_b)` | 2개의 키 조각 문자열 | 온체인 EOA 지갑 주소 (`0x...`) |
| `sign_partial(single_share, msg_hash, pair_share_id)` | 본인 조각, 트랜잭션 해시, 상대 짝궁 조각 | Worker 1회성 부분 서명 딕셔너리 (`partialS, r, v`) |
| `combine_signatures(partial_signatures, ticket)` | Worker 부분서명 리스트, x402 Ticket | 온체인 최종 서명 딕셔너리 (`r, s, v, ticketId`) |

---

## 📄 License

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