Metadata-Version: 2.4
Name: signaai
Version: 0.3.0
Summary: AI agent infrastructure on Signum blockchain — payments, identity, verifiable outputs, and trustless escrow
License-Expression: MIT
Project-URL: Homepage, https://signaai.io
Project-URL: Repository, https://github.com/folkerds13/signaai
Project-URL: Issues, https://github.com/folkerds13/signaai/issues
Keywords: signum,blockchain,ai-agents,payments,escrow,smart-contracts
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# SignaAI

AI agent infrastructure on the Signum blockchain — payments, identity, verifiable outputs, and trustless escrow.

Built on Signum's self-executing AT (Automated Transaction) contracts, live since 2014. No Ethereum gas wars. No external keepers. Fixed fees around $0.00003 per transaction.

---

## Why Signum?

| Feature | Signum | Ethereum/Solana |
|---|---|---|
| Smart contract execution | Self-executing, no keeper | Requires external keeper or relayer |
| Transaction fee | ~$0.00003 fixed | Variable, often $1–$50+ |
| Energy use | <0.002% of Bitcoin | High (PoW) or validator overhead |
| Agent-to-agent payments | Native payments, fixed low fees | Possible but expensive |
| Running since | 2014 (as Burstcoin) | 2015 / 2020 |

Competitors (Coinbase x402, ERC-8004, Fetch.ai/ASI, Olas) are all building on Ethereum or Solana. Signum is greenfield for AI agent infrastructure.

---

## Install

```bash
pip install signaai
```

Or from source (editable):

```bash
git clone https://github.com/folkerds13/signaai
cd signaai
pip install -e .
```

**No external dependencies** — uses Python stdlib only (urllib, hashlib, struct, secrets).

Requires Python 3.9+.

---

## Quick Start

```python
import signaai

# Set network once at startup
signaai.network("mainnet")  # or "testnet"

# Check a balance
bal, err = signaai.wallet.get_balance("S-YOUR-ADDRESS")
print(f"{bal['confirmed']:.4f} SIGNA")

# Register your agent
signaai.identity.register_agent(
    "your secret passphrase",
    "my-agent",
    capabilities=["research", "summarization"]
)

# Stamp an output on-chain
signaai.verify.stamp(
    "your secret passphrase",
    "The answer to the task is 42.",
    label="task-001"
)
```

---

## Layers

### Layer 1 — Wallet (agent-to-agent payments)

```python
from signaai import wallet

# Check balance
bal, err = wallet.get_balance("S-XXXX-XXXX-XXXX-XXXXX")
# bal = {"confirmed": 10.5, "unconfirmed": 10.5, "address": "S-..."}

# Send SIGNA
result, err = wallet.send_signa(
    "payer passphrase",
    recipient="S-XXXX-XXXX-XXXX-XXXXX",
    amount=5.0
)

# Transaction history
txs, err = wallet.get_transactions("S-XXXX-XXXX-XXXX-XXXXX", limit=10)
```

CLI:
```bash
signaai-wallet --network mainnet balance S-XXXX-XXXX-XXXX-XXXXX
signaai-wallet --network mainnet send "passphrase" S-XXXX-XXXX-XXXX-XXXXX 5.0
signaai-wallet --network mainnet history S-XXXX-XXXX-XXXX-XXXXX
```

---

### Layer 2 — Identity (agent registry and reputation)

Agents register a unique on-chain alias with a JSON profile (name, version, capabilities, endpoint).

```python
from signaai import identity

# Register your agent
result, err = identity.register_agent(
    "your passphrase",
    "my-research-agent",
    capabilities=["research", "web-search"],
    endpoint="https://myagent.example.com",
    version="1.0.0"
)

# Look up an agent by name
agent, err = identity.lookup_agent("my-research-agent")
# agent = {"name": "my-research-agent", "address": "S-...", "capabilities": [...], ...}

# Get reputation score (derived from transaction count and history)
rep, err = identity.get_reputation("S-XXXX-XXXX-XXXX-XXXXX")
```

CLI:
```bash
signaai-identity --network mainnet register "passphrase" my-agent --capabilities research,summarization
signaai-identity --network mainnet lookup my-agent
signaai-identity --network mainnet reputation S-XXXX-XXXX-XXXX-XXXXX
```

---

### Layer 3 — Verify (tamper-proof output stamping)

Hash an AI output and record it on-chain before delivery. Anyone can verify the output hasn't been altered.

```python
from signaai import verify

# Stamp output on-chain
result, err = verify.stamp(
    "your passphrase",
    "The quarterly revenue was $4.2M, up 12% YoY.",
    label="report-2026-Q1"
)
# result = {"tx_id": "...", "hash": "sha256:abc123...", "block": 12345}

# Verify output matches on-chain record
ok, err = verify.check(
    "The quarterly revenue was $4.2M, up 12% YoY.",
    tx_id="<stamp tx id>"
)
```

CLI:
```bash
signaai-verify --network mainnet stamp "passphrase" "output text" --label task-001
signaai-verify --network mainnet check "output text" --tx TX_ID
```

---

### Protocol messages (network-free building blocks)

Parse and build compact on-chain messages without making any network calls.
This is useful for indexers, dashboards, OpenClaw skills, and custom agent
runtimes.

```python
from signaai import protocol

msg = protocol.build_escrow_submit("escrow-abc", "result_hash")
parsed = protocol.parse_message(msg)

assert parsed.kind == "escrow"
assert parsed.action == "SUBMIT"
assert parsed.escrow_id == "escrow-abc"
```

Supported message families:

- `SIGPROOF:v1:...`
- `ESCROW:CREATE|FUND|SUBMIT|RELEASE|REFUND|ASSIGN:...`
- `TASK_COMPLETE:...`
- `ARBIT_OPEN|ARBIT_VOTE|ARBIT_CLOSE:...`

---

### Layer 4 — Escrow (Phase 1: operator-mediated)

On-chain audit trail for agent task payments. An operator (trusted third party) releases or refunds.

```python
from signaai import escrow

# Payer creates escrow
result, err = escrow.create_escrow(
    "payer passphrase",
    worker_address="S-WORKER-ADDRESS",
    amount=10.0,
    task_description="Summarize these 5 documents",
    deadline_hours=24,
    operator_address="S-OPERATOR-ADDRESS"
)
escrow_id = result["escrow_id"]

# Check status
status, err = escrow.get_escrow_status(escrow_id, address="S-OPERATOR-ADDRESS")

# Operator releases payment after verifying work.
# Use expected_result_hash when the expected output hash is known, or approve=True
# when the operator has performed manual/off-chain review.
result, err = escrow.release_payment(
    "operator passphrase",
    escrow_id,
    expected_result_hash="<submitted result hash>"
)

# Or operator refunds payer
result, err = escrow.refund_escrow("operator passphrase", escrow_id)
```

CLI:
```bash
signaai-escrow --network mainnet create "payer pass" S-WORKER 10.0 "task description" --deadline-hours 24 --operator-address S-OPERATOR
signaai-escrow --network mainnet status ESCROW_ID --address S-OPERATOR
signaai-escrow --network mainnet release "operator pass" ESCROW_ID --expected-hash RESULT_HASH
signaai-escrow --network mainnet refund "operator pass" ESCROW_ID
```

Phase 1 escrow is operator-mediated. Funds are sent to the operator wallet and
released or refunded by that operator. For no-operator custody, use AT Escrow.

---

### Layer 4 — AT Escrow (Phase 2: trustless, no operator)

A smart contract holds funds. The worker reveals a preimage → contract auto-pays. Deadline passes → contract auto-refunds. No operator, no trust required.

```python
from signaai import at_escrow, wallet

# 1. Generate a secret preimage
preimage, preimage_hash = at_escrow.gen_preimage()
# Store preimage securely — reveal only after verifying the worker's output

# 2. Deploy the escrow contract
result, err = at_escrow.deploy_at(
    "payer passphrase",
    worker_address="S-WORKER-ADDRESS",
    deadline_minutes=1440,  # 24 hours
    preimage_hex=preimage
)
at_address = result["at_address"]

# 3. Fund the contract (send SIGNA to the AT address)
wallet.send_signa("payer passphrase", at_address, amount=10.0)

# 4. Verify worker's output, then reveal the preimage to them
# Worker submits preimage — AT auto-pays, no operator needed
result, err = at_escrow.submit_preimage(
    "worker passphrase",
    at_address=at_address,
    preimage_hex=preimage
)

# Check AT state
info, err = at_escrow.get_at_info(at_address)
```

CLI:
```bash
# Generate preimage
signaai-at gen-preimage

# Deploy contract
signaai-at --network mainnet deploy "payer pass" S-WORKER 1440 PREIMAGE_HEX

# Fund it
signaai-wallet --network mainnet send "payer pass" S-AT-ADDRESS 10.0

# Worker claims payment
signaai-at --network mainnet submit "worker pass" S-AT-ADDRESS PREIMAGE_HEX

# Check status
signaai-at --network mainnet info S-AT-ADDRESS
```

---

## Environment Variables

```bash
export SIGNUM_NETWORK=mainnet  # default all calls to mainnet
```

Or call `signaai.network("mainnet")` once at startup.

---

## How AT Escrow Works (trustless flow)

```
Payer                          AT Contract                    Worker
  |                                |                              |
  |-- gen_preimage() ---------->   |                              |
  |   (preimage, hash)             |                              |
  |                                |                              |
  |-- deploy_at(hash, worker) ->   |                              |
  |   (AT address)                 |                              |
  |                                |                              |
  |-- send SIGNA to AT -------->   |                              |
  |                                |  (funds held trustlessly)   |
  |                                |                              |
  |   [verify worker output]       |                              |
  |-- reveal preimage ----------->  |  <-- submit_preimage() -- |
  |                                |                              |
  |                                |-- SHA256(preimage) match? --|
  |                                |   YES → sendBalance(worker) |
  |                                |   NO + deadline passed      |
  |                                |        → refund(creator)    |
```

The contract runs entirely on-chain. No API key, no server, no operator.

---

## Examples

Small runnable examples live in `examples/`:

```bash
python examples/register_agent.py my-agent --capabilities research,summarization
python examples/stamp_output.py "output text" --label task-001
python examples/pay_agent.py S-RECIPIENT 1.0 --message "thanks"
python examples/escrow_task.py S-WORKER 1.0 "summarize this file"
python examples/parse_protocol_message.py "ESCROW:SUBMIT:escrow-1:hash"
python examples/mk_hires_sieka.py "research Signum AT use cases" --sieka-address S-SIEKA
```

Most examples read `SIGNAAI_PASSPHRASE`, `SIGNUM_NETWORK`, and
`SIGNAAI_ESCROW_OPERATOR` from the environment. `mk_hires_sieka.py` is a
dogfooding scenario only; MK and Sieka are examples, not special identities in
the SDK.

---

## Security Notes

- Prefer testnet until your agent workflow is fully rehearsed.
- Avoid passing real wallet passphrases on shared machines or in shell history.
- Phase 1 escrow is an auditable operator-mediated flow, not trustless custody.
- AT escrow is the trustless path, but should be validated on testnet before
  handling meaningful value.
- On-chain proof records prove content integrity and timestamp. They do not,
  by themselves, prove the content is factually correct.

---

## Tests

```bash
python -m unittest discover -s tests
```

---

## Network Nodes

| Network | Node |
|---|---|
| Mainnet | europe.signum.network, us.signum.network |
| Testnet | europe3.testnet.signum.network |

Testnet SIGNA faucet: https://faucet.signum.network

---

## Architecture

```
signaai/
├── api.py          — HTTP client, NQT conversion, node failover
├── wallet.py       — SIGNA send/receive/history
├── identity.py     — Agent registry, reputation scoring
├── verify.py       — Output stamping and verification
├── protocol.py     — Parse/build on-chain SignaAI messages
├── escrow.py       — Phase 1 operator-mediated escrow
├── at_escrow.py    — Phase 2 trustless AT smart contract escrow
├── arbitration.py  — Dispute records and arbitrator decisions
└── contracts/
    └── signaai_escrow.smart   — AT bytecode source
```

---

## License

MIT
