@totalis/hip4-client 0.0.0-stage → 0.73.0

package/dist/typed-data.d.ts

@@ -0,0 +1,330 @@
+import type { components } from "./generated/openapi.js";
+type Schemas = components["schemas"];
+export type Hex = `0x${string}`;
+/**
+ * EIP-712 types for every Totalis vault signature. One module signs for
+ * takers and makers alike; the account's signer (the `wallet` of GET /v1/me,
+ * or maker capital's `signer`) is the address that signs.
+ */
+export declare const totalisTypes: {
+    readonly Leg: readonly [{
+        readonly name: "outcomeId";
+        readonly type: "uint32";
+    }, {
+        readonly name: "side";
+        readonly type: "uint8";
+    }];
+    readonly Quote: readonly [{
+        readonly name: "makerId";
+        readonly type: "uint64";
+    }, {
+        readonly name: "legs";
+        readonly type: "Leg[]";
+    }, {
+        readonly name: "stake";
+        readonly type: "uint128";
+    }, {
+        readonly name: "payout";
+        readonly type: "uint128";
+    }, {
+        readonly name: "feeBps";
+        readonly type: "uint16";
+    }, {
+        readonly name: "takerFeeBps";
+        readonly type: "uint16";
+    }, {
+        readonly name: "taker";
+        readonly type: "address";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }, {
+        readonly name: "salt";
+        readonly type: "uint256";
+    }];
+    readonly TakerAccept: readonly [{
+        readonly name: "makerId";
+        readonly type: "uint64";
+    }, {
+        readonly name: "legs";
+        readonly type: "Leg[]";
+    }, {
+        readonly name: "stake";
+        readonly type: "uint128";
+    }, {
+        readonly name: "payout";
+        readonly type: "uint128";
+    }, {
+        readonly name: "feeBps";
+        readonly type: "uint16";
+    }, {
+        readonly name: "takerFeeBps";
+        readonly type: "uint16";
+    }, {
+        readonly name: "taker";
+        readonly type: "address";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }, {
+        readonly name: "salt";
+        readonly type: "uint256";
+    }];
+    readonly SellBack: readonly [{
+        readonly name: "ticketId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "price";
+        readonly type: "uint128";
+    }, {
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }, {
+        readonly name: "salt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "legState";
+        readonly type: "bytes32";
+    }];
+    readonly CashoutTransfer: readonly [{
+        readonly name: "ticketId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "price";
+        readonly type: "uint128";
+    }, {
+        readonly name: "seller";
+        readonly type: "address";
+    }, {
+        readonly name: "buyer";
+        readonly type: "address";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }, {
+        readonly name: "salt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "legState";
+        readonly type: "bytes32";
+    }];
+    readonly Exit: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }, {
+        readonly name: "salt";
+        readonly type: "uint256";
+    }];
+};
+export type TotalisPrimaryType = Exclude<keyof typeof totalisTypes, "Leg">;
+/** Who signs each struct: the maker's signer, the taker's signer, or either side of a cash-out. */
+export declare const signedBy: {
+    readonly Quote: "maker";
+    readonly TakerAccept: "taker";
+    readonly SellBack: "maker_and_taker";
+    readonly CashoutTransfer: "maker_and_taker";
+    readonly Exit: "taker";
+};
+/** The vault deployment a signature binds to: GET /v1/deployment. */
+export type TotalisDeployment = Pick<Schemas["Deployment"], "chain_id" | "vault_address">;
+/** The deployment's canonical USDC and its signing domain, as GET /v1/deployment publishes them. */
+export type UsdcDeployment = Pick<Schemas["Deployment"], "usdc">;
+export type TypedDataField = {
+    readonly name: string;
+    readonly type: string;
+};
+/** An EIP-712 payload with the domain every Totalis and USDC signature uses. */
+export type TypedData = {
+    readonly domain: {
+        readonly name: string;
+        readonly version: string;
+        readonly chainId: bigint;
+        readonly verifyingContract: Hex;
+    };
+    readonly types: {
+        readonly [name: string]: readonly TypedDataField[];
+    };
+    readonly primaryType: string;
+    readonly message: Record<string, unknown>;
+};
+export type TotalisTypedData<P extends TotalisPrimaryType = TotalisPrimaryType> = {
+    readonly domain: {
+        readonly name: "TotalisParlay";
+        readonly version: "1";
+        readonly chainId: bigint;
+        readonly verifyingContract: Hex;
+    };
+    readonly types: Pick<typeof totalisTypes, P | (P extends "Quote" | "TakerAccept" ? "Leg" : never)>;
+    readonly primaryType: P;
+    readonly message: Record<string, unknown>;
+};
+/** A 20-byte hex address, or a TypeError. */
+export declare function address(value: string): Hex;
+/** A leg as the API names it: a decimal outcome ID and YES or NO. */
+export type Leg = Schemas["QuoteTerms"]["legs"][number];
+/** The signed Leg: outcome_id as uint32, and side 0 for YES, 1 for NO. */
+export declare function signedLeg(leg: Leg): {
+    readonly outcomeId: number;
+    readonly side: 0 | 1;
+};
+/** A maker's signed quote on an entry RFQ, from a quote's `entry` terms. */
+export declare function quoteTypedData(deployment: TotalisDeployment, quote: Schemas["QuoteTerms"]): TotalisTypedData<"Quote">;
+/** A taker's acceptance of the exact quote it received. */
+export declare function takerAcceptTypedData(deployment: TotalisDeployment, quote: Schemas["QuoteTerms"]): TotalisTypedData<"TakerAccept">;
+/**
+ * A sell-back of a position to its original maker; the maker quotes it and the
+ * owner accepts it. `position_id` from the API goes into `ticketId`.
+ */
+export declare function sellBackTypedData(deployment: TotalisDeployment, bid: Schemas["SellBackTerms"]): TotalisTypedData<"SellBack">;
+/**
+ * A cash-out transfer of a position to a buying maker; the maker quotes it and
+ * the seller accepts it. `position_id` from the API goes into `ticketId`.
+ */
+export declare function cashoutTransferTypedData(deployment: TotalisDeployment, bid: Schemas["TransferTerms"]): TotalisTypedData<"CashoutTransfer">;
+/** The vault leg of a withdrawal: the Exit that moves its shortfall from the vault to the wallet. */
+export declare function exitTypedData(deployment: TotalisDeployment, exit: {
+    account: Hex;
+    to: Hex;
+    amount: string;
+    expiry: string;
+    salt: string;
+}): TotalisTypedData<"Exit">;
+export declare const domainTypes: {
+    readonly EIP712Domain: readonly [{
+        readonly name: "name";
+        readonly type: "string";
+    }, {
+        readonly name: "version";
+        readonly type: "string";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "verifyingContract";
+        readonly type: "address";
+    }];
+};
+export declare function hashDomain(domain: TypedData["domain"]): Hex;
+/** The EIP-712 digest a signer signs; for a Quote this is the `quote_digest` the API expects. */
+export declare function hashTypedData(typedData: TypedData): Hex;
+export declare const usdcTypes: {
+    readonly ReceiveWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+export type UsdcTypedData<P extends keyof typeof usdcTypes> = {
+    readonly domain: {
+        readonly name: "USDC";
+        readonly version: "2";
+        readonly chainId: bigint;
+        readonly verifyingContract: Hex;
+    };
+    readonly types: Pick<typeof usdcTypes, P>;
+    readonly primaryType: P;
+    readonly message: Record<string, unknown>;
+};
+/** The USDC EIP-712 domain GET /v1/deployment publishes, in signer form. */
+export declare function usdcDomain(deployment: UsdcDeployment): UsdcTypedData<"ReceiveWithAuthorization">["domain"];
+/** The wallet side of an accept's funding, in the API's wire shape. */
+export type DepositAuthorization = {
+    readonly account: string;
+    readonly from: string;
+    readonly value: string;
+    readonly valid_after: string;
+    readonly valid_before: string;
+    readonly salt: string;
+};
+/** The EIP-3009 nonce `ParlayVault.depositUserWithAuthorization` derives: keccak256(abi.encode(vault, chainId, from, salt, account)). */
+export declare function depositNonce(deployment: TotalisDeployment, authorization: Pick<DepositAuthorization, "account" | "from" | "salt">): Hex;
+/** USDC ReceiveWithAuthorization that lets the vault pull a deposit from the wallet. */
+export declare function receiveWithAuthorizationTypedData(deployment: TotalisDeployment & UsdcDeployment, authorization: DepositAuthorization): UsdcTypedData<"ReceiveWithAuthorization">;
+/**
+ * The EIP-3009 nonce of a withdrawal's payout, derived from the create's
+ * Idempotency-Key: keccak256(abi.encode(keccak256("TOTALIS_PAYOUT_NONCE_V1"),
+ * chainId, vault, account, uint128(idempotencyKey))). Sign the payout under it;
+ * the venue derives the same bytes, so the signature is bound to that one request.
+ */
+export declare function payoutNonce(deployment: TotalisDeployment, account: string, idempotencyKey: string): Hex;
+/** A withdrawal's payout: exactly `value` from the embedded wallet to `to`, under `payoutNonce`. */
+export type PayoutAuthorization = {
+    readonly from: string;
+    readonly to: string;
+    readonly value: string;
+    readonly valid_after: string;
+    readonly valid_before: string;
+    readonly nonce: Hex;
+};
+/** USDC TransferWithAuthorization for a Totalis withdrawal payout, under the deployment's USDC domain. */
+export declare function transferWithAuthorizationTypedData(deployment: UsdcDeployment, payout: PayoutAuthorization): UsdcTypedData<"TransferWithAuthorization">;
+/** Any EIP-712 signer. `toTotalisSigner` in `./signer` adapts viem, EIP-1193 and ethers signers. */
+export type TypedDataSigner = {
+    signTypedData(typedData: TypedData): Promise<Hex>;
+};
+/** Lowercase hex with v in {27, 28}: the venue rejects v = 0/1. Longer ERC-1271 signatures pass through. */
+export declare function canonicalSignature(signature: string): Hex;
+/** Sign with the account's signer and return the canonical signature the API expects. */
+export declare function signTotalis(signer: TypedDataSigner, typedData: TypedData): Promise<Hex>;
+/** The canonical EIP-712 type string, for checking a signer's encoding against the contract. */
+export declare function encodeType(primaryType: TotalisPrimaryType): string;
+export type IssueKeyMessage = {
+    readonly domain: string;
+    readonly address: string;
+    readonly uri: string;
+    readonly chainId: string;
+    readonly nonce: string;
+    readonly issuedAt: string;
+    readonly expirationTime: string;
+    readonly requestId: string;
+    readonly resources: readonly string[];
+};
+export declare function issueKeyMessage(message: IssueKeyMessage): string;
+/** Parse an issue_key message; throws unless it is exactly the server's template. */
+export declare function parseIssueKeyMessage(text: string): IssueKeyMessage;
+export {};

package/dist/typed-data.js

@@ -0,0 +1,340 @@
+import { keccak_256 } from "@noble/hashes/sha3";
+// A maker's quote and the taker's acceptance sign the same offer fields.
+const offerFields = [
+    { name: "makerId", type: "uint64" },
+    { name: "legs", type: "Leg[]" },
+    { name: "stake", type: "uint128" },
+    { name: "payout", type: "uint128" },
+    { name: "feeBps", type: "uint16" },
+    { name: "takerFeeBps", type: "uint16" },
+    { name: "taker", type: "address" },
+    { name: "expiry", type: "uint64" },
+    { name: "salt", type: "uint256" },
+];
+/**
+ * EIP-712 types for every Totalis vault signature. One module signs for
+ * takers and makers alike; the account's signer (the `wallet` of GET /v1/me,
+ * or maker capital's `signer`) is the address that signs.
+ */
+export const totalisTypes = {
+    Leg: [
+        { name: "outcomeId", type: "uint32" },
+        { name: "side", type: "uint8" },
+    ],
+    Quote: offerFields,
+    TakerAccept: offerFields,
+    SellBack: [
+        { name: "ticketId", type: "bytes32" },
+        { name: "price", type: "uint128" },
+        { name: "owner", type: "address" },
+        { name: "expiry", type: "uint64" },
+        { name: "salt", type: "uint256" },
+        { name: "legState", type: "bytes32" },
+    ],
+    CashoutTransfer: [
+        { name: "ticketId", type: "bytes32" },
+        { name: "price", type: "uint128" },
+        { name: "seller", type: "address" },
+        { name: "buyer", type: "address" },
+        { name: "expiry", type: "uint64" },
+        { name: "salt", type: "uint256" },
+        { name: "legState", type: "bytes32" },
+    ],
+    Exit: [
+        { name: "account", type: "address" },
+        { name: "to", type: "address" },
+        { name: "amount", type: "uint128" },
+        { name: "expiry", type: "uint64" },
+        { name: "salt", type: "uint256" },
+    ],
+};
+/** Who signs each struct: the maker's signer, the taker's signer, or either side of a cash-out. */
+export const signedBy = {
+    Quote: "maker",
+    TakerAccept: "taker",
+    SellBack: "maker_and_taker",
+    CashoutTransfer: "maker_and_taker",
+    Exit: "taker",
+};
+/** A 20-byte hex address, or a TypeError. */
+export function address(value) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(value))
+        throw new TypeError(`not an address: ${value}`);
+    return value;
+}
+function domain(deployment) {
+    return { name: "TotalisParlay", version: "1", chainId: BigInt(deployment.chain_id), verifyingContract: address(deployment.vault_address) };
+}
+/** The signed Leg: outcome_id as uint32, and side 0 for YES, 1 for NO. */
+export function signedLeg(leg) {
+    const outcomeId = Number(leg.outcome_id);
+    if (!/^(0|[1-9][0-9]*)$/.test(leg.outcome_id) || outcomeId > 0xffffffff)
+        throw new TypeError(`not a uint32 outcome_id: ${leg.outcome_id}`);
+    if (leg.side !== "YES" && leg.side !== "NO")
+        throw new TypeError(`not a side: ${String(leg.side)}`);
+    return { outcomeId, side: leg.side === "YES" ? 0 : 1 };
+}
+function offer(quote) {
+    return {
+        makerId: BigInt(quote.maker_id),
+        legs: quote.legs.map(signedLeg),
+        stake: BigInt(quote.stake),
+        payout: BigInt(quote.payout),
+        feeBps: quote.fee_bps,
+        takerFeeBps: quote.taker_fee_bps,
+        taker: quote.taker,
+        expiry: BigInt(quote.expiry),
+        salt: BigInt(quote.salt),
+    };
+}
+/** A maker's signed quote on an entry RFQ, from a quote's `entry` terms. */
+export function quoteTypedData(deployment, quote) {
+    return { domain: domain(deployment), types: { Quote: totalisTypes.Quote, Leg: totalisTypes.Leg }, primaryType: "Quote", message: offer(quote) };
+}
+/** A taker's acceptance of the exact quote it received. */
+export function takerAcceptTypedData(deployment, quote) {
+    return { domain: domain(deployment), types: { TakerAccept: totalisTypes.TakerAccept, Leg: totalisTypes.Leg }, primaryType: "TakerAccept", message: offer(quote) };
+}
+/**
+ * A sell-back of a position to its original maker; the maker quotes it and the
+ * owner accepts it. `position_id` from the API goes into `ticketId`.
+ */
+export function sellBackTypedData(deployment, bid) {
+    return {
+        domain: domain(deployment), types: { SellBack: totalisTypes.SellBack }, primaryType: "SellBack",
+        message: { ticketId: bid.position_id, price: BigInt(bid.price), owner: bid.owner, expiry: BigInt(bid.expiry), salt: BigInt(bid.salt), legState: bid.leg_state },
+    };
+}
+/**
+ * A cash-out transfer of a position to a buying maker; the maker quotes it and
+ * the seller accepts it. `position_id` from the API goes into `ticketId`.
+ */
+export function cashoutTransferTypedData(deployment, bid) {
+    return {
+        domain: domain(deployment), types: { CashoutTransfer: totalisTypes.CashoutTransfer }, primaryType: "CashoutTransfer",
+        message: { ticketId: bid.position_id, price: BigInt(bid.price), seller: bid.seller, buyer: bid.buyer, expiry: BigInt(bid.expiry), salt: BigInt(bid.salt), legState: bid.leg_state },
+    };
+}
+/** The vault leg of a withdrawal: the Exit that moves its shortfall from the vault to the wallet. */
+export function exitTypedData(deployment, exit) {
+    return {
+        domain: domain(deployment), types: { Exit: totalisTypes.Exit }, primaryType: "Exit",
+        message: { account: exit.account, to: exit.to, amount: BigInt(exit.amount), expiry: BigInt(exit.expiry), salt: BigInt(exit.salt) },
+    };
+}
+// ---------------------------------------------------------------------------
+// EIP-712 hashing, so makers can compute quote_digest and every signer can be
+// checked against the contract's vectors without a wallet library.
+const utf8 = new TextEncoder();
+function hexBytes(value) {
+    if (!/^0x(?:[0-9a-fA-F]{2})*$/.test(value))
+        throw new TypeError(`not hex: ${value}`);
+    return Uint8Array.from(value.slice(2).match(/../g) ?? [], (byte) => Number.parseInt(byte, 16));
+}
+function toHex(value) {
+    return `0x${Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((length, part) => length + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function uintWord(value, bits = 256) {
+    if (value < 0n || value >= 1n << BigInt(bits))
+        throw new RangeError(`${value} does not fit uint${bits}`);
+    return hexBytes(`0x${value.toString(16).padStart(64, "0")}`);
+}
+function bytes32(value) {
+    const word = hexBytes(value);
+    if (word.length !== 32)
+        throw new TypeError(`not bytes32: ${value}`);
+    return word;
+}
+function fields(types, name) {
+    const struct = types[name];
+    if (struct === undefined)
+        throw new TypeError(`unknown EIP-712 struct ${name}`);
+    return struct;
+}
+function structType(types, primary) {
+    const referenced = new Set();
+    const visit = (name) => {
+        for (const field of fields(types, name)) {
+            const base = field.type.replace(/\[\]$/, "");
+            if (types[base] !== undefined && base !== primary && !referenced.has(base)) {
+                referenced.add(base);
+                visit(base);
+            }
+        }
+    };
+    visit(primary);
+    return [primary, ...[...referenced].sort()]
+        .map((name) => `${name}(${fields(types, name).map((field) => `${field.type} ${field.name}`).join(",")})`)
+        .join("");
+}
+function encodeValue(types, type, value) {
+    if (type.endsWith("[]")) {
+        if (!Array.isArray(value))
+            throw new TypeError(`${type} needs an array`);
+        return keccak_256(concat(value.map((item) => encodeValue(types, type.slice(0, -2), item))));
+    }
+    if (types[type] !== undefined) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new TypeError(`${type} needs an object`);
+        return hashStruct(types, type, Object.fromEntries(Object.entries(value)));
+    }
+    if (type === "address")
+        return uintWord(BigInt(address(String(value))));
+    if (type === "bytes32")
+        return bytes32(String(value));
+    if (type === "string")
+        return keccak_256(utf8.encode(String(value)));
+    const uint = /^uint(\d+)$/.exec(type);
+    if (uint?.[1] !== undefined) {
+        if (typeof value !== "bigint" && typeof value !== "number" && typeof value !== "string")
+            throw new TypeError(`${type} needs an integer`);
+        return uintWord(BigInt(value), Number(uint[1]));
+    }
+    throw new TypeError(`unsupported EIP-712 type ${type}`);
+}
+function hashStruct(types, name, message) {
+    return keccak_256(concat([
+        keccak_256(utf8.encode(structType(types, name))),
+        ...fields(types, name).map((field) => encodeValue(types, field.type, message[field.name])),
+    ]));
+}
+export const domainTypes = {
+    EIP712Domain: [
+        { name: "name", type: "string" },
+        { name: "version", type: "string" },
+        { name: "chainId", type: "uint256" },
+        { name: "verifyingContract", type: "address" },
+    ],
+};
+export function hashDomain(domain) {
+    return toHex(hashStruct(domainTypes, "EIP712Domain", domain));
+}
+/** The EIP-712 digest a signer signs; for a Quote this is the `quote_digest` the API expects. */
+export function hashTypedData(typedData) {
+    return toHex(keccak_256(concat([
+        Uint8Array.of(0x19, 0x01),
+        hashStruct(domainTypes, "EIP712Domain", typedData.domain),
+        hashStruct(typedData.types, typedData.primaryType, typedData.message),
+    ])));
+}
+// ---------------------------------------------------------------------------
+// USDC (EIP-3009) authorizations: the wallet funding a deposit and the
+// sponsored payout of a Totalis withdrawal.
+const authorizationFields = [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+];
+export const usdcTypes = {
+    ReceiveWithAuthorization: authorizationFields,
+    TransferWithAuthorization: authorizationFields,
+};
+/** The USDC EIP-712 domain GET /v1/deployment publishes, in signer form. */
+export function usdcDomain(deployment) {
+    const { name, version, chain_id, verifying_contract } = deployment.usdc.eip712_domain;
+    return { name, version, chainId: BigInt(chain_id), verifyingContract: address(verifying_contract) };
+}
+/** The EIP-3009 nonce `ParlayVault.depositUserWithAuthorization` derives: keccak256(abi.encode(vault, chainId, from, salt, account)). */
+export function depositNonce(deployment, authorization) {
+    return toHex(keccak_256(concat([
+        uintWord(BigInt(address(deployment.vault_address))),
+        uintWord(BigInt(deployment.chain_id)),
+        uintWord(BigInt(address(authorization.from))),
+        bytes32(authorization.salt),
+        uintWord(BigInt(address(authorization.account))),
+    ])));
+}
+/** USDC ReceiveWithAuthorization that lets the vault pull a deposit from the wallet. */
+export function receiveWithAuthorizationTypedData(deployment, authorization) {
+    return {
+        domain: usdcDomain(deployment), types: { ReceiveWithAuthorization: authorizationFields }, primaryType: "ReceiveWithAuthorization",
+        message: {
+            from: address(authorization.from), to: address(deployment.vault_address), value: BigInt(authorization.value),
+            validAfter: BigInt(authorization.valid_after), validBefore: BigInt(authorization.valid_before), nonce: depositNonce(deployment, authorization),
+        },
+    };
+}
+/**
+ * The EIP-3009 nonce of a withdrawal's payout, derived from the create's
+ * Idempotency-Key: keccak256(abi.encode(keccak256("TOTALIS_PAYOUT_NONCE_V1"),
+ * chainId, vault, account, uint128(idempotencyKey))). Sign the payout under it;
+ * the venue derives the same bytes, so the signature is bound to that one request.
+ */
+export function payoutNonce(deployment, account, idempotencyKey) {
+    const key = idempotencyKey.replaceAll("-", "");
+    if (!/^[0-9a-f]{32}$/.test(key))
+        throw new TypeError("the Idempotency-Key is not a lowercase UUID");
+    return toHex(keccak_256(concat([
+        keccak_256(utf8.encode("TOTALIS_PAYOUT_NONCE_V1")),
+        uintWord(BigInt(deployment.chain_id)),
+        uintWord(BigInt(address(deployment.vault_address))),
+        uintWord(BigInt(address(account))),
+        uintWord(BigInt(`0x${key}`)),
+    ])));
+}
+/** USDC TransferWithAuthorization for a Totalis withdrawal payout, under the deployment's USDC domain. */
+export function transferWithAuthorizationTypedData(deployment, payout) {
+    return {
+        domain: usdcDomain(deployment), types: { TransferWithAuthorization: authorizationFields }, primaryType: "TransferWithAuthorization",
+        message: {
+            from: address(payout.from), to: address(payout.to), value: BigInt(payout.value),
+            validAfter: BigInt(payout.valid_after), validBefore: BigInt(payout.valid_before), nonce: toHex(bytes32(payout.nonce)),
+        },
+    };
+}
+/** Lowercase hex with v in {27, 28}: the venue rejects v = 0/1. Longer ERC-1271 signatures pass through. */
+export function canonicalSignature(signature) {
+    const lower = signature.toLowerCase();
+    if (!/^0x(?:[0-9a-f]{2})+$/.test(lower))
+        throw new TypeError("signature is not hex");
+    const v = lower.length === 132 ? Number.parseInt(lower.slice(130), 16) : undefined;
+    return (v === 0 || v === 1 ? `${lower.slice(0, 130)}${(v + 27).toString(16)}` : lower);
+}
+/** Sign with the account's signer and return the canonical signature the API expects. */
+export async function signTotalis(signer, typedData) {
+    return canonicalSignature(await signer.signTypedData(typedData));
+}
+/** The canonical EIP-712 type string, for checking a signer's encoding against the contract. */
+export function encodeType(primaryType) {
+    return structType(totalisTypes, primaryType);
+}
+// ---------------------------------------------------------------------------
+// The SIWE (EIP-4361) message an account owner personal-signs to issue an API
+// key (TT-1791). The server writes it; the client checks it before signing.
+const issueKeyStatement = "Issue a Totalis API key. It grants scoped API access, not financial signing authority.";
+export function issueKeyMessage(message) {
+    return `${message.domain} wants you to sign in with your Ethereum account:\n${message.address}\n\n${issueKeyStatement}\n\n` +
+        `URI: ${message.uri}\nVersion: 1\nChain ID: ${message.chainId}\nNonce: ${message.nonce}\nIssued At: ${message.issuedAt}\n` +
+        `Expiration Time: ${message.expirationTime}\nRequest ID: ${message.requestId}\nResources:\n${message.resources.map((resource) => `- ${resource}`).join("\n")}`;
+}
+const issueKeyPattern = new RegExp("^(?<domain>\\S+) wants you to sign in with your Ethereum account:\\n(?<address>0x[0-9a-fA-F]{40})\\n\\n" +
+    issueKeyStatement.replaceAll(".", "\\.") +
+    "\\n\\nURI: (?<uri>\\S+)\\nVersion: 1\\nChain ID: (?<chainId>[0-9]+)\\nNonce: (?<nonce>[0-9a-f]+)\\nIssued At: (?<issuedAt>\\S+)\\n" +
+    "Expiration Time: (?<expirationTime>\\S+)\\nRequest ID: (?<requestId>\\S+)\\nResources:\\n(?<resources>- \\S+(?:\\n- \\S+)*)$");
+/** Parse an issue_key message; throws unless it is exactly the server's template. */
+export function parseIssueKeyMessage(text) {
+    const groups = issueKeyPattern.exec(text)?.groups;
+    if (groups === undefined)
+        throw new TypeError("not a Totalis issue_key message");
+    const message = {
+        domain: groups.domain, address: groups.address, uri: groups.uri, chainId: groups.chainId, nonce: groups.nonce,
+        issuedAt: groups.issuedAt, expirationTime: groups.expirationTime, requestId: groups.requestId,
+        resources: groups.resources.split("\n").map((line) => line.slice(2)),
+    };
+    if (issueKeyMessage(message) !== text || !message.resources.includes("urn:totalis:purpose:issue_key")) {
+        throw new TypeError("not a Totalis issue_key message");
+    }
+    return message;
+}