signaai 0.3.1

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

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

pip install signaai

Or from source (editable):

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

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(
    os.environ["WALLET_SECRET"],   # passphrase — never hard-code it
    "my-agent",
    capabilities=["research", "summarization"]
)

# Stamp an output on-chain
signaai.verify.stamp(
    os.environ["WALLET_SECRET"],
    "The answer to the task is 42.",
    label="task-001"
)

---

Layers

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

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(
    os.environ["WALLET_SECRET"],
    recipient="S-XXXX-XXXX-XXXX-XXXXX",
    amount=5.0
)

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

CLI:

signaai-wallet --network mainnet balance S-XXXX-XXXX-XXXX-XXXXX
signaai-wallet --network mainnet send env:WALLET_SECRET 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).

from signaai import identity

# Register your agent
result, err = identity.register_agent(
    os.environ["WALLET_SECRET"],
    "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:

signaai-identity --network mainnet register env:WALLET_SECRET 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.

from signaai import verify

# Stamp output on-chain
result, err = verify.stamp(
    os.environ["WALLET_SECRET"],
    "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:

signaai-verify --network mainnet stamp env:WALLET_SECRET "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.

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.

from signaai import escrow

# Payer creates escrow
result, err = escrow.create_escrow(
    os.environ["WALLET_SECRET"],
    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:

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.

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(
    os.environ["WALLET_SECRET"],
    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(os.environ["WALLET_SECRET"], 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(
    os.environ["WALLET_SECRET"],
    at_address=at_address,
    preimage_hex=preimage
)

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

CLI:

# 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

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

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

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