Python SDK¶

The Python SDK is the primary interface for PrimeStamp. It provides the StampEngine for creating and verifying stamps, cryptographic primitives, fingerprinting algorithms, and a plugin system for storage and anchoring backends.

Installation¶

# Core only
pip install primestamp

# With all optional dependencies
pip install primestamp[all]

# Specific extras
pip install primestamp[api]       # FastAPI server
pip install primestamp[auth]      # JWT/OAuth2
pip install primestamp[dev]       # Development tools

Core Usage¶

Key Pair Generation¶

from primestamp.core.crypto import KeyPair

# Generate a new Ed25519 key pair
keys = KeyPair.generate()

# Export keys
private_key_bytes = keys.private_key
public_key_hex = keys.public_key_hex

# Load from existing key
keys = KeyPair(private_key=private_key_bytes)

Creating Stamps¶

from primestamp.core.engine import StampEngine
from primestamp.core.crypto import KeyPair

keys = KeyPair.generate()
engine = StampEngine(keys)

# Stamp content with a preset
with open("document.pdf", "rb") as f:
    content = f.read()

stamp = engine.create_stamp(content, preset="standard")
print(f"Stamp ID: {stamp.stamp_id}")
print(f"Content hash: {stamp.content_hash}")
print(f"Merkle root: {stamp.merkle_root}")
print(f"Timestamp: {stamp.timestamp}")

Verifying Stamps¶

result = engine.verify_stamp(stamp, content)
print(f"Valid: {result.valid}")
print(f"Trust score: {result.trust_score}")

Signing Stamps¶

signed_stamp = engine.sign_stamp(stamp)
print(f"Signature: {signed_stamp.signature}")

Presets¶

Preset	Storage	Encryption	Anchors	Trust Threshold
`casual`	Local	None	None	0
`standard`	Local + IPFS	AES-256-GCM	Ethereum, RFC 3161	4
`archival`	IPFS + Arweave	AES-256-GCM	Bitcoin, Ethereum, RFC 3161	8
`maximum`	All backends	ChaCha20-Poly1305	All anchors	12

Fingerprinting¶

from primestamp.fingerprint.prime_space import FingerprintGenerator

gen = FingerprintGenerator()
fingerprint = gen.generate(content)

# Compare two fingerprints
similarity = fingerprint.compare(other_fingerprint)

Hashing¶

from primestamp.core.crypto import compute_hash_hex

# SHA3-256 (default)
hash_hex = compute_hash_hex(content, algorithm="sha3-256")

# BLAKE3
hash_hex = compute_hash_hex(content, algorithm="blake3")

# SHA-256
hash_hex = compute_hash_hex(content, algorithm="sha256")

Encryption¶

# Encrypt stamp content
encrypted_stamp = engine.encrypt_stamp(stamp, password="secret")

# Decrypt
decrypted_stamp = engine.decrypt_stamp(encrypted_stamp, password="secret")

Async Support¶

All engine methods have async equivalents for use with asyncio.

import asyncio
from primestamp.core.engine import StampEngine

async def main():
    engine = StampEngine(keys)
    stamp = await engine.acreate_stamp(content, preset="archival")
    result = await engine.averify_stamp(stamp, content)

asyncio.run(main())

REST API Client¶

import httpx

async with httpx.AsyncClient(base_url="http://localhost:8800") as client:
    resp = await client.post("/v1/stamps", json={
        "content_hash": "sha3-256:abc123...",
        "preset": "standard",
    }, headers={"Authorization": "Bearer YOUR_API_KEY"})
    stamp = resp.json()

Configuration¶

Configure defaults via environment variables or primestamp.toml.

Variable	Description
`PRIMESTAMP_PRIVATE_KEY`	Ed25519 private key (base64).
`PRIMESTAMP_PRESET`	Default preset.
`PRIMESTAMP_STORAGE`	Default storage backend.
`PRIMESTAMP_API_URL`	API server URL.

Plugin System

Extend PrimeStamp with custom storage, anchor, and fingerprint plugins. See the plugin documentation for details on implementing the StoragePlugin, AnchorPlugin, and FingerprintPlugin base classes.