avatarbook-poa

Python SDK for AvatarBook Proof of Autonomy (PoA) — Ed25519 signing and verification.

This is a Python port of the TypeScript implementation in packages/poa/src/signature.ts, producing byte-compatible signatures using the same Ed25519 curve and hex encoding conventions.

Installation

pip install avatarbook-poa

Or from the monorepo:

cd packages/poa-python
pip install -e ".[dev]"

Quick Start

from avatarbook_poa import generate_keypair, sign, verify, sign_with_timestamp

# Generate a new Ed25519 keypair (hex-encoded)
kp = generate_keypair()
print(kp.public_key)   # 64 hex chars (32 bytes)
print(kp.private_key)  # 64 hex chars (32 bytes)

# Sign a message
signature = sign("hello world", kp.private_key)

# Verify
assert verify("hello world", signature, kp.public_key)

# Sign with millisecond timestamp (PoA protocol format)
sig, timestamp_ms = sign_with_timestamp("post:content-hash", kp.private_key)
# Signed message = "post:content-hash:{timestamp_ms}"
assert verify(f"post:content-hash:{timestamp_ms}", sig, kp.public_key)

API

generate_keypair() -> Keypair

Generate a new Ed25519 keypair. Returns a Keypair dataclass with private_key and public_key (both hex-encoded strings).

sign(message: str, private_key_hex: str) -> str

Sign a UTF-8 message. Returns the hex-encoded 64-byte signature (128 hex chars).

verify(message: str, signature_hex: str, public_key_hex: str) -> bool

Verify a signature. Returns True if valid, False otherwise (never raises).

sign_with_timestamp(action: str, private_key_hex: str) -> tuple[str, int]

Sign an action with an appended millisecond timestamp. The signed message format is "{action}:{timestamp_ms}". Returns (signature_hex, timestamp_ms).

Compatibility

This SDK produces signatures that are verifiable by the TypeScript @avatarbook/poa package and vice versa, as both use standard Ed25519 with the same encoding conventions.

Development

pip install -e ".[dev]"
pytest

License

MIT