"""Chainvara server SDK for Python — https://www.chainvara.com/docs

One file, standard library only (Python 3.9+). Server side only: never ship a secret API key to a browser or an app.

    from chainvara import Chainvara
    cv = Chainvara("fos_test_…")
    wallet = cv.wallets.create(network="base-sepolia", label="Treasury")
    transfer = cv.transfers.create(wallet_id=wallet["id"], asset="ETH", amount="0.01", destination="0x…")
    cv.transfers.wait(transfer["id"])

Webhooks and the API co-signer:

    event = verify_webhook(raw_body, request.headers["fos-signature"], WEBHOOK_SECRET)
    req = verify_cosigner_request(raw_body, request.headers["fos-signature"], COSIGNER_SECRET)
    body, headers = cosigner_response(req, "approve", COSIGNER_SECRET)
"""

from __future__ import annotations

import hashlib
import hmac
import json
import random
import re
import time
import uuid
from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Tuple
from urllib import error as urlerror
from urllib import parse, request as urlrequest

__all__ = [
    "Chainvara", "ChainvaraError", "FINAL_TRANSFER_STATUSES", "verify_webhook", "sign_webhook_payload",
    "verify_cosigner_request", "cosigner_response",
]
__version__ = "0.1.0"

FINAL_TRANSFER_STATUSES = ("confirmed", "failed", "rejected", "blocked", "canceled", "expired")
_KEY_RE = re.compile(r"^fos_(test|live)_[0-9a-f]{12}_[0-9a-f]{64}$")

Json = Dict[str, Any]


class ChainvaraError(Exception):
    """API or transport error. `status` is the HTTP status (0 for network errors), `code` a stable machine code."""

    def __init__(self, message: str, status: int, type: str, code: str, request_id: Optional[str]):
        super().__init__(message)
        self.message = message
        self.status = status
        self.type = type
        self.code = code
        self.request_id = request_id

    def __repr__(self) -> str:
        return f"ChainvaraError(status={self.status}, code={self.code!r}, message={self.message!r}, request_id={self.request_id!r})"


# Transport: (method, url, headers, body bytes or None, timeout seconds) -> (status, headers, body bytes).
Transport = Callable[[str, str, Mapping[str, str], Optional[bytes], float], Tuple[int, Mapping[str, str], bytes]]


def _urllib_transport(method: str, url: str, headers: Mapping[str, str], body: Optional[bytes], timeout: float) -> Tuple[int, Mapping[str, str], bytes]:
    req = urlrequest.Request(url, data=body, method=method, headers=dict(headers))
    try:
        with urlrequest.urlopen(req, timeout=timeout) as res:  # noqa: S310 (URL built by the client from base_url)
            return res.status, {k.lower(): v for k, v in res.headers.items()}, res.read()
    except urlerror.HTTPError as e:
        return e.code, {k.lower(): v for k, v in (e.headers or {}).items()}, e.read() or b""


class Chainvara:
    """Client for the Chainvara REST API (/api/v1). Every POST carries an Idempotency-Key, so retries never act twice."""

    def __init__(self, api_key: str, *, base_url: str = "https://www.chainvara.com", max_retries: int = 2, timeout: float = 30.0, transport: Optional[Transport] = None):
        m = _KEY_RE.match(api_key or "")
        if not m:
            raise ValueError("Chainvara: invalid API key. Expected fos_test_… or fos_live_… (create one in Developers).")
        self.mode = m.group(1)
        self._key = api_key
        self._base = base_url.rstrip("/") + "/api/v1"
        self._max_retries = max_retries
        self._timeout = timeout
        self._transport = transport or _urllib_transport
        self.wallets = _Wallets(self)
        self.transfers = _Transfers(self)
        self.operations = _Operations(self)
        self.payouts = _Payouts(self)
        self.embedded = _Embedded(self)
        self.swap = _Swap(self)
        self.screening = _Screening(self)
        self.security = _Security(self)
        self.networks = _Networks(self, "/networks")
        self.deposit_addresses = _DepositAddresses(self)
        self.travel_rule = _TravelRule(self)
        self.reserves = _Reserves(self)
        self.payees = _Simple(self, "/payees")
        self.prices = _Simple(self, "/prices")
        self.tokens = _Simple(self, "/tokens")
        self.events = _Events(self)
        self.audit = _Audit(self)
        self.network = _Network(self)
        self.vaults = _Vaults(self)
        self.policy = _Policy(self)
        self.addresses = _Addresses(self)
        self.address_proofs = _AddressProofs(self)
        self.reports = _Reports(self)

    def __repr__(self) -> str:
        return f"Chainvara(mode={self.mode!r})"  # never the key

    def request(self, method: str, path: str, body: Optional[Mapping[str, Any]] = None, query: Optional[Mapping[str, Any]] = None, *, idempotency_key: Optional[str] = None) -> Any:
        q = {k: ("true" if v is True else "false" if v is False else str(v)) for k, v in (query or {}).items() if v is not None}
        url = self._base + path + (("?" + parse.urlencode(q)) if q else "")
        headers = {"authorization": f"Bearer {self._key}", "accept": "application/json", "user-agent": f"chainvara-python/{__version__}"}
        data: Optional[bytes] = None
        if method == "POST":
            headers["content-type"] = "application/json"
            headers["idempotency-key"] = idempotency_key or f"sdk_{uuid.uuid4()}"
            data = json.dumps(body if body is not None else {}, separators=(",", ":")).encode("utf-8")
        attempt = 0
        while True:
            status, res_headers, raw = 0, {}, b""
            net_err: Optional[BaseException] = None
            try:
                status, res_headers, raw = self._transport(method, url, headers, data, self._timeout)
            except (urlerror.URLError, OSError, TimeoutError) as e:
                net_err = e
            retryable = net_err is not None or status == 429 or status >= 500
            if retryable and attempt < self._max_retries:
                try:
                    ra = float(res_headers.get("retry-after", "") or 0)
                except ValueError:
                    ra = 0
                time.sleep(min(ra, 60) if ra > 0 else 0.5 * 2 ** attempt + random.random() * 0.25)
                attempt += 1
                continue
            if net_err is not None:
                raise ChainvaraError(f"Network error: {net_err}", 0, "connection_error", "network_error", None)
            request_id = res_headers.get("request-id")
            try:
                payload = json.loads(raw.decode("utf-8")) if raw else None
            except ValueError:
                payload = None
            if status >= 400:
                err = (payload or {}).get("error") if isinstance(payload, dict) else None
                err = err if isinstance(err, dict) else {}
                raise ChainvaraError(err.get("message") or f"HTTP {status}", status, err.get("type") or "api_error", err.get("code") or "http_error", err.get("request_id") or request_id)
            return payload


def _clean(d: Mapping[str, Any]) -> Json:
    return {k: v for k, v in d.items() if v is not None}


def _seg(s: str) -> str:
    return parse.quote(str(s), safe="")


class _Resource:
    def __init__(self, client: Chainvara):
        self._c = client


class _Wallets(_Resource):
    def create(self, *, network: str, label: Optional[str] = None, external_user_id: Optional[str] = None, kind: Optional[str] = None, key_mode: Optional[str] = None, idempotency_key: Optional[str] = None) -> Json:
        """New key in the vault. key_mode: single (default), split (2-of-2 with your co-signer) or mpc."""
        return self._c.request("POST", "/wallets", _clean({"network": network, "label": label, "external_user_id": external_user_id, "kind": kind, "key_mode": key_mode}), idempotency_key=idempotency_key)

    def watch(self, *, network: str, address: str, label: Optional[str] = None, kind: Optional[str] = None) -> Json:
        """Watch-only: track any address, no key."""
        return self._c.request("POST", "/wallets", _clean({"network": network, "address": address, "label": label, "kind": kind}))

    def for_user(self, external_user_id: str, network: str, label: Optional[str] = None) -> Json:
        """One wallet per end user and network: created on first call, returned afterwards."""
        return self.create(network=network, external_user_id=external_user_id, label=label)

    def list(self, *, purpose: Optional[str] = None, custody: Optional[str] = None, external_user_id: Optional[str] = None, limit: Optional[int] = None) -> Json:
        return self._c.request("GET", "/wallets", query={"purpose": purpose, "custody": custody, "external_user_id": external_user_id, "limit": limit})

    def get(self, wallet_id: str) -> Json:
        return self._c.request("GET", f"/wallets/{_seg(wallet_id)}")

    def balances(self, wallet_id: str, *, refresh: Optional[bool] = None) -> Json:
        return self._c.request("GET", f"/wallets/{_seg(wallet_id)}/balances", query={"refresh": refresh})

    def transactions(self, wallet_id: str, *, limit: Optional[int] = None) -> Json:
        return self._c.request("GET", f"/wallets/{_seg(wallet_id)}/transactions", query={"limit": limit})

    def allowances(self, wallet_id: str) -> Json:
        """Token approvals of an EVM wallet that can still be used (ERC-20, NFT operators, Permit2), riskiest first."""
        return self._c.request("GET", f"/wallets/{_seg(wallet_id)}/allowances")

    def revoke_allowance(self, wallet_id: str, *, kind: str, token: str, spender: str, idempotency_key: Optional[str] = None) -> Json:
        """Requests the revocation of one approval: a contract call under your policy, approvals and co-signer."""
        return self._c.request("POST", f"/wallets/{_seg(wallet_id)}/allowances", {"kind": kind, "token": token, "spender": spender}, idempotency_key=idempotency_key)

    def refresh_keys(self, wallet_id: str, *, idempotency_key: Optional[str] = None) -> Json:
        """Renews both shares of an MPC wallet with your co-signer (same address; older shares stop working)."""
        return self._c.request("POST", f"/wallets/{_seg(wallet_id)}/refresh-keys", {}, idempotency_key=idempotency_key)


class _DepositAddresses(_Resource):
    def create(self, *, external_user_id: str, networks: Optional[List[str]] = None, label: Optional[str] = None, idempotency_key: Optional[str] = None) -> Json:
        """Every deposit address of one of your users in one call (one wallet per network); calling again returns the same ones."""
        return self._c.request("POST", "/deposit-addresses", _clean({"external_user_id": external_user_id, "networks": list(networks) if networks is not None else None, "label": label}), idempotency_key=idempotency_key)


class _Transfers(_Resource):
    def create(self, *, wallet_id: str, asset: str, amount: str, destination: str, note: Optional[str] = None, travel_rule: Optional[Mapping[str, Any]] = None, idempotency_key: Optional[str] = None, **extra: Any) -> Json:
        """Evaluated against your policy; executed once approved. Amounts are decimal strings ("0.25"), never floats."""
        if not isinstance(amount, str):
            raise TypeError('amount must be a decimal string such as "0.25" (floats lose precision).')
        return self._c.request("POST", "/transfers", _clean({"wallet_id": wallet_id, "asset": asset, "amount": amount, "destination": destination, "note": note, "travel_rule": travel_rule, **extra}), idempotency_key=idempotency_key)

    def preview(self, *, wallet_id: str, asset: str, amount: str, destination: str, **extra: Any) -> Json:
        """Policy decision, network fee and a dry run on chain. Nothing is created or signed."""
        return self._c.request("POST", "/transfers/preview", _clean({"wallet_id": wallet_id, "asset": asset, "amount": amount, "destination": destination, **extra}))

    def list(self, *, status: Optional[str] = None, wallet_id: Optional[str] = None, external_id: Optional[str] = None, tag: Optional[str] = None, limit: Optional[int] = None, starting_after: Optional[str] = None) -> Json:
        """Newest first; when has_more, pass next_cursor as starting_after for the next page."""
        return self._c.request("GET", "/transfers", query={"status": status, "wallet_id": wallet_id, "external_id": external_id, "tag": tag, "limit": limit, "starting_after": starting_after})

    def iterate(self, *, status: Optional[str] = None, wallet_id: Optional[str] = None, tag: Optional[str] = None):
        """Every transfer matching the filters, newest first, page after page."""
        after: Optional[str] = None
        while True:
            page = self.list(status=status, wallet_id=wallet_id, tag=tag, limit=200, starting_after=after)
            yield from page.get("data", [])
            if not page.get("has_more") or not page.get("next_cursor"):
                return
            after = page["next_cursor"]

    def set_tags(self, transfer_id: str, tags: List[str], *, idempotency_key: Optional[str] = None) -> Json:
        """Replaces the accounting tags (never part of what was approved or signed)."""
        return self._c.request("POST", f"/transfers/{_seg(transfer_id)}/tags", {"tags": list(tags)}, idempotency_key=idempotency_key)

    def get(self, transfer_id: str) -> Json:
        return self._c.request("GET", f"/transfers/{_seg(transfer_id)}")

    def cancel(self, transfer_id: str, *, idempotency_key: Optional[str] = None) -> Json:
        return self._c.request("POST", f"/transfers/{_seg(transfer_id)}/cancel", idempotency_key=idempotency_key)

    def speed_up(self, transfer_id: str, *, idempotency_key: Optional[str] = None) -> Json:
        """Stuck EVM transaction: the same transaction again with a higher fee (same nonce)."""
        return self._c.request("POST", f"/transfers/{_seg(transfer_id)}/speed-up", idempotency_key=idempotency_key)

    def cancel_onchain(self, transfer_id: str, *, idempotency_key: Optional[str] = None) -> Json:
        """Stuck EVM transaction: replaced by a 0-value transaction to the wallet (same nonce)."""
        return self._c.request("POST", f"/transfers/{_seg(transfer_id)}/cancel-onchain", idempotency_key=idempotency_key)

    def wait(self, transfer_id: str, *, interval: float = 5.0, timeout: float = 600.0, until: Optional[Callable[[Json], bool]] = None) -> Json:
        """Polls until the transfer reaches a final status (or `until` returns True)."""
        deadline = time.monotonic() + timeout
        while True:
            t = self.get(transfer_id)
            if until(t) if until else t.get("status") in FINAL_TRANSFER_STATUSES:
                return t
            if time.monotonic() > deadline:
                raise ChainvaraError(f"Transfer {transfer_id} still {t.get('status')} after timeout.", 408, "timeout", "wait_timeout", None)
            time.sleep(interval)


class _Operations(_Resource):
    def create(self, *, wallet_id: str, type: str, idempotency_key: Optional[str] = None, **fields: Any) -> Json:
        """Tokens, swaps, staking, contract calls: same policy, approvals and signing as transfers."""
        return self._c.request("POST", "/operations", _clean({"wallet_id": wallet_id, "type": type, **fields}), idempotency_key=idempotency_key)

    def list(self, *, limit: Optional[int] = None) -> Json:
        return self._c.request("GET", "/operations", query={"limit": limit})


class _Payouts(_Resource):
    def create(self, *, wallet_id: str, asset: str, items: Iterable[Mapping[str, Any]], reference: Optional[str] = None, idempotency_key: Optional[str] = None) -> Json:
        """Up to 500 payouts in one batch. Pass an idempotency_key so a retry never pays twice."""
        lines = [dict(i) for i in items]
        for n, line in enumerate(lines, 1):
            if not isinstance(line.get("amount"), str):
                raise TypeError(f"Line {n}: amount must be a decimal string.")
        return self._c.request("POST", "/payouts", _clean({"wallet_id": wallet_id, "asset": asset, "reference": reference, "items": lines}), idempotency_key=idempotency_key)

    def get(self, batch_id: str) -> Json:
        return self._c.request("GET", f"/payouts/{_seg(batch_id)}")

    def list(self, *, limit: Optional[int] = None) -> Json:
        return self._c.request("GET", "/payouts", query={"limit": limit})


class _Embedded(_Resource):
    def relay(self, path: str, body: Mapping[str, Any]) -> Json:
        """Forwards a call of the device SDK (chainvara-embedded.js). Set external_user_id from YOUR session, never from the device."""
        if path not in ("/embedded/wallets", "/embedded/sign", "/embedded/backup"):
            raise ChainvaraError("Unknown embedded path.", 400, "invalid_request_error", "parameter_invalid", None)
        return self._c.request("POST", path, dict(body))


class _Swap(_Resource):
    def quote(self, *, wallet_id: str, sell: str, buy: str, amount: str, slippage_bps: Optional[int] = None) -> Json:
        return self._c.request("GET", "/swap/quote", query={"wallet_id": wallet_id, "sell": sell, "buy": buy, "amount": amount, "slippage_bps": slippage_bps})


class _Screening(_Resource):
    def check(self, network: str, address: str) -> Json:
        """Sanctions screening (OFAC SDN) of any address."""
        return self._c.request("GET", "/screening", query={"network": network, "address": address})

    def inbound(self, *, status: Optional[str] = None, limit: Optional[int] = None) -> Json:
        """Screening of the senders of your deposits: clear, flagged, released or reported."""
        return self._c.request("GET", "/screening/inbound", query={"status": status, "limit": limit})


class _TravelRule(_Resource):
    def messages(self, *, direction: Optional[str] = None) -> Json:
        """Travel Rule messages exchanged with organizations on the Chainvara network (incoming or outgoing)."""
        return self._c.request("GET", "/travel-rule/messages", query={"direction": direction})

    def acknowledge(self, message_id: str, *, idempotency_key: Optional[str] = None) -> Json:
        """As beneficiary: confirm you received the originator information."""
        return self._c.request("POST", f"/travel-rule/messages/{_seg(message_id)}/acknowledge", {}, idempotency_key=idempotency_key)


class _Reserves(_Resource):
    def create_snapshot(self, *, customers: Iterable[Mapping[str, Any]], idempotency_key: Optional[str] = None) -> Json:
        """Commits customer liabilities ([{user_id, balances: {"BTC": "0.25"}}]) in a Merkle sum tree and reads your reserves."""
        return self._c.request("POST", "/reserves/snapshots", {"customers": [dict(c) for c in customers]}, idempotency_key=idempotency_key)

    def proof(self, snapshot_id: str, user_id: str) -> Json:
        """One customer's inclusion proof, to give to that customer."""
        return self._c.request("GET", f"/reserves/snapshots/{_seg(snapshot_id)}/proof", query={"user_id": user_id})


class _Security(_Resource):
    def posture(self) -> Json:
        return self._c.request("GET", "/security")


class _Events(_Resource):
    def list(self, *, type: Optional[str] = None, limit: Optional[int] = None, after: Optional[int] = None) -> Json:
        """Newest first, or with after=<seq> the events that came next, oldest first (poll again with next_after)."""
        return self._c.request("GET", "/events", query={"type": type, "limit": limit, "after": after})


class _Audit(_Resource):
    """Audit trail for a SIEM (scope audit:read): poll list(after=last_seq); verify() recomputes the hash chain."""

    def list(self, *, after: Optional[int] = None, since: Optional[str] = None, action: Optional[str] = None, limit: Optional[int] = None) -> Json:
        return self._c.request("GET", "/audit", query={"after": after, "since": since, "action": action, "limit": limit})

    def verify(self) -> Json:
        return self._c.request("GET", "/audit/verify")


class _Vaults(_Resource):
    """Vault accounts. freeze() stops every outflow of a vault until it is unfrozen in the console (never by API)."""

    def list(self) -> Json:
        return self._c.request("GET", "/vaults")

    def create(self, *, name: str, description: Optional[str] = None, idempotency_key: Optional[str] = None) -> Json:
        body: dict = {"name": name}
        if description is not None:
            body["description"] = description
        return self._c.request("POST", "/vaults", body, idempotency_key=idempotency_key)

    def freeze(self, vault_id: str, reason: str, *, idempotency_key: Optional[str] = None) -> Json:
        return self._c.request("POST", f"/vaults/{parse.quote(vault_id, safe='')}/freeze", {"reason": reason}, idempotency_key=idempotency_key)

    def assign_wallet(self, wallet_id: str, vault_id: Optional[str], *, idempotency_key: Optional[str] = None) -> Json:
        return self._c.request("POST", f"/wallets/{parse.quote(wallet_id, safe='')}/vault", {"vault_id": vault_id}, idempotency_key=idempotency_key)


class _Policy(_Resource):
    """Policy as code: the policy in force, and the impact of a candidate on the last 200 requests (nothing published)."""

    def get(self) -> Json:
        return self._c.request("GET", "/policy")

    def impact(self, policy: Mapping[str, Any]) -> Json:
        return self._c.request("POST", "/policy/impact", {"policy": dict(policy)})


class _Addresses(_Resource):
    """Address book: trusted destinations (add/revoke need the addresses:write scope; additions wait for the cooldown)."""

    def list(self) -> Json:
        return self._c.request("GET", "/addresses")

    def add(self, *, network: str, address: str, label: str, note: Optional[str] = None, beneficiary: Optional[Mapping[str, Any]] = None, idempotency_key: Optional[str] = None) -> Json:
        """beneficiary: {"name", "type": "natural"|"legal", "vasp" (None = self-hosted), "reference"?}, sealed and attached to transfers to this address."""
        body: dict = {"network": network, "address": address, "label": label}
        if note is not None:
            body["note"] = note
        if beneficiary is not None:
            body["beneficiary"] = dict(beneficiary)
        return self._c.request("POST", "/addresses", body, idempotency_key=idempotency_key)

    def revoke(self, address_id: str, *, idempotency_key: Optional[str] = None) -> Json:
        return self._c.request("POST", f"/addresses/{parse.quote(address_id, safe='')}/revoke", {}, idempotency_key=idempotency_key)


class _AddressProofs(_Resource):
    """Self-hosted wallet ownership proofs (EU Transfer of Funds Regulation): create() returns the message and the link to send the owner."""

    def create(self, *, network: str, address: str, label: str, idempotency_key: Optional[str] = None) -> Json:
        return self._c.request("POST", "/address-proofs", {"network": network, "address": address, "label": label}, idempotency_key=idempotency_key)

    def list(self) -> Json:
        return self._c.request("GET", "/address-proofs")

    def submit_signature(self, proof_id: str, signature: str, *, idempotency_key: Optional[str] = None) -> Json:
        return self._c.request("POST", f"/address-proofs/{parse.quote(proof_id, safe='')}/signature", {"signature": signature}, idempotency_key=idempotency_key)


class _Reports(_Resource):
    """Accounting (scope transfers:read): the valued ledger and realized gains (method "fifo" or "average")."""

    def ledger(self, *, from_: Optional[str] = None, to: Optional[str] = None) -> Json:
        return self._c.request("GET", "/reports/ledger", query={"from": from_, "to": to})

    def gains(self, *, from_: Optional[str] = None, to: Optional[str] = None, method: Optional[str] = None) -> Json:
        return self._c.request("GET", "/reports/gains", query={"from": from_, "to": to, "method": method})


def check_audit_links(events: List[Json], seq: int = 0, prev_hash: Optional[str] = None) -> Optional[Json]:
    """First break in a page of audit events continuing the chain at (seq, prev_hash), or None."""
    for e in events:
        if e.get("seq") != seq + 1:
            return {"seq": e.get("seq"), "problem": "sequence_gap"}
        if e.get("prev_hash") != prev_hash:
            return {"seq": e.get("seq"), "problem": "link_mismatch"}
        seq, prev_hash = e["seq"], e.get("hash")
    return None


class _Network(_Resource):
    """Chainvara network: payment requests and bilateral net settlement with connected organizations."""

    def request_payment(self, *, to: str, network: str, asset: str, amount: str, reference: str, note: Optional[str] = None, ttl_days: Optional[int] = None, idempotency_key: Optional[str] = None) -> Json:
        """Ask a connected organization (to="@handle") to pay you, to your published address on that network."""
        if not isinstance(amount, str):
            raise TypeError('amount must be a decimal string such as "0.25".')
        return self._c.request("POST", "/network/requests", _clean({"to": to, "network": network, "asset": asset, "amount": amount, "reference": reference, "note": note, "ttl_days": ttl_days}), idempotency_key=idempotency_key)

    def requests(self, *, direction: Optional[str] = None, status: Optional[str] = None) -> Json:
        return self._c.request("GET", "/network/requests", query={"direction": direction, "status": status})

    def pay_request(self, request_id: str, *, wallet_id: str, idempotency_key: Optional[str] = None) -> Json:
        """Pays an incoming request from one of your wallets: a normal transfer under your policy and approvals."""
        return self._c.request("POST", f"/network/requests/{_seg(request_id)}/pay", {"wallet_id": wallet_id}, idempotency_key=idempotency_key)

    def close_request(self, request_id: str) -> Json:
        """Declines (payer) or cancels (requester) an open request."""
        return self._c.request("POST", f"/network/requests/{_seg(request_id)}/close")

    def record_obligation(self, *, counterparty: str, direction: str, network: str, asset: str, amount: str, reference: str, idempotency_key: Optional[str] = None) -> Json:
        """direction: "they_owe" or "we_owe". Counts in the net position once the counterparty confirms it."""
        if direction not in ("they_owe", "we_owe"):
            raise ValueError('direction must be "they_owe" or "we_owe"')
        if not isinstance(amount, str):
            raise TypeError('amount must be a decimal string such as "0.25".')
        return self._c.request("POST", "/network/obligations", {"counterparty": counterparty, "direction": direction, "network": network, "asset": asset, "amount": amount, "reference": reference}, idempotency_key=idempotency_key)

    def obligations(self) -> Json:
        return self._c.request("GET", "/network/obligations")

    def answer_obligation(self, obligation_id: str, action: str) -> Json:
        """action: "confirm" or "dispute" (counterparty), "cancel" (the side that recorded it)."""
        if action not in ("confirm", "dispute", "cancel"):
            raise ValueError('action must be "confirm", "dispute" or "cancel"')
        return self._c.request("POST", f"/network/obligations/{_seg(obligation_id)}/{action}")

    def positions(self) -> Json:
        """Net of confirmed obligations per counterparty and asset."""
        return self._c.request("GET", "/network/positions")

    def settle(self, *, counterparty: str, asset_id: str, wallet_id: str, idempotency_key: Optional[str] = None) -> Json:
        """The net debtor settles the whole position with one transfer; the obligations settle when it confirms."""
        return self._c.request("POST", "/network/settlements", {"counterparty": counterparty, "asset_id": asset_id, "wallet_id": wallet_id}, idempotency_key=idempotency_key)

    def settlements(self) -> Json:
        return self._c.request("GET", "/network/settlements")


class _Simple(_Resource):
    def __init__(self, client: Chainvara, path: str):
        super().__init__(client)
        self._path = path

    def list(self) -> Json:
        return self._c.request("GET", self._path)


class _Networks(_Simple):
    def fees(self, network: str) -> Json:
        """Current fee estimates for a typical transfer at each fee_level (low, medium, high)."""
        return self._c.request("GET", f"/networks/{_seg(network)}/fees")


# ---------------------------------------------------------------------------------------------- webhooks, co-signer

def _hmac_hex(secret: str, data: str) -> str:
    return hmac.new(secret.encode("utf-8"), data.encode("utf-8"), hashlib.sha256).hexdigest()


def sign_webhook_payload(raw_body: str, secret: str, timestamp: Optional[int] = None) -> str:
    """fos-signature header for a body: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">. For testing your endpoint."""
    t = int(time.time()) if timestamp is None else int(timestamp)
    return f"t={t},v1={_hmac_hex(secret, f'{t}.{raw_body}')}"


def verify_cosigner_callback(raw_body: str | bytes, signature_header: Optional[str], secret: str, *, tolerance: int = 300, now: Optional[int] = None) -> Json:
    """On your callback server: checks the co-signer's x-chainvara-signature (secret from `node chainvara-cosigner.mjs callback-secret`)
    and returns the approval request ({ request_id, transfer: {...} })."""
    req = verify_webhook(raw_body, signature_header, secret, tolerance=tolerance, now=now)
    if req.get("type") != "transfer.approval_request" or not isinstance(req.get("request_id"), str):
        raise ChainvaraError("Not a co-signer approval request.", 400, "signature_error", "unexpected_payload", None)
    return req


def cosigner_callback_answer(request: Json, action: str, secret: str, reason: Optional[str] = None) -> Tuple[str, Dict[str, str]]:
    """Your answer to the co-signer: (body, headers) to send with HTTP 200. action is "approve" or "reject"."""
    if action not in ("approve", "reject"):
        raise ValueError("action must be approve or reject")
    body = json.dumps({"request_id": request["request_id"], "action": action, **({"reason": reason} if reason else {})}, separators=(",", ":"))
    return body, {"content-type": "application/json", "x-chainvara-signature": sign_webhook_payload(body, secret)}


def verify_webhook(raw_body: str | bytes, signature_header: Optional[str], secret: str, *, tolerance: int = 300, now: Optional[int] = None) -> Json:
    """Checks the fos-signature of a webhook (pass the RAW body, exactly as received) and returns the event."""
    body = raw_body.decode("utf-8") if isinstance(raw_body, (bytes, bytearray)) else raw_body
    if not signature_header:
        raise ChainvaraError("Missing fos-signature header.", 400, "signature_error", "missing_signature", None)
    pairs = [p.strip().split("=", 1) for p in signature_header.split(",") if "=" in p]
    parts = dict(pairs)
    # During a secret rotation the header carries one v1 per secret: any of them may match.
    v1s = [v for k, v in pairs if k == "v1" and re.fullmatch(r"[0-9a-f]{64}", v)]
    try:
        t: Optional[int] = int(parts.get("t", ""))
    except ValueError:
        t = None
    if t is None or not v1s:
        raise ChainvaraError("Malformed fos-signature header.", 400, "signature_error", "malformed_signature", None)
    current = int(time.time()) if now is None else now
    if abs(current - t) > tolerance:
        raise ChainvaraError("Webhook signature timestamp is outside the tolerance window.", 400, "signature_error", "timestamp_out_of_range", None)
    expected = _hmac_hex(secret, f"{t}.{body}")
    if not any(hmac.compare_digest(expected, v) for v in v1s):
        raise ChainvaraError("Webhook signature does not match.", 400, "signature_error", "invalid_signature", None)
    return json.loads(body)


def verify_cosigner_request(raw_body: str | bytes, signature_header: Optional[str], secret: str, **opts: Any) -> Json:
    """Verifies an API co-signer request (transfer.sign_request) and returns it."""
    parsed = verify_webhook(raw_body, signature_header, secret, **opts)
    if parsed.get("type") != "transfer.sign_request":
        raise ChainvaraError("Not a co-signer request.", 400, "signature_error", "unexpected_type", None)
    return parsed


def cosigner_response(req: Mapping[str, Any], action: str, secret: str, reason: Optional[str] = None) -> Tuple[str, Dict[str, str]]:
    """Signed answer (HTTP 200) to a co-signer request: return `body` with `headers`. action: "approve" or "reject"."""
    if action not in ("approve", "reject"):
        raise ValueError('action must be "approve" or "reject"')
    payload: Json = {"request_id": req["request_id"], "transfer_id": req["data"]["id"], "action": action}
    if reason:
        payload["reason"] = reason
    body = json.dumps(payload, separators=(",", ":"))
    return body, {"content-type": "application/json", "fos-signature": sign_webhook_payload(body, secret)}
