foliant-protocol 0.1.0__py3-none-any.whl

foliant/__init__.py

@@ -0,0 +1,18 @@
+"""Foliant reference implementation (Python) — agent accounts, policies, channels, pools.
+
+Executable specification for whitepaper §6; the Cosmos SDK port follows these
+state machines one-to-one and reuses the tests in `tests/` as a conformance suite.
+"""
+from .accounts import AgentAccount, AgentSigner, Attestation, Policy
+from .agent import Agent
+from .channels import Channel
+from .crypto import KeyPair, PublicKey, Signed, sign
+from .ledger import Ledger
+from .market import Contribution, Receipt, ServiceOffer, royalty_split
+from .pools import Pool
+
+__all__ = [
+    "Agent", "AgentAccount", "AgentSigner", "Attestation", "Channel", "Contribution",
+    "KeyPair", "Ledger", "Policy", "Pool", "PublicKey", "Receipt", "ServiceOffer",
+    "Signed", "royalty_split", "sign",
+]

foliant/accounts.py

@@ -0,0 +1,232 @@
+"""Agent accounts, spending policies and attestation (whitepaper §6.1-6.3).
+
+An AgentAccount is operated by a `signer` key under a `Policy`. The policy is
+checked by the ledger (on-chain) for every value-moving transaction, and by
+the AgentSigner (the enclave side) for every off-chain channel or pool update.
+Both sides run the same `Policy.check`, so a signer that refuses to sign and a
+ledger that refuses to apply agree exactly.
+
+Accounts form a tree (whitepaper §6.2, hierarchical budgets). An account's
+signer may `delegate`: create a child account with its own signer and a policy
+that sits within the parent's (`Policy.within`). Value leaving the tree is
+checked against, and recorded in, every ancestor's policy and window, so no
+branch can ever commit more than any ancestor allows, whatever its own policy
+says. Moves inside the tree (delegating funds down, recalling them up) are not
+spends.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .crypto import KeyPair, PublicKey, Signed, hash_obj, sign
+from .errors import PolicyViolation
+
+
+@dataclass
+class Policy:
+    per_tx_max: int
+    per_window_max: int
+    window_secs: int
+    allow_list: Optional[frozenset[str]] = None  # payee addresses; None = any
+    deny_list: frozenset[str] = frozenset()
+    expiry: Optional[int] = None  # unix seconds; None = never
+    escalation: Optional[PublicKey] = None  # co-signer that may exceed per_tx_max
+
+    @property
+    def id(self) -> str:
+        return hash_obj(self.to_dict())
+
+    def to_dict(self) -> dict:
+        return {
+            "per_tx_max": self.per_tx_max,
+            "per_window_max": self.per_window_max,
+            "window_secs": self.window_secs,
+            "allow_list": sorted(self.allow_list) if self.allow_list is not None else None,
+            "deny_list": sorted(self.deny_list),
+            "expiry": self.expiry,
+            "escalation": self.escalation.to_dict() if self.escalation else None,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Policy":
+        return cls(
+            per_tx_max=d["per_tx_max"],
+            per_window_max=d["per_window_max"],
+            window_secs=d["window_secs"],
+            allow_list=frozenset(d["allow_list"]) if d.get("allow_list") is not None else None,
+            deny_list=frozenset(d.get("deny_list", [])),
+            expiry=d.get("expiry"),
+            escalation=PublicKey.from_dict(d["escalation"]) if d.get("escalation") else None,
+        )
+
+    def check(
+        self,
+        *,
+        amount: int,
+        payee: str,
+        now: int,
+        spent_in_window: int,
+        escalated: bool = False,
+    ) -> None:
+        """Raise PolicyViolation if a payment of `amount` to `payee` is not allowed."""
+        if amount < 0:
+            raise PolicyViolation("negative amount")
+        if self.expiry is not None and now >= self.expiry:
+            raise PolicyViolation("policy expired")
+        if payee in self.deny_list:
+            raise PolicyViolation(f"payee {payee} is denied")
+        if self.allow_list is not None and payee not in self.allow_list:
+            raise PolicyViolation(f"payee {payee} is not on the allow list")
+        if amount > self.per_tx_max and not escalated:
+            raise PolicyViolation(f"amount {amount} exceeds per_tx_max {self.per_tx_max}")
+        if spent_in_window + amount > self.per_window_max:
+            raise PolicyViolation(
+                f"amount {amount} would exceed per_window_max {self.per_window_max} "
+                f"(already spent {spent_in_window})"
+            )
+
+    def within(self, parent: "Policy") -> None:
+        """Raise PolicyViolation unless this policy is no wider than `parent` on every axis.
+
+        Runtime enforcement up the tree makes this a guarantee at delegation time
+        rather than the only line of defence: a child that somehow held a wider
+        policy would still be bounded by its ancestors at every spend.
+
+        Not compared, deliberately: `window_secs` (a child may meter over a shorter
+        window than its parent; the parent's window still binds the subtree) and
+        `escalation` (a child's co-signer lifts only the child's own per_tx_max;
+        see Ledger._authorise).
+        """
+        if self.per_tx_max > parent.per_tx_max:
+            raise PolicyViolation(f"child per_tx_max {self.per_tx_max} exceeds parent {parent.per_tx_max}")
+        if self.per_window_max > parent.per_window_max:
+            raise PolicyViolation(f"child per_window_max {self.per_window_max} exceeds parent {parent.per_window_max}")
+        if parent.allow_list is not None and (self.allow_list is None or not self.allow_list <= parent.allow_list):
+            raise PolicyViolation("child allow list must be a subset of the parent's")
+        if not parent.deny_list <= self.deny_list:
+            raise PolicyViolation("child deny list must include the parent's")
+        if parent.expiry is not None and (self.expiry is None or self.expiry > parent.expiry):
+            raise PolicyViolation("child expiry must not be later than the parent's")
+
+
+@dataclass(frozen=True)
+class Attestation:
+    """A remote-attestation quote binding `signer` to `code_hash`, signed by a vendor key.
+
+    Simulated: the vendor is any key the ledger has registered as a trusted
+    attestation root. Real quotes (TDX, SEV-SNP, Nitro) are verified by a
+    precompile; the shape is the same.
+    """
+
+    code_hash: str
+    signer: PublicKey
+    quote: Signed
+
+    @staticmethod
+    def issue(vendor: KeyPair, code_hash: str, signer: PublicKey) -> "Attestation":
+        body = {"code_hash": code_hash, "signer": signer.to_dict()}
+        return Attestation(code_hash, signer, sign(vendor, body))
+
+    def valid_for(self, trusted_vendors: set[str]) -> bool:
+        return (
+            self.quote.valid()
+            and self.quote.signer.hex in trusted_vendors
+            and self.quote.body == {"code_hash": self.code_hash, "signer": self.signer.to_dict()}
+        )
+
+
+@dataclass
+class SpendWindow:
+    """Rolling record of value the account has committed, for per_window_max."""
+
+    entries: list[tuple[int, int]] = field(default_factory=list)  # (ts, amount)
+
+    def spent(self, now: int, window_secs: int) -> int:
+        cutoff = now - window_secs
+        self.entries = [(t, a) for t, a in self.entries if t > cutoff]
+        return sum(a for _, a in self.entries)
+
+    def record(self, now: int, amount: int) -> None:
+        self.entries.append((now, amount))
+
+
+@dataclass
+class AgentAccount:
+    id: str
+    owner: PublicKey
+    signer: PublicKey
+    policy: Policy
+    attestation: Optional[Attestation] = None
+    nonce: int = 0
+    window: SpendWindow = field(default_factory=SpendWindow)
+    parent: Optional[str] = None  # account id this one was delegated from; None = root
+
+    @staticmethod
+    def make_id(owner: PublicKey, signer: PublicKey, nonce_salt: int) -> str:
+        return hash_obj({"owner": owner.to_dict(), "signer": signer.to_dict(), "salt": nonce_salt})
+
+    @staticmethod
+    def make_child_id(parent_id: str, signer: PublicKey, nonce_salt: int) -> str:
+        return hash_obj({"parent": parent_id, "signer": signer.to_dict(), "salt": nonce_salt})
+
+    @property
+    def address(self) -> str:
+        """Where the account's funds sit on the ledger."""
+        return f"account:{self.id}"
+
+    def authorise(self, *, amount: int, payee: str, now: int, escalated: bool = False) -> None:
+        """Policy check then record the spend. Raises PolicyViolation without recording."""
+        spent = self.window.spent(now, self.policy.window_secs)
+        self.policy.check(
+            amount=amount, payee=payee, now=now, spent_in_window=spent, escalated=escalated
+        )
+        self.window.record(now, amount)
+
+
+class AgentSigner:
+    """The enclave side: holds the signer key and refuses to sign anything the policy forbids.
+
+    It keeps its own SpendWindow so per_window_max holds across off-chain updates
+    that the ledger never sees individually.
+    """
+
+    def __init__(self, keypair: KeyPair, policy: Policy, account_id: str):
+        self.keypair = keypair
+        self.policy = policy
+        self.account_id = account_id
+        self.window = SpendWindow()
+        self._last_balance: dict[str, int] = {}  # channel/pool id -> last signed balance
+
+    @property
+    def public(self) -> PublicKey:
+        return self.keypair.public
+
+    def sign_payment(self, *, payee: str, amount: int, now: int, body: dict, escalated: bool = False) -> Signed:
+        """Sign `body` if committing `amount` to `payee` is within policy."""
+        spent = self.window.spent(now, self.policy.window_secs)
+        self.policy.check(amount=amount, payee=payee, now=now, spent_in_window=spent, escalated=escalated)
+        self.window.record(now, amount)
+        return sign(self.keypair, body)
+
+    def sign_update(self, *, kind: str, obj_id: str, payee: str, seq: int, balance: int, now: int) -> Signed:
+        """Sign a channel or pool update.
+
+        The policy bounds *committed* value: the deposit was authorised when the
+        channel or pool was funded, and every update is bounded by that deposit,
+        so an update is not a new spend. The signer still enforces the payee
+        allow/deny lists, expiry, and monotonic balances.
+        """
+        last = self._last_balance.get(obj_id, 0)
+        if balance < last:
+            raise PolicyViolation("balance must not decrease")
+        spent = self.window.spent(now, self.policy.window_secs)
+        self.policy.check(amount=0, payee=payee, now=now, spent_in_window=spent)
+        body = {"kind": kind, "id": obj_id, "seq": seq, "balance": balance, "account": self.account_id}
+        signed = sign(self.keypair, body)
+        self._last_balance[obj_id] = balance
+        return signed
+
+    def sign_plain(self, body: dict) -> Signed:
+        """Sign a non-payment message (account maintenance, exits, receipts)."""
+        return sign(self.keypair, body)

foliant/agent.py

@@ -0,0 +1,139 @@
+"""Agent-side convenience: builds envelopes and off-chain updates for one account.
+
+This is what an agent SDK wraps. The signer runs the same policy as the ledger,
+so a payment the enclave refuses to sign is one the chain would have rejected.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .accounts import AgentAccount, AgentSigner, Attestation, Policy
+from .crypto import KeyPair, Signed, sign
+from .ledger import Ledger
+
+
+class Agent:
+    def __init__(self, ledger: Ledger, owner: KeyPair, signer_kp: KeyPair, policy: Policy,
+                 attestation: Optional[Attestation] = None, salt: int = 0):
+        self.ledger = ledger
+        self.owner = owner
+        reg = sign(owner, {"op": "register", "signer": signer_kp.public.to_dict(), "policy_id": policy.id, "salt": salt})
+        self.account = ledger.register_account(reg, signer=signer_kp.public, policy=policy, attestation=attestation, salt=salt)
+        self.signer = AgentSigner(signer_kp, policy, self.account.id)
+        self._channel_seq: dict[str, int] = {}
+        self._pool_seq: dict[str, int] = {}
+        self.latest: dict[str, Signed] = {}  # obj id -> last update we signed
+
+    # --- envelopes (on-chain) --------------------------------------------
+
+    def _env(self, op: str, **params) -> Signed:
+        body = {"account": self.account.id, "nonce": self.account.nonce, "op": op, **params}
+        return self.signer.sign_plain(body)
+
+    def submit(self, op: str, escalate_with: Optional[KeyPair] = None, *,
+               spend: int = 0, payee_addr: str = "", **params) -> dict:
+        """Sign and apply an envelope. Value-moving ops pass `spend`/`payee_addr` so the
+        signer runs the same policy check the ledger will run."""
+        body = {"account": self.account.id, "nonce": self.account.nonce, "op": op, **params}
+        snapshot = list(self.signer.window.entries)
+        if spend or payee_addr:
+            env = self.signer.sign_payment(payee=payee_addr, amount=spend, now=self.ledger.now, body=body,
+                                           escalated=escalate_with is not None)
+        else:
+            env = self.signer.sign_plain(body)
+        esc = sign(escalate_with, env.body) if escalate_with else None
+        try:
+            return self.ledger.apply(env, esc)
+        except Exception:
+            # the ledger refused (an ancestor's policy, funds, a duplicate): the signer's
+            # window must not keep a spend that never happened, or it diverges from the ledger
+            self.signer.window.entries = snapshot
+            raise
+
+    # --- the tree -----------------------------------------------------------
+
+    def delegate(self, signer_kp: KeyPair, policy: Policy, *, fund: int = 0, asset: str = "", salt: int = 0) -> "Agent":
+        """Create a child account operated by `signer_kp` under `policy` (which must sit
+        within this account's), fund it, and return an Agent for it."""
+        res = self.submit("delegate", signer=signer_kp.public.to_dict(), policy=policy.to_dict(),
+                          fund=fund, asset=asset, salt=salt)
+        child = self.ledger.accounts[res["account_id"]]
+        return Agent.attach(self.ledger, child, signer_kp, owner=self.owner)
+
+    def recall(self, child: "Agent", asset: str, amount: Optional[int] = None) -> dict:
+        return self.submit("recall", child=child.account.id, asset=asset, amount=amount)
+
+    def set_child_policy(self, child: "Agent", policy: Policy) -> dict:
+        """An ancestor's signer sets a descendant's policy; the child's signer must be told."""
+        body = {"account": child.account.id, "nonce": child.account.nonce, "op": "set_policy", "policy": policy.to_dict()}
+        res = self.ledger.apply(self.signer.sign_plain(body))
+        child.signer.policy = policy
+        return res
+
+    @classmethod
+    def attach(cls, ledger: Ledger, account: AgentAccount, signer_kp: KeyPair, *, owner: KeyPair) -> "Agent":
+        """An Agent object for an account that already exists on the ledger."""
+        self = cls.__new__(cls)
+        self.ledger, self.owner, self.account = ledger, owner, account
+        self.signer = AgentSigner(signer_kp, account.policy, account.id)
+        self._channel_seq, self._pool_seq, self.latest = {}, {}, {}
+        return self
+
+    def transfer(self, to: str, asset: str, amount: int, **kw) -> dict:
+        return self.submit("transfer", spend=amount, payee_addr=to, to=to, asset=asset, amount=amount, **kw)
+
+    def open_channel(self, payee: str, asset: str, deposit: int, timeout_secs: int = 3600, salt: int = 0, **kw) -> str:
+        return self.submit("open_channel", spend=deposit, payee_addr=payee, payee=payee, asset=asset, deposit=deposit,
+                           timeout_secs=timeout_secs, salt=salt, **kw)["channel_id"]
+
+    def close_channel(self, channel_id: str) -> dict:
+        latest = self.latest.get(channel_id)
+        return self.submit("close_channel", channel_id=channel_id, latest=latest.to_dict() if latest else None)
+
+    def finalize_close(self, channel_id: str) -> dict:
+        return self.submit("finalize_close", channel_id=channel_id)
+
+    def join_pool(self, pool_id: str, deposit: int, **kw) -> dict:
+        coordinator = self.ledger.pools[pool_id].coordinator
+        return self.submit("join_pool", spend=deposit, payee_addr=coordinator, pool_id=pool_id, deposit=deposit, **kw)
+
+    def begin_exit(self, pool_id: str) -> dict:
+        latest = self.latest.get(pool_id)
+        return self.submit("begin_exit", pool_id=pool_id, latest=latest.to_dict() if latest else None)
+
+    def finalize_exit(self, pool_id: str) -> dict:
+        return self.submit("finalize_exit", pool_id=pool_id)
+
+    # --- off-chain updates -----------------------------------------------
+
+    def pay_channel(self, channel_id: str, amount: int) -> Signed:
+        """Sign the next channel update adding `amount` for the payee."""
+        ch = self.ledger.channels[channel_id]
+        seq = self._channel_seq.get(channel_id, ch.seq) + 1
+        balance = (self.latest[channel_id].body["balance"] if channel_id in self.latest else ch.balance_to_payee) + amount
+        if balance > ch.deposit:
+            raise ValueError("channel deposit exhausted")
+        u = self.signer.sign_update(kind="channel", obj_id=channel_id, payee=ch.payee, seq=seq, balance=balance, now=self.ledger.now)
+        self._channel_seq[channel_id] = seq
+        self.latest[channel_id] = u
+        return u
+
+    def pay_pool(self, pool_id: str, amount: int) -> Signed:
+        pool = self.ledger.pools[pool_id]
+        claim = pool.members[self.account.id]
+        seq = self._pool_seq.get(pool_id, claim.seq) + 1
+        balance = (self.latest[pool_id].body["balance"] if pool_id in self.latest else claim.paid) + amount
+        if balance > claim.deposit:
+            raise ValueError("pool deposit exhausted")
+        u = self.signer.sign_update(kind="pool", obj_id=pool_id, payee=pool.coordinator, seq=seq, balance=balance, now=self.ledger.now)
+        self._pool_seq[pool_id] = seq
+        self.latest[pool_id] = u
+        return u
+
+    def start_stream(self, channel_id: str, rate_per_sec: int) -> Signed:
+        ch = self.ledger.channels[channel_id]
+        # the deposit was authorised at open; a stream only schedules it
+        body = {"kind": "stream", "id": channel_id, "account": self.account.id, "rate": rate_per_sec, "start": self.ledger.now}
+        s = self.signer.sign_payment(payee=ch.payee, amount=0, now=self.ledger.now, body=body)
+        self.ledger.start_stream(channel_id, s)
+        return s

foliant/channels.py

@@ -0,0 +1,149 @@
+"""Payment channels and streams (whitepaper §6.4, §6.6).
+
+A channel escrows `deposit` from a payer account for one payee. Off-chain the
+payer signs updates (channel_id, seq, balance) with balance monotonically
+increasing. The payee settles by submitting the latest update at any time;
+the payer closes by submitting its latest update and waiting `timeout_secs`
+for the payee to submit a higher one.
+
+State machines here are pure: methods validate and return Transfer effects;
+the Ledger executes them.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .crypto import PublicKey, Signed, hash_obj
+from .errors import InvalidSignatureError, InvalidUpdate, Unauthorized
+
+
+@dataclass(frozen=True)
+class Transfer:
+    src: str  # address, or "escrow:<obj id>"
+    dst: str
+    asset: str
+    amount: int
+
+
+def verify_update(signed: Signed, *, kind: str, obj_id: str, account_id: str, signer: PublicKey) -> tuple[int, int]:
+    """Check an update's signature and shape; return (seq, balance)."""
+    if not signed.valid():
+        raise InvalidSignatureError("bad signature on update")
+    if signed.signer != signer:
+        raise Unauthorized("update not signed by the account's current signer")
+    b = signed.body
+    if b.get("kind") != kind or b.get("id") != obj_id or b.get("account") != account_id:
+        raise InvalidUpdate("update is for a different object or account")
+    seq, balance = b["seq"], b["balance"]
+    if not (isinstance(seq, int) and isinstance(balance, int)) or seq < 0 or balance < 0:
+        raise InvalidUpdate("seq and balance must be non-negative integers")
+    return seq, balance
+
+
+@dataclass
+class Channel:
+    id: str
+    payer_account: str
+    payee: str  # address
+    asset: str
+    deposit: int
+    timeout_secs: int
+    balance_to_payee: int = 0  # settled so far
+    seq: int = 0  # seq of the last update applied on-chain
+    closing_at: Optional[int] = None
+    closed: bool = False
+    # streaming: a signed (rate, start) lets the payee claim rate*(now-start)
+    stream: Optional[dict] = field(default=None)
+
+    @staticmethod
+    def make_id(payer_account: str, payee: str, salt: int) -> str:
+        return hash_obj({"payer": payer_account, "payee": payee, "salt": salt})
+
+    @property
+    def escrow(self) -> str:
+        return f"escrow:{self.id}"
+
+    def _apply_balance(self, seq: int, balance: int) -> list[Transfer]:
+        if self.closed:
+            raise InvalidUpdate("channel is closed")
+        if seq <= self.seq:
+            raise InvalidUpdate(f"seq {seq} not greater than last applied {self.seq}")
+        if balance < self.balance_to_payee:
+            raise InvalidUpdate("balance may not decrease")
+        if balance > self.deposit:
+            raise InvalidUpdate(f"balance {balance} exceeds deposit {self.deposit}")
+        delta = balance - self.balance_to_payee
+        self.seq, self.balance_to_payee = seq, balance
+        return [Transfer(self.escrow, self.payee, self.asset, delta)] if delta else []
+
+    def settle(self, update: Signed, *, account_id: str, signer: PublicKey) -> list[Transfer]:
+        """Payee (or anyone) submits a payer-signed update; pays out the delta."""
+        seq, balance = verify_update(update, kind="channel", obj_id=self.id, account_id=account_id, signer=signer)
+        return self._apply_balance(seq, balance)
+
+    def begin_close(self, now: int, latest: Optional[Signed], *, account_id: str, signer: PublicKey) -> list[Transfer]:
+        """Payer starts closing with its latest update (or none). Payee has `timeout_secs` to top it."""
+        if self.closed:
+            raise InvalidUpdate("channel is closed")
+        effects: list[Transfer] = []
+        if latest is not None:
+            seq, balance = verify_update(latest, kind="channel", obj_id=self.id, account_id=account_id, signer=signer)
+            if seq > self.seq:
+                effects = self._apply_balance(seq, balance)
+        if self.closing_at is None:
+            self.closing_at = now + self.timeout_secs
+        return effects
+
+    def finalize_close(self, now: int) -> list[Transfer]:
+        """After the timeout, return the unspent deposit to the payer."""
+        if self.closed:
+            raise InvalidUpdate("channel is closed")
+        if self.closing_at is None or now < self.closing_at:
+            raise InvalidUpdate("close timeout has not elapsed")
+        effects = self.claim_stream(now)
+        remaining = self.deposit - self.balance_to_payee
+        self.closed = True
+        if remaining:
+            effects.append(Transfer(self.escrow, f"account:{self.payer_account}", self.asset, remaining))
+        return effects
+
+    # --- streaming -------------------------------------------------------
+
+    def start_stream(self, signed: Signed, *, account_id: str, signer: PublicKey) -> None:
+        """Payer signs (rate_per_sec, start_ts); claimable grows with time until stopped."""
+        if not signed.valid() or signed.signer != signer:
+            raise InvalidSignatureError("bad stream signature")
+        b = signed.body
+        if b.get("kind") != "stream" or b.get("id") != self.id or b.get("account") != account_id:
+            raise InvalidUpdate("stream is for a different channel")
+        if self.stream is not None:
+            raise InvalidUpdate("stream already running")
+        self.stream = {"rate": int(b["rate"]), "start": int(b["start"]), "stopped": None}
+
+    def stop_stream(self, now: int) -> None:
+        if self.stream and self.stream["stopped"] is None:
+            self.stream["stopped"] = now
+
+    def stream_claimable(self, now: int) -> int:
+        if not self.stream:
+            return 0
+        end = self.stream["stopped"] if self.stream["stopped"] is not None else now
+        elapsed = max(0, end - self.stream["start"])
+        return min(self.deposit, self.balance_to_payee + self.stream["rate"] * elapsed)
+
+    def claim_stream(self, now: int) -> list[Transfer]:
+        """Pay out whatever the stream has accrued; folds it into balance_to_payee."""
+        if not self.stream:
+            return []
+        target = self.stream_claimable(now)
+        delta = target - self.balance_to_payee
+        if delta <= 0:
+            return []
+        # streams settle by time, not seq; keep seq unchanged
+        self.balance_to_payee = target
+        if self.stream["stopped"] is not None:
+            self.stream = None
+        else:
+            self.stream["start"] = now  # restart accrual from the claim point
+        return [Transfer(self.escrow, self.payee, self.asset, delta)]

foliant/crypto.py

@@ -0,0 +1,111 @@
+"""Keys, signatures and canonical hashing.
+
+Ed25519 stands in for the production scheme. Whitepaper principle 9 requires
+signature agility, so every signed message carries a `scheme` tag and the
+verifier dispatches on it; only "ed25519" is implemented here.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.exceptions import InvalidSignature
+
+SCHEME = "ed25519"
+
+
+def canonical(obj: Any) -> bytes:
+    """Deterministic JSON encoding used for every signed or hashed message."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+
+
+def sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def hash_obj(obj: Any) -> str:
+    return sha256(canonical(obj))
+
+
+@dataclass(frozen=True)
+class PublicKey:
+    scheme: str
+    raw: bytes
+
+    @property
+    def hex(self) -> str:
+        return self.raw.hex()
+
+    @property
+    def address(self) -> str:
+        """Address = first 20 bytes of sha256(scheme || pubkey)."""
+        return sha256(self.scheme.encode() + self.raw)[:40]
+
+    def verify(self, message: bytes, signature: bytes) -> bool:
+        if self.scheme != SCHEME:
+            raise ValueError(f"unsupported scheme {self.scheme}")
+        try:
+            Ed25519PublicKey.from_public_bytes(self.raw).verify(signature, message)
+            return True
+        except InvalidSignature:
+            return False
+
+    def to_dict(self) -> dict:
+        return {"scheme": self.scheme, "key": self.hex}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "PublicKey":
+        return cls(d["scheme"], bytes.fromhex(d["key"]))
+
+
+class KeyPair:
+    def __init__(self, private: Ed25519PrivateKey | None = None):
+        self._priv = private or Ed25519PrivateKey.generate()
+        raw = self._priv.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw
+        )
+        self.public = PublicKey(SCHEME, raw)
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> "KeyPair":
+        return cls(Ed25519PrivateKey.from_private_bytes(hashlib.sha256(seed).digest()))
+
+    @property
+    def address(self) -> str:
+        return self.public.address
+
+    def sign(self, message: bytes) -> bytes:
+        return self._priv.sign(message)
+
+    def sign_obj(self, obj: Any) -> str:
+        return self.sign(canonical(obj)).hex()
+
+
+@dataclass(frozen=True)
+class Signed:
+    """A message plus one signature. `body` must be JSON-serialisable."""
+
+    body: dict
+    signer: PublicKey
+    signature: str
+
+    def valid(self) -> bool:
+        return self.signer.verify(canonical(self.body), bytes.fromhex(self.signature))
+
+    def to_dict(self) -> dict:
+        return {"body": self.body, "signer": self.signer.to_dict(), "signature": self.signature}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Signed":
+        return cls(d["body"], PublicKey.from_dict(d["signer"]), d["signature"])
+
+
+def sign(kp: KeyPair, body: dict) -> Signed:
+    return Signed(body, kp.public, kp.sign_obj(body))

foliant/errors.py

@@ -0,0 +1,26 @@
+class FoliantError(Exception):
+    """Base for all protocol rejections. The message is the reason a transaction fails."""
+
+
+class PolicyViolation(FoliantError):
+    pass
+
+
+class InvalidSignatureError(FoliantError):
+    pass
+
+
+class InvalidUpdate(FoliantError):
+    pass
+
+
+class InsufficientFunds(FoliantError):
+    pass
+
+
+class NotFound(FoliantError):
+    pass
+
+
+class Unauthorized(FoliantError):
+    pass