walley-sdk 0.1.0__tar.gz

walley_sdk-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/

walley_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: walley-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Walley wallet API on Canton Network
+Project-URL: Homepage, https://walley.cc
+Project-URL: Documentation, https://docs.walley.cc
+Project-URL: Source, https://github.com/k2flabs/walley
+Author: Walley
+License-Expression: MIT
+Keywords: canton,cip-56,sdk,wallet,walley
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: mnemonic>=0.20
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# walley-sdk
+
+Official Python SDK for [Walley](https://walley.cc) — programmatic
+self-custody of CIP-56 tokens on Canton Network. Your process holds the
+wallet's key, signs locally, and submits transactions; the API only ever
+sees public keys and signatures.
+
+```bash
+pip install walley-sdk
+```
+
+```python
+from walley import Walley
+
+w = Walley(
+    key_file="~/.config/walley/alice.key",   # PEM or 24-word mnemonic file
+    party_hint="walley-alice",
+)
+
+for balance in w.balances:
+    print(balance.instrument_id, balance.total_balance)
+
+result = w.transactions.execute(commands)   # your dapp's own ledger commands
+result = w.transfers.send(receiver="walley-bob::1220...", amount="5")
+print(result.update_id, result.fee)
+```
+
+**Full documentation: [docs.walley.cc/python-sdk](https://docs.walley.cc/python-sdk/overview)** —
+quickstart, keys & authentication, transactions & the fee model, wallet
+operations, and ledger reads.
+
+## Development
+
+```bash
+cd walley-sdk
+pip install -e '.[dev]'
+pytest
+```

walley_sdk-0.1.0/README.md

@@ -0,0 +1,38 @@
+# walley-sdk
+
+Official Python SDK for [Walley](https://walley.cc) — programmatic
+self-custody of CIP-56 tokens on Canton Network. Your process holds the
+wallet's key, signs locally, and submits transactions; the API only ever
+sees public keys and signatures.
+
+```bash
+pip install walley-sdk
+```
+
+```python
+from walley import Walley
+
+w = Walley(
+    key_file="~/.config/walley/alice.key",   # PEM or 24-word mnemonic file
+    party_hint="walley-alice",
+)
+
+for balance in w.balances:
+    print(balance.instrument_id, balance.total_balance)
+
+result = w.transactions.execute(commands)   # your dapp's own ledger commands
+result = w.transfers.send(receiver="walley-bob::1220...", amount="5")
+print(result.update_id, result.fee)
+```
+
+**Full documentation: [docs.walley.cc/python-sdk](https://docs.walley.cc/python-sdk/overview)** —
+quickstart, keys & authentication, transactions & the fee model, wallet
+operations, and ledger reads.
+
+## Development
+
+```bash
+cd walley-sdk
+pip install -e '.[dev]'
+pytest
+```

walley_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "walley-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Walley wallet API on Canton Network"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Walley" }]
+keywords = ["walley", "canton", "wallet", "cip-56", "sdk"]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "cryptography>=42",
+    "mnemonic>=0.20",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+]
+
+[project.urls]
+Homepage = "https://walley.cc"
+Documentation = "https://docs.walley.cc"
+Source = "https://github.com/k2flabs/walley"
+
+# Import package is `walley` (PyPI distribution is `walley-sdk`):
+#   pip install walley-sdk  ->  from walley import Walley
+[tool.hatch.build.targets.wheel]
+packages = ["src/walley"]
+
+# Published artifacts carry only the SDK itself.
+[tool.hatch.build.targets.sdist]
+include = ["src/walley", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

walley_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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"