walley-sdk 0.1.0__py3-none-any.whl

walley/__init__.py

@@ -0,0 +1,88 @@
+from .client import Walley
+from .enums import (
+    PreapprovalStatus,
+    TransactionSource,
+    TransferStatus,
+    TxKind,
+    TxKindFilter,
+)
+from .errors import (
+    AuthError,
+    FeeDueError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    UnprocessableError,
+    ValidationError,
+    WalleyError,
+)
+from .models import (
+    ActiveContract,
+    Balance,
+    Fee,
+    FeeDue,
+    FreeSends,
+    Holding,
+    MergeDelegation,
+    MergeDelegationState,
+    MergeEvent,
+    Party,
+    PreparedSubmission,
+    PreparedTransaction,
+    SignedMessage,
+    SubmitResult,
+    SubmittedTransaction,
+    Token,
+    Transaction,
+    TransactionPage,
+    Transfer,
+    TransferEvent,
+    TransferPreapproval,
+    TransferPreapprovalState,
+)
+from .signer import Signer
+
+__all__ = [
+    "Walley",
+    "Signer",
+    # enums
+    "TransferStatus",
+    "TransactionSource",
+    "TxKind",
+    "TxKindFilter",
+    "PreapprovalStatus",
+    # models
+    "ActiveContract",
+    "Balance",
+    "Holding",
+    "Token",
+    "Party",
+    "Transfer",
+    "Transaction",
+    "TransactionPage",
+    "TransferEvent",
+    "MergeEvent",
+    "Fee",
+    "FeeDue",
+    "FreeSends",
+    "PreparedTransaction",
+    "PreparedSubmission",
+    "SubmittedTransaction",
+    "SubmitResult",
+    "SignedMessage",
+    "TransferPreapproval",
+    "TransferPreapprovalState",
+    "MergeDelegation",
+    "MergeDelegationState",
+    # errors
+    "WalleyError",
+    "AuthError",
+    "ValidationError",
+    "FeeDueError",
+    "UnprocessableError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]
+
+__version__ = "0.1.0"

walley/_transport.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import error_from_response
+
+# Response-envelope metadata flattened into every body by the server. Stripped
+# so payloads (e.g. Commands from /transfers/prepare) can be echoed back clean.
+ENVELOPE_KEYS = ("trace_id", "request_id", "timestamp")
+
+
+class Transport:
+    """Issues requests against a fixed base URL and returns the body.
+
+    Success bodies are flat: the payload fields sit at the top level next to
+    ``trace_id``/``request_id``/``timestamp``. Errors carry a ``message`` and
+    the HTTP status.
+    """
+
+    def __init__(self, client: httpx.Client, base_url: str) -> None:
+        self._client = client
+        self._base = base_url.rstrip("/")
+
+    @property
+    def base_url(self) -> str:
+        return self._base
+
+    def request(self, method: str, path: str, **kwargs: Any) -> dict:
+        response = self._client.request(method, self._base + path, **kwargs)
+        body = response.json() if response.content else {}
+        if response.status_code >= 400:
+            raise error_from_response(response.status_code, body)
+        return body
+
+    def get(self, path: str, **kwargs: Any) -> dict:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> dict:
+        return self.request("POST", path, **kwargs)
+
+
+def strip_envelope(body: dict) -> dict:
+    return {k: v for k, v in body.items() if k not in ENVELOPE_KEYS}

walley/auth.py

@@ -0,0 +1,115 @@
+"""Challenge/verify authentication.
+
+Read endpoints (balances, holdings, transaction history) require a bearer
+token. Walley issues one to whoever proves control of a party's signing key:
+
+1. ``POST /v1/auth/challenge`` → ``{nonce, expires_at, token}``.
+2. Sign the canonical message ``"{audience}|{origin}|{nonce}|{expires_at}"``
+   (UTF-8; the nonce is signed as its base64url string) with the party's
+   Ed25519 key. Must byte-match ``canonical_message`` in
+   ``vendor/sherpa-api/src/auth/crypto.rs``.
+3. ``POST /v1/auth/verify`` → ``{access_token, expires_at}``.
+
+The party id itself is not part of the signed message — the server binds the
+party via the key fingerprint (the party id's namespace).
+
+Prepare/submit endpoints don't need the bearer; they are guarded by the
+prepare token and the ledger's own signature check. The SDK still attaches
+it everywhere — it's harmless and keeps the client uniform.
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from typing import Generator
+
+import httpx
+
+from .errors import AuthError
+from .signer import Signer
+
+# Re-authenticate this many seconds before the token's stated expiry.
+_EXPIRY_SKEW_SECONDS = 30
+
+
+class ChallengeAuth(httpx.Auth):
+    """Proves key ownership via the challenge/verify flow, caches the issued
+    bearer token, and re-authenticates transparently on expiry or 401."""
+
+    requires_response_body = True
+
+    def __init__(
+        self,
+        *,
+        signer: Signer,
+        party_id: str,
+        challenge_url: str,
+        verify_url: str,
+        audience: str,
+        origin: str,
+    ) -> None:
+        self._signer = signer
+        self._party_id = party_id
+        self._challenge_url = challenge_url
+        self._verify_url = verify_url
+        self._audience = audience
+        self._origin = origin
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    def sync_auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        if not self._fresh():
+            yield from self._authenticate()
+        self._apply(request)
+        response = yield request
+        if response.status_code == 401:
+            yield from self._authenticate()
+            self._apply(request)
+            yield request
+
+    def _authenticate(self) -> Generator[httpx.Request, httpx.Response, None]:
+        response = yield httpx.Request("POST", self._challenge_url, json={})
+        response.read()
+        if response.status_code != 200:
+            raise AuthError("Auth challenge failed.", status=response.status_code)
+        challenge = response.json()
+
+        message = self.canonical_message(
+            self._audience, self._origin, challenge["nonce"], challenge["expires_at"]
+        )
+        signature = base64.b64encode(self._signer.sign(message)).decode()
+
+        response = yield httpx.Request(
+            "POST",
+            self._verify_url,
+            json={
+                "party_id": self._party_id,
+                "origin": self._origin,
+                "public_key": self._signer.public_key_base64,
+                "signature": signature,
+                "challenge": {
+                    "nonce": challenge["nonce"],
+                    "expires_at": challenge["expires_at"],
+                    "token": challenge["token"],
+                },
+            },
+        )
+        response.read()
+        if response.status_code != 200:
+            raise AuthError("Auth verify failed.", status=response.status_code)
+        body = response.json()
+        self._token = body["access_token"]
+        self._expires_at = float(body["expires_at"])
+
+    @staticmethod
+    def canonical_message(audience: str, origin: str, nonce: str, expires_at: int) -> bytes:
+        return f"{audience}|{origin}|{nonce}|{expires_at}".encode()
+
+    def _fresh(self) -> bool:
+        return self._token is not None and time.time() < self._expires_at - _EXPIRY_SKEW_SECONDS
+
+    def _apply(self, request: httpx.Request) -> None:
+        request.headers["Authorization"] = f"Bearer {self._token}"

walley/client.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import base64
+import os
+import re
+from typing import Optional, Union
+
+import httpx
+
+from ._transport import Transport
+from .auth import ChallengeAuth
+from .models import SignedMessage
+from .resources import (
+    Balances,
+    Fees,
+    Holdings,
+    Ledger,
+    MergeDelegations,
+    Party,
+    Tokens,
+    TransferPreapprovals,
+    Transactions,
+    Transfers,
+)
+from .signer import Signer
+
+DEFAULT_API_BASE = "https://api.walley.cc"
+DEFAULT_AUDIENCE = "https://walley.cc/dapp"
+DEFAULT_ORIGIN = "walley-python-sdk"
+
+_PARTY_HINT_RE = re.compile(r"^walley-[a-zA-Z0-9-]+$")
+_PARTY_ID_RE = re.compile(r"^[a-zA-Z0-9-]+::[0-9a-f]+$")
+
+
+class Walley:
+    """Synchronous Walley client, signed in to one existing self-custodied
+    party.
+
+    The client holds the party's Ed25519 key and does all signing locally —
+    the API only ever sees public keys and signatures. Reads authenticate
+    automatically via the challenge/verify flow; writes follow Canton's
+    external-signing dance (prepare → sign → submit) behind one method call.
+
+    Parties are created in the Walley app; sign in here with the wallet's
+    recovery mnemonic (or exported key).
+
+    Args:
+        key_file: Path to a key file — a PKCS#8 PEM or the 24-word recovery
+            mnemonic (format detected). The recommended option: key material
+            stays out of source code. Falls back to ``$WALLEY_KEY_FILE``.
+        mnemonic: Alternatively, the 24-word mnemonic inline. Falls back to
+            ``$WALLEY_MNEMONIC``.
+        private_key: Alternatively, the raw Ed25519 private key — bytes,
+            hex, base64, or PEM. Falls back to ``$WALLEY_PRIVATE_KEY``.
+        signer: Alternatively, a pre-built :class:`Signer`.
+        party_id: The full party id (``hint::fingerprint``). Falls back to
+            ``$WALLEY_PARTY_ID``. Must match the key's fingerprint.
+        party_hint: Or just the hint (``walley-...``) — the id is derived
+            from the key. Falls back to ``$WALLEY_PARTY_HINT``.
+        api_base: Walley API base URL. Falls back to ``$WALLEY_API_URL``,
+            then ``https://api.walley.cc``.
+        audience: Auth audience string; must match the deployment's
+            ``AUTH_PROVIDER__AUDIENCE``.
+        origin: Free-form caller identifier recorded in issued tokens.
+        timeout: Per-request timeout in seconds (submits use a longer one).
+        auto_settle_fees: Settle each deferred network fee immediately after
+            the transaction that incurred it (the settlement lands on the
+            result's ``fee_settlement``). Pass ``False`` to manage debts
+            yourself via ``client.fees`` — but note an unsettled debt blocks
+            the party's next prepare with :class:`FeeDueError`.
+
+    Example::
+
+        w = Walley(mnemonic="...", party_hint="walley-alice")
+        result = w.transfers.send(receiver="walley-bob::1220...", amount="5")
+        print(result.fee)          # the network fee this send incurred
+    """
+
+    def __init__(
+        self,
+        *,
+        key_file: Optional[str] = None,
+        mnemonic: Optional[str] = None,
+        private_key: Union[bytes, str, None] = None,
+        signer: Optional[Signer] = None,
+        party_id: Optional[str] = None,
+        party_hint: Optional[str] = None,
+        api_base: Optional[str] = None,
+        audience: str = DEFAULT_AUDIENCE,
+        origin: str = DEFAULT_ORIGIN,
+        timeout: float = 30.0,
+        auto_settle_fees: bool = True,
+    ) -> None:
+        self.signer = _resolve_signer(key_file, mnemonic, private_key, signer)
+        self.party_id = _resolve_party_id(self.signer, party_id, party_hint)
+        api_base = (api_base or os.environ.get("WALLEY_API_URL") or DEFAULT_API_BASE).rstrip("/")
+
+        auth = ChallengeAuth(
+            signer=self.signer,
+            party_id=self.party_id,
+            challenge_url=f"{api_base}/v1/auth/challenge",
+            verify_url=f"{api_base}/v1/auth/verify",
+            audience=audience,
+            origin=origin,
+        )
+        self._http = httpx.Client(auth=auth, timeout=timeout)
+        transport = Transport(self._http, api_base)
+
+        self.tokens = Tokens(transport)
+        self.transactions = Transactions(
+            transport, self.party_id, self.signer, auto_settle_fees=auto_settle_fees
+        )
+        self.transfers = Transfers(transport, self.party_id, self.transactions, self.tokens)
+        self.fees = Fees(transport, self.party_id, self.transactions)
+        self.balances = Balances(transport, self.party_id)
+        self.holdings = Holdings(transport, self.party_id)
+        self.party = Party(transport, self.party_id)
+        self.ledger = Ledger(transport, self.party_id)
+        self.preapprovals = TransferPreapprovals(transport, self.party_id, self.transactions)
+        self.merge_delegations = MergeDelegations(transport, self.party_id, self.transactions)
+
+    @property
+    def fingerprint(self) -> str:
+        """The signing key's Canton fingerprint (the party id's namespace)."""
+        return self.signer.fingerprint
+
+    def sign(self, message: Union[bytes, str]) -> SignedMessage:
+        """Sign an arbitrary message with the party's key.
+
+        Strings are signed as UTF-8. Returns a :class:`SignedMessage`
+        bundling the signature with the public key and fingerprint, so any
+        verifier can check it against the party id.
+        """
+        data = message.encode() if isinstance(message, str) else message
+        return SignedMessage(
+            signature=base64.b64encode(self.signer.sign(data)).decode(),
+            signed_by=self.signer.fingerprint,
+            public_key=self.signer.public_key_base64,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Walley":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Walley(party_id={self.party_id!r})"
+
+
+def _resolve_signer(
+    key_file: Optional[str],
+    mnemonic: Optional[str],
+    private_key: Union[bytes, str, None],
+    signer: Optional[Signer],
+) -> Signer:
+    if signer is not None:
+        return signer
+    key_file = key_file or os.environ.get("WALLEY_KEY_FILE")
+    if key_file:
+        return Signer.from_file(key_file)
+    mnemonic = mnemonic or os.environ.get("WALLEY_MNEMONIC")
+    if mnemonic:
+        return Signer.from_mnemonic(mnemonic)
+    private_key = private_key or os.environ.get("WALLEY_PRIVATE_KEY")
+    if private_key:
+        return Signer.from_private_key(private_key)
+    raise ValueError(
+        "a signing key is required — pass key_file=..., mnemonic=..., private_key=..., "
+        "or signer=... (or set WALLEY_KEY_FILE / WALLEY_MNEMONIC / WALLEY_PRIVATE_KEY)"
+    )
+
+
+def _resolve_party_id(
+    signer: Signer,
+    party_id: Optional[str],
+    party_hint: Optional[str],
+) -> str:
+    party_id = party_id or os.environ.get("WALLEY_PARTY_ID")
+    if party_id:
+        if not _PARTY_ID_RE.match(party_id):
+            raise ValueError(f"invalid party_id {party_id!r} (expected hint::fingerprint)")
+        namespace = party_id.rsplit("::", 1)[1]
+        if namespace.lower() != signer.fingerprint:
+            raise ValueError(
+                f"party_id namespace {namespace!r} does not match the signing key's "
+                f"fingerprint {signer.fingerprint!r} — wrong key for this party?"
+            )
+        return party_id
+    party_hint = party_hint or os.environ.get("WALLEY_PARTY_HINT")
+    if party_hint:
+        if not _PARTY_HINT_RE.match(party_hint) or not 8 <= len(party_hint) <= 64:
+            raise ValueError(
+                f"invalid party_hint {party_hint!r} (expected 'walley-' + 8-64 "
+                "alphanumeric/hyphen chars)"
+            )
+        return signer.party_id(party_hint)
+    raise ValueError(
+        "pass party_id=... or party_hint=... (or set WALLEY_PARTY_ID / WALLEY_PARTY_HINT)"
+    )
+
+
+__all__ = ["Walley", "DEFAULT_API_BASE", "DEFAULT_AUDIENCE", "DEFAULT_ORIGIN"]

walley/enums.py

@@ -0,0 +1,45 @@
+from enum import Enum
+
+
+class TransferStatus(str, Enum):
+    """Lifecycle of a transfer event in the transaction history."""
+
+    INITIATED = "INITIATED"
+    COMPLETED = "COMPLETED"
+    ACCEPTED = "ACCEPTED"
+    REJECTED = "REJECTED"
+    WITHDRAWN = "WITHDRAWN"
+
+
+class TransactionSource(str, Enum):
+    """Which app initiated a transaction (``WALLEY`` for a plain wallet send)."""
+
+    WALLEY = "WALLEY"
+    NEXODE = "NEXODE"
+    ATOMIX = "ATOMIX"
+    VAULT = "VAULT"
+    CANTORY = "CANTORY"
+
+
+class TxKind(str, Enum):
+    TRANSFER = "transfer"
+    FEE = "fee"
+
+
+class TxKindFilter(str, Enum):
+    """Filter for the transaction history: everything, only network-fee
+    transactions, or everything but fees."""
+
+    ALL = "all"
+    FEES = "fees"
+    NON_FEES = "non_fees"
+
+
+class PreapprovalStatus(str, Enum):
+    """State of a transfer preapproval or merge delegation. ``EXPIRED``
+    applies to transfer preapprovals only."""
+
+    ENABLED = "ENABLED"
+    PENDING = "PENDING"
+    NOT_ENABLED = "NOT_ENABLED"
+    EXPIRED = "EXPIRED"

walley/errors.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Type
+
+
+class WalleyError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        trace_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.trace_id = trace_id
+
+
+class AuthError(WalleyError):
+    """Invalid or expired credentials (401/403)."""
+
+
+class ValidationError(WalleyError):
+    """The request was malformed (400)."""
+
+
+class FeeDueError(WalleyError):
+    """The party owes an unpaid network fee (402). New transactions are
+    refused until it is settled — call ``client.fees.pay()``."""
+
+
+class UnprocessableError(WalleyError):
+    """A well-formed request rejected by a business rule — insufficient
+    funds, expired transfer, party quota exceeded, etc. (422)."""
+
+
+class NotFoundError(WalleyError):
+    """The resource does not exist (404)."""
+
+
+class RateLimitError(WalleyError):
+    """Too many requests (429)."""
+
+
+class ServerError(WalleyError):
+    """The server failed to handle the request (5xx)."""
+
+
+def error_from_response(status: int, body: Mapping[str, Any]) -> WalleyError:
+    match status:
+        case 400:
+            cls: Type[WalleyError] = ValidationError
+        case 401 | 403:
+            cls = AuthError
+        case 402:
+            cls = FeeDueError
+        case 404:
+            cls = NotFoundError
+        case 422:
+            cls = UnprocessableError
+        case 429:
+            cls = RateLimitError
+        case s if s >= 500:
+            cls = ServerError
+        case _:
+            cls = WalleyError
+    message = body.get("message") or f"HTTP {status}"
+    if cls is FeeDueError:
+        message += " Settle it with client.fees.pay(), then retry."
+    return cls(message, status=status, trace_id=body.get("trace_id"))

walley/models/__init__.py

@@ -0,0 +1,53 @@
+from .balance import Balance, Holding, Token
+from .fee import Fee, FeeDue, FreeSends
+from .ledger import ActiveContract
+from .party import Party
+from .preapproval import (
+    MergeDelegation,
+    MergeDelegationProposal,
+    MergeDelegationState,
+    TransferPreapproval,
+    TransferPreapprovalProposal,
+    TransferPreapprovalState,
+)
+from .prepared import (
+    PreparedSubmission,
+    PreparedTransaction,
+    SignedMessage,
+    SubmitResult,
+    SubmittedTransaction,
+)
+from .transaction import (
+    MergeEvent,
+    Transaction,
+    TransactionPage,
+    TransferEvent,
+)
+from .transfer import Transfer
+
+__all__ = [
+    "ActiveContract",
+    "Balance",
+    "Holding",
+    "Token",
+    "Party",
+    "Transfer",
+    "Transaction",
+    "TransactionPage",
+    "TransferEvent",
+    "MergeEvent",
+    "Fee",
+    "FeeDue",
+    "FreeSends",
+    "PreparedTransaction",
+    "PreparedSubmission",
+    "SubmittedTransaction",
+    "SubmitResult",
+    "SignedMessage",
+    "TransferPreapproval",
+    "TransferPreapprovalProposal",
+    "TransferPreapprovalState",
+    "MergeDelegation",
+    "MergeDelegationProposal",
+    "MergeDelegationState",
+]

walley/models/_base.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True)

walley/models/balance.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Optional
+
+from ._base import Model
+
+
+class Balance(Model):
+    """A party's aggregate position in one instrument."""
+
+    owner: str
+    instrument_id: str
+    instrument_admin_id: str
+    total_balance: Decimal
+    unlocked_balance: Decimal
+    locked_balance: Decimal
+    holding_count: int
+    usd_value: Optional[Decimal] = None
+
+
+class Holding(Model):
+    """A single on-ledger holding contract (a UTXO-like slice of a balance)."""
+
+    contract_id: str
+    owner: str
+    instrument_id: str
+    instrument_admin_id: str
+    amount: Decimal
+    is_locked: bool
+    lock_context: Optional[str] = None
+    lock_expires_at: Optional[str] = None
+    created_at: Optional[datetime] = None
+
+
+class Token(Model):
+    """An instrument known to the registry (e.g. ``Amulet`` — Canton Coin)."""
+
+    id: str
+    name: str
+    symbol: str
+    decimals: int
+    admin_id: str
+    operator_id: Optional[str] = None
+    total_supply: Optional[str] = None
+    total_supply_as_of: Optional[datetime] = None