@lamarge/sdk 0.0.0-stage → 0.1.0

package/dist/protocol/deployments.d.ts

@@ -0,0 +1,54 @@
+/** Addresses identify reviewed UUPS proxies, never implementations or values supplied by the API. */
+export type EscrowDeployment = Readonly<{
+    version: 5;
+    chainId: number;
+    address: string;
+}>;
+export type DeploymentManifest = readonly EscrowDeployment[];
+/** Reviewed deployments (contracts/README.md#deployments). */
+export declare const ESCROW_DEPLOYMENTS: DeploymentManifest;
+/** Retired v5 proxies are trusted for existing proofs, never new signatures. BSC's current proxy
+ * only lets owners close and withdraw, since Aster settles inside itself. */
+export declare const RETIRED_V5_DEPLOYMENTS: readonly [{
+    readonly version: 5;
+    readonly chainId: 56;
+    readonly address: "0x3100b7b49c0f9631c6af25877b5a4e13a47afad6";
+}, {
+    readonly version: 5;
+    readonly chainId: 999;
+    readonly address: "0xea5ba9e1c0f5dde572bc08f3af6a3e8b9db73734";
+}, {
+    readonly version: 5;
+    readonly chainId: 137;
+    readonly address: "0xea5ba9e1c0f5dde572bc08f3af6a3e8b9db73734";
+}, {
+    readonly version: 5;
+    readonly chainId: 56;
+    readonly address: "0xea5ba9e1c0f5dde572bc08f3af6a3e8b9db73734";
+}];
+export declare const ESCROW_PROOF_DEPLOYMENTS: DeploymentManifest;
+export declare function escrowDeployment(chainId: number, address: string, manifest?: DeploymentManifest): EscrowDeployment | undefined;
+/** Never derive or fund a receiver against an unpinned escrow, even if the API names it. */
+export declare function requireV5Deployment(chainId: number, address: string, manifest?: DeploymentManifest): EscrowDeployment;
+/** Signing domains of venues without escrow: Lighter's L2 chain id and zkLighter contract, BSC and Aster's vault. Quote sets of inventory held there are signed in them; nothing is ever sent to them. */
+export declare const VENUE_DOMAINS: readonly [{
+    readonly venue: "lighter";
+    readonly chainId: 304;
+    readonly address: "0x3b4d794a66304f130a4db8f2551b0070dfcf5ca7";
+}, {
+    readonly venue: "aster";
+    readonly chainId: 56;
+    readonly address: "0x128463a60784c4d3f46c23af3f65ed859ba87974";
+}];
+/** A quote set's domain: a reviewed escrow, or a pinned venue domain. */
+export declare function requireSigningDomain(chainId: number, address: string, manifest?: DeploymentManifest): void;
+/** A whole bundle is checked before its first prompt: each quote set's domain, and each funding or payment's escrow. */
+export declare function requireSigningDomains(items: readonly {
+    kind: string;
+    typed_data: {
+        domain: {
+            chainId: number;
+            verifyingContract: string;
+        };
+    };
+}[], manifest?: DeploymentManifest): void;

package/dist/protocol/deployments.js

@@ -0,0 +1,44 @@
+/** Reviewed deployments (contracts/README.md#deployments). */
+export const ESCROW_DEPLOYMENTS = Object.freeze([
+    { version: 5, chainId: 999, address: "0x3100b7b49c0f9631c6af25877b5a4e13a47afad6" },
+    { version: 5, chainId: 137, address: "0x3100b7b49c0f9631c6af25877b5a4e13a47afad6" },
+]);
+/** Retired v5 proxies are trusted for existing proofs, never new signatures. BSC's current proxy
+ * only lets owners close and withdraw, since Aster settles inside itself. */
+export const RETIRED_V5_DEPLOYMENTS = Object.freeze([
+    { version: 5, chainId: 56, address: "0x3100b7b49c0f9631c6af25877b5a4e13a47afad6" },
+    { version: 5, chainId: 999, address: "0xea5ba9e1c0f5dde572bc08f3af6a3e8b9db73734" },
+    { version: 5, chainId: 137, address: "0xea5ba9e1c0f5dde572bc08f3af6a3e8b9db73734" },
+    { version: 5, chainId: 56, address: "0xea5ba9e1c0f5dde572bc08f3af6a3e8b9db73734" },
+]);
+export const ESCROW_PROOF_DEPLOYMENTS = Object.freeze([...ESCROW_DEPLOYMENTS, ...RETIRED_V5_DEPLOYMENTS]);
+export function escrowDeployment(chainId, address, manifest = ESCROW_DEPLOYMENTS) {
+    return manifest.find(deployment => deployment.chainId === chainId && deployment.address.toLowerCase() === address.toLowerCase());
+}
+/** Never derive or fund a receiver against an unpinned escrow, even if the API names it. */
+export function requireV5Deployment(chainId, address, manifest = ESCROW_DEPLOYMENTS) {
+    const deployment = escrowDeployment(chainId, address, manifest);
+    if (deployment?.version !== 5)
+        throw new Error("The balance upgrade is not available on this venue yet");
+    return deployment;
+}
+/** Signing domains of venues without escrow: Lighter's L2 chain id and zkLighter contract, BSC and Aster's vault. Quote sets of inventory held there are signed in them; nothing is ever sent to them. */
+export const VENUE_DOMAINS = Object.freeze([
+    { venue: "lighter", chainId: 304, address: "0x3b4d794a66304f130a4db8f2551b0070dfcf5ca7" },
+    { venue: "aster", chainId: 56, address: "0x128463a60784c4d3f46c23af3f65ed859ba87974" },
+]);
+/** A quote set's domain: a reviewed escrow, or a pinned venue domain. */
+export function requireSigningDomain(chainId, address, manifest = ESCROW_DEPLOYMENTS) {
+    if (VENUE_DOMAINS.some(domain => domain.chainId === chainId && domain.address === address.toLowerCase()))
+        return;
+    requireV5Deployment(chainId, address, manifest);
+}
+/** A whole bundle is checked before its first prompt: each quote set's domain, and each funding or payment's escrow. */
+export function requireSigningDomains(items, manifest = ESCROW_DEPLOYMENTS) {
+    for (const { kind, typed_data: { domain } } of items) {
+        if (kind === "quote_set")
+            requireSigningDomain(domain.chainId, domain.verifyingContract, manifest);
+        else if (kind === "fund" || kind === "pay_take")
+            requireV5Deployment(domain.chainId, domain.verifyingContract, manifest);
+    }
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./consents.ts";
+export * from "./deployments.ts";
+export * from "./intents.ts";
+export * from "./lighter.ts";
+export * from "./protocol.ts";
+export * from "./validation.ts";

package/dist/protocol/index.js

@@ -0,0 +1,6 @@
+export * from "./consents.js";
+export * from "./deployments.js";
+export * from "./intents.js";
+export * from "./lighter.js";
+export * from "./protocol.js";
+export * from "./validation.js";

package/dist/protocol/intents.d.ts

@@ -0,0 +1,126 @@
+import { type Verified } from "./validation.ts";
+import { type SignItem, type QuoteIntent } from "./protocol.ts";
+/** `replace` names a position in the current set; without it, the quote adds a price level on `receive_venue`. */
+export type MakerQuoteIntent = {
+    receive_venue: string;
+    receive: string;
+    min_fill: string;
+    quote_validity_seconds?: number | null | undefined;
+    replace?: {
+        sequence: number;
+        index: number;
+    } | undefined;
+};
+/** Added capital comes from the linked wallet alone, or from one margin move of the whole deposit. */
+export type FundingSource = "wallet" | "venue";
+type MakerIntent = {
+    venue: string;
+    amount: string;
+    quote?: MakerQuoteIntent | null;
+    quote_identity_id?: string | null | undefined;
+    client_request_id: string;
+    funding_source: FundingSource;
+};
+export type MakerOrderSnapshot = {
+    id: string;
+    venue: string;
+    owner_address: string;
+    quote_signer: string;
+    quote_identity_id: string;
+    state: string;
+    revision: string;
+    last_sequence: number;
+    available_to_quote: string;
+    quote_set: {
+        sequence: number;
+        active: boolean;
+        valid_until: string;
+        expires_at: string;
+        quotes: (QuoteIntent & {
+            available: string;
+        })[];
+    } | null;
+};
+export type PreparedMaker = {
+    id: string;
+    client_request_id: string;
+    state: string;
+    venue: string;
+    order: MakerOrderSnapshot;
+    expires_at: string;
+    expected_revision: string;
+    sequence: number | null;
+    to_sign: SignItem[];
+    intent: {
+        amount: string;
+        quote: MakerQuoteIntent | null;
+        quote_identity_id: string;
+        funding_source: string;
+    };
+    funding: {
+        existing_available: string;
+        added_amount: string;
+        wallet_amount: string;
+        venue_amount: string;
+        idle_amount: string;
+    };
+};
+type MakerAuthority = {
+    owner: string;
+    quoteSigner: string;
+    quoteIdentityId: string;
+    operator: string;
+    recipient?: string;
+    existingOrder: MakerOrderSnapshot | null;
+};
+/** Bind all new capital and the complete replacement quote set before any wallet request. */
+export declare function checkMakerIntent<T extends PreparedMaker>(prepared: T, input: MakerIntent, authority: MakerAuthority, now?: number): asserts prepared is T & {
+    to_sign: Verified<SignItem[]>;
+};
+type TakeIntent = {
+    from: string;
+    to: string;
+    amount_in: string;
+    min_out: string;
+    max_parts?: number;
+};
+export type TakeFill = {
+    id: string;
+    order_id: string;
+    sequence: number;
+    role: string;
+    from_venue: string;
+    to_venue: string;
+    amount_in: string;
+    amount_out: string;
+    payer: string;
+    maker_recipient: string;
+    taker_recipient: string;
+    swap_id: string;
+    hashlock: string;
+    pay_by: string;
+    t1: string;
+    t2: string;
+};
+/** What a take from `venue` signs to pay: a transfer inside Aster or Lighter, an escrow `pay_take` elsewhere. */
+export declare const takePaymentKind: (venue: string) => string;
+type LighterTransfer = {
+    kind: string;
+    signer: string;
+    fill_id?: string | undefined;
+    typed_data: {
+        from_account_index: number;
+        amount: string;
+        memo: string;
+    };
+};
+/** A take's whole signing batch, as the API sends it. */
+type TakeItems = readonly (SignItem | LighterTransfer)[];
+/** A take paid from Lighter: the transfer the taker signs pays exactly its fill, from his linked account, named by its memo. */
+export declare function checkLighterTakeIntent(items: TakeItems, fills: TakeFill[], input: TakeIntent, payer: string, recipient: string, account: number, now?: number): void;
+/** A take paid from Aster: the taker's wallet signs a transfer of the fill's amount to the maker's
+ * account under the fill id, with a nonce far enough ahead for LaMarge to lock the maker and
+ * within Aster's nonce window. */
+export declare function checkAsterTakeIntent(items: TakeItems, fills: TakeFill[], input: TakeIntent, payer: string, recipient: string, now?: number): void;
+export declare function checkTakeIntent(items: SignItem[], fills: TakeFill[], input: TakeIntent, payer: string, recipient: string, now?: number): asserts items is Verified<SignItem[]>;
+export {};

package/dist/protocol/intents.js

@@ -0,0 +1,141 @@
+import { fillMemo } from "./lighter.js";
+import { required } from "./validation.js";
+import { asterTransfer, CHAINS, checkAsterTransfer, checkDeadline, checkEscrowTyped, checkSignedQuote, checkWithdrawal, insist, MAKER_TIMEOUT_SECONDS, NEVER_VALID_UNTIL, same, takePayments, TAKER_TIMEOUT_SECONDS, uint, venueUnits, withdrawalCost } from "./protocol.js";
+/** Bind all new capital and the complete replacement quote set before any wallet request. */
+export function checkMakerIntent(prepared, input, authority, now = Date.now() / 1000) {
+    const { owner, quoteSigner, quoteIdentityId, operator, existingOrder } = authority;
+    const { order, funding, intent, to_sign: items } = prepared;
+    insist(/^0x[0-9a-fA-F]{40}$/.test(operator), "The deployment operator has not been configured");
+    insist(prepared.state === "preparing" && prepared.id.length > 0 && prepared.client_request_id === input.client_request_id && input.client_request_id.length > 0 && prepared.venue === input.venue);
+    insist(order.venue === input.venue && same(order.owner_address, owner) && same(order.quote_signer, quoteSigner) && order.quote_identity_id === quoteIdentityId && (!input.quote_identity_id || input.quote_identity_id === quoteIdentityId));
+    insist(intent.amount === input.amount && intent.quote_identity_id === quoteIdentityId && intent.funding_source === input.funding_source && prepared.expected_revision === order.revision);
+    checkDeadline(Math.floor(Date.parse(prepared.expires_at) / 1000), 3600, now);
+    const asked = input.quote ?? null, echoed = intent.quote;
+    insist(asked === null ? echoed === null : echoed !== null && echoed.receive_venue === asked.receive_venue && echoed.receive === asked.receive && echoed.min_fill === asked.min_fill && (echoed.quote_validity_seconds ?? 0) === (asked.quote_validity_seconds ?? 0) && echoed.replace?.sequence === asked.replace?.sequence && echoed.replace?.index === asked.replace?.index);
+    insist(!asked?.replace || existingOrder?.quote_set?.sequence === asked.replace.sequence, "Quotes changed; review again");
+    if (existingOrder) {
+        insist(same(order.id, existingOrder.id) && existingOrder.venue === input.venue && same(existingOrder.owner_address, owner) && same(existingOrder.quote_signer, quoteSigner) && existingOrder.quote_identity_id === quoteIdentityId);
+        insist(order.last_sequence === existingOrder.last_sequence && order.available_to_quote === existingOrder.available_to_quote && uint(order.revision) >= uint(existingOrder.revision), "Maker capital changed; review again");
+    }
+    else
+        insist(order.last_sequence === 0 && uint(order.available_to_quote) === 0n);
+    const amount = uint(input.amount), available = existingOrder ? uint(existingOrder.available_to_quote) : 0n;
+    const added = uint(funding.added_amount), idle = uint(funding.idle_amount), wallet = uint(funding.wallet_amount), venue = uint(funding.venue_amount), existing = uint(funding.existing_available);
+    const deposit = wallet + venue;
+    insist(amount > 0n && existing >= available && added === idle + deposit && (input.funding_source === "venue" ? wallet : venue) === 0n);
+    const kept = [];
+    // A deposit for a delegated quoter does not publish prices on its behalf.
+    const prior = existingOrder && !["closed", "failed"].includes(existingOrder.state) ? existingOrder.quote_set : null;
+    if ((asked || !input.quote_identity_id) && prior && Date.parse(prior.valid_until) / 1000 > now) {
+        for (const [index, q] of prior.quotes.entries()) {
+            const remaining = uint(q.available), supply = uint(q.supply), receive = uint(q.receive);
+            insist(remaining <= supply && remaining <= available);
+            if (remaining < uint(q.min_fill) || remaining === 0n)
+                continue;
+            kept.push({ venue: q.venue, recipient: q.recipient, supply: String(remaining), receive: String((remaining * receive + supply - 1n) / supply), min_fill: q.min_fill, index });
+        }
+    }
+    if (asked) {
+        // A venue's levels need capital for their sum; other venues share it. A change adds only
+        // the amount by which it raises that sum above both the available capital and the current sum.
+        const levels = kept.filter(q => q.venue === asked.receive_venue);
+        const before = levels.reduce((sum, q) => sum + uint(q.supply), 0n);
+        const after = levels.filter(q => q.index !== asked.replace?.index).reduce((sum, q) => sum + uint(q.supply), amount);
+        const covered = before > available ? before : available, spare = existing - available;
+        insist(added === (after > covered ? after - covered : 0n) && deposit === (added > spare ? added - spare : 0n));
+    }
+    else
+        insist(added === amount && idle === 0n);
+    const quotes = kept.filter(q => q.index !== asked?.replace?.index).map(({ index: _, ...q }) => q);
+    if (asked)
+        quotes.push({ venue: asked.receive_venue, recipient: required(authority.recipient), supply: input.amount, receive: asked.receive, min_fill: asked.min_fill });
+    // The server's stable order: by venue, a venue's levels as they were, a new one last.
+    quotes.sort((a, b) => a.venue < b.venue ? -1 : a.venue > b.venue ? 1 : 0);
+    const kinds = items.map(item => item.kind);
+    insist(new Set(kinds).size === kinds.length && kinds.includes("fund") === (added > 0n) && kinds.includes("quote_set") === (quotes.length > 0) && kinds.includes("margin_move") === (venue > 0n));
+    const sequence = prepared.sequence === null ? null : uint(prepared.sequence);
+    insist(quotes.length ? sequence !== null && sequence > BigInt(order.last_sequence) : sequence === null);
+    for (const item of items) {
+        const typed = item.typed_data, m = typed.message;
+        if (item.kind === "margin_move") {
+            // The wallet keeps what the move rounds up to whole millionths.
+            const moved = venueUnits(venue, input.venue);
+            insist(same(item.signer, owner) && withdrawalCost(input.venue, typed) === moved);
+            checkWithdrawal(typed, input.venue, owner, owner, moved, now);
+        }
+        else if (item.kind === "fund") {
+            checkEscrowTyped(typed, input.venue);
+            const floor = uint(m.minQuoteSequence);
+            insist(typed.primaryType === "FundOffer" && same(item.signer, owner) && same(m.owner, owner) && same(m.offerId, order.id) && uint(m.amount) === added && uint(m.deposit) === deposit && same(m.quoteSigner, quoteSigner) && same(m.operator, operator));
+            insist(floor > BigInt(order.last_sequence) && floor <= BigInt(Number.MAX_SAFE_INTEGER) && (sequence === null || floor === sequence));
+            checkDeadline(m.deadline, 3600, now);
+        }
+        else if (item.kind === "quote_set") {
+            const expiry = Number(uint(m.expiresAt)), validity = asked?.quote_validity_seconds ?? 0;
+            insist(Number.isSafeInteger(validity) && validity >= 0 && validity <= 300);
+            insist(!asked ? prior !== null && prior !== undefined && expiry === Math.floor(Date.parse(prior.expires_at) / 1000) : validity === 0 ? expiry === NEVER_VALID_UNTIL + MAKER_TIMEOUT_SECONDS + 1 : expiry > now + MAKER_TIMEOUT_SECONDS && expiry <= now + validity + MAKER_TIMEOUT_SECONDS + 31);
+            insist(sequence !== null && sequence <= BigInt(Number.MAX_SAFE_INTEGER));
+            checkSignedQuote(item, order, quotes, Number(sequence), expiry);
+        }
+        else
+            throw new Error("Unexpected maker signing operation");
+    }
+}
+/** What a take from `venue` signs to pay: a transfer inside Aster or Lighter, an escrow `pay_take` elsewhere. */
+export const takePaymentKind = (venue) => venue === "aster" ? "aster_transfer" : venue === "lighter" ? "lighter_transfer" : "pay_take";
+/** A take paid inside its venue buys exactly one fill, paid by one signed transfer that is the whole batch. */
+function checkVenueTake(items, kind, fills, input, payer, recipient, now) {
+    insist(takePaymentKind(input.from) === kind, "The signing request differs from the take's venue");
+    const item = items[0];
+    insist(items.length === 1 && fills.length === 1 && item?.kind === kind && same(item.signer, payer), "A take paid inside a venue is one transfer");
+    const fill = required(fills[0]);
+    insist(fill.role === "taker" && fill.from_venue === input.from && fill.to_venue === input.to && same(fill.payer, payer) && same(fill.taker_recipient, recipient) && item.fill_id === fill.id);
+    insist(BigInt(fill.amount_in) > 0n && BigInt(fill.amount_in) <= BigInt(input.amount_in) && BigInt(fill.amount_out) >= BigInt(input.min_out));
+    const payBy = Date.parse(fill.pay_by) / 1000, t1 = Date.parse(fill.t1) / 1000;
+    insist(payBy > now && payBy <= now + 90 && t1 > payBy && t1 <= now + MAKER_TIMEOUT_SECONDS + 30);
+    return { terms: item.typed_data, fill };
+}
+/** A take paid from Lighter: the transfer the taker signs pays exactly its fill, from his linked account, named by its memo. */
+export function checkLighterTakeIntent(items, fills, input, payer, recipient, account, now = Date.now() / 1000) {
+    const { terms, fill } = checkVenueTake(items, "lighter_transfer", fills, input, payer, recipient, now);
+    insist("memo" in terms && terms.from_account_index === account && terms.amount === fill.amount_in && terms.memo === fillMemo(fill.id), "The Lighter transfer differs from the take");
+}
+/** A take paid from Aster: the taker's wallet signs a transfer of the fill's amount to the maker's
+ * account under the fill id, with a nonce far enough ahead for LaMarge to lock the maker and
+ * within Aster's nonce window. */
+export function checkAsterTakeIntent(items, fills, input, payer, recipient, now = Date.now() / 1000) {
+    const { terms, fill } = checkVenueTake(items, "aster_transfer", fills, input, payer, recipient, now);
+    insist("domain" in terms, "Unexpected Aster transfer");
+    const transfer = asterTransfer(terms);
+    checkAsterTransfer(transfer, fill);
+    insist(transfer.nonce >= now + 20 && transfer.nonce <= now + 70, "The Aster transfer's nonce differs from the take");
+}
+export function checkTakeIntent(items, fills, input, payer, recipient, now = Date.now() / 1000) {
+    insist(takePaymentKind(input.from) === "pay_take", "The signing request differs from the take's venue");
+    insist(fills.length > 0 && fills.length <= (input.max_parts ?? 8) && new Set(fills.map(fill => fill.id)).size === fills.length && new Set(fills.map(fill => fill.swap_id.toLowerCase())).size === fills.length);
+    const totalIn = fills.reduce((sum, fill) => sum + BigInt(fill.amount_in), 0n);
+    const totalOut = fills.reduce((sum, fill) => sum + BigInt(fill.amount_out), 0n);
+    insist(totalIn > 0n && totalIn <= BigInt(input.amount_in) && totalOut >= BigInt(input.min_out));
+    const takes = items.filter(item => item.kind === "pay_take");
+    insist(takes.length === 1 && items.length === 1, "A reserved take must already be funded and authorized");
+    const take = required(takes[0]), typed = take.typed_data, m = typed.message;
+    checkEscrowTyped(typed, input.from);
+    insist(typed.primaryType === "PayTake" && same(take.signer, payer) && same(m.payer, payer) && take.fill_id !== undefined && fills.some(fill => fill.id === take.fill_id));
+    const payments = takePayments(typed);
+    insist(payments.length === fills.length);
+    const receive = CHAINS[input.to];
+    for (const fill of fills) {
+        insist(fill.role === "taker" && fill.from_venue === input.from && fill.to_venue === input.to && same(fill.payer, payer) && same(fill.taker_recipient, recipient) && BigInt(fill.amount_in) > 0n && BigInt(fill.amount_out) > 0n);
+        const t1 = Date.parse(fill.t1) / 1000, t2 = Date.parse(fill.t2) / 1000, payBy = Date.parse(fill.pay_by) / 1000;
+        insist(payBy > now && payBy <= now + 90 && t1 > payBy && t1 <= now + MAKER_TIMEOUT_SECONDS + 30 && t2 > t1 && t2 <= now + TAKER_TIMEOUT_SECONDS + 30);
+        const matching = payments.filter(payment => same(payment.swapId, fill.swap_id));
+        insist(matching.length === 1);
+        const p = required(matching[0]);
+        insist(same(p.payer, payer) && same(p.recipient, fill.maker_recipient) && same(p.hashlock, fill.hashlock) && /^0x[0-9a-f]{64}$/i.test(fill.hashlock) && uint(p.amount) === BigInt(fill.amount_in) && uint(p.refundAt) === BigInt(Math.floor(t2)) && uint(p.deadline) === BigInt(Math.floor(payBy)));
+        insist(uint(p.dex) === 0n || input.from === "hyperliquid" && uint(p.dex) === 4294967295n);
+        insist(same(p.orderId, fill.order_id) && uint(p.sequence) === BigInt(fill.sequence) && uint(p.amountOut) === BigInt(fill.amount_out) && same(p.receiveRecipient, recipient) && receive && uint(p.receiveChainId) === BigInt(receive.id) && same(p.receiveToken, receive.token) && same(p.receiveEscrow, receive.escrow));
+    }
+    // Only the shortfall is pulled from the payer. The allowance is reusable, but no unrelated operation is signed.
+    const deposit = uint(m.deposit);
+    insist(deposit <= totalIn);
+}

package/dist/protocol/lighter-constants.d.ts

@@ -0,0 +1,4 @@
+/** Poseidon2 round constants of Lighter's Goldilocks width-12 permutation (poseidon_crypto v0.0.15). */
+export declare const EXTERNAL: readonly (readonly bigint[])[];
+export declare const INTERNAL: readonly bigint[];
+export declare const DIAG: readonly bigint[];

package/dist/protocol/lighter-constants.js

@@ -0,0 +1,49 @@
+/** Poseidon2 round constants of Lighter's Goldilocks width-12 permutation (poseidon_crypto v0.0.15). */
+export const EXTERNAL = [
+    [0xd70193d17ab3b7d6n, 0xa2c3662a78a9162bn, 0x7a9fda827556ad44n, 0xe8d5501818c99643n, 0x4c7a8fced4d5fd38n, 0x55ab38985c0c513dn, 0x28a17bd016210b0bn, 0x8f8277679ec32fa8n, 0x768b3c3d68a460e9n, 0x872a022eb559d941n, 0xd1316dd4b3b97973n, 0xa7b608e578321000n],
+    [0x3fa02c87b0bee026n, 0x7a38f0022e13c31en, 0x00c054f3c5e8d20dn, 0x439f50f4bca7242fn, 0x4d0938aa57cd517fn, 0xb2e03ac5fb6b9a7dn, 0xe29d1f4237bedca8n, 0x05b7c844bc99b848n, 0x91cc0b73f34e17edn, 0x876e4427694bd755n, 0x67002ae0725c612dn, 0x05351f20e0b6315fn],
+    [0x2e3b9ef5457eb60bn, 0xd9ac17618c3783ddn, 0x0807528ad8874bcfn, 0xc78d546a455d2a0en, 0xf8b930c81e2481f0n, 0x712707d8dff3b041n, 0xdcb8c0aa0b9d34c3n, 0x9baddbdf2ee3a468n, 0x2dd16d50c5176c78n, 0x89eac5cfbc075cd3n, 0x2a741dea181587f3n, 0x1a4d6aa85a113d84n],
+    [0x4d736286a2387e34n, 0x8bad5dfc4fcb3ee3n, 0x84fbd03adb77c56an, 0x8d5cdd1a23ec53a2n, 0x036f08f08fff28ecn, 0xb717a3f4dbdfb443n, 0x58a074b5509d645cn, 0xf92bf834e4b87718n, 0x1541c3a0baa5ac4bn, 0x22149e6783e67692n, 0x9be8b5d9e112476fn, 0x41e0969f62babb76n],
+    [0xbc585ad3b9443dbbn, 0xf28dd3206975cbb1n, 0xdd8815e53ca045e0n, 0xde82c416b9e701ban, 0xc5cb875233afa025n, 0x7212697cd897ffa9n, 0x67844790aa63cfd7n, 0xdc0b9cfa97fe65c3n, 0xe8fe091869a82070n, 0x62902bb2e413c6d1n, 0x29f9f5001fb84f57n, 0xbe1014796ef5f8ben],
+    [0x71feb53e9bdba19cn, 0x251054f592ebb71cn, 0xe1a57643a4bb284bn, 0xa4ba6f87a45b739bn, 0x2c1fcade0b958c49n, 0xbbb424cda9a3e360n, 0x2ca647354c5f3f54n, 0xc9277b64d152e084n, 0xdbc9ac97445eff17n, 0x6f6cdf3198969f70n, 0x1de29d14fa76d8f1n, 0x73337458a8cc1d19n],
+    [0xb87e775e2fb3ab23n, 0xf166a1c7a565c80bn, 0xb24be06f426c747fn, 0xc281e8c49482ce00n, 0x51974c3b3b726c2dn, 0x87444cf8caf7d619n, 0x7c362f827a580cedn, 0x9567af14667647a0n, 0xcbf0473cbec54e37n, 0xe3209dedeff4f620n, 0xd43ad94e45a4c4een, 0x976981ee73f41768n],
+    [0xef707a224e207258n, 0x2fc779e10e6362een, 0x29b5ee60ad8c891fn, 0x96b37b39d8bfd667n, 0x877df68a8b22e733n, 0x5c41746f562c8d9fn, 0x0c9d76751052b71an, 0xfb3465341bf1c087n, 0xa0d14dc614d15eb1n, 0xdc27d17136906fa6n, 0x482e163b05ec397fn, 0x0273a462992366efn],
+];
+export const INTERNAL = [
+    0xa571418d95897b60n,
+    0x8f32676574fcf6d3n,
+    0x731102d4e3fb1bben,
+    0x0330f08328a82d2bn,
+    0x7f0449b6557f785dn,
+    0x62f06210658dcbcbn,
+    0xd5a98af9f89c458bn,
+    0x77ec69083a346385n,
+    0xef7ca48bbc27f890n,
+    0x53e9652f61eac532n,
+    0xa71c634abff4f0ccn,
+    0xb16f5f0d7e28ea29n,
+    0xc9dde31d0a003ab2n,
+    0x2ddadf9775902533n,
+    0xe4fa73fb16408b47n,
+    0x90242ebc00d2ee59n,
+    0xbb02dffd9f381982n,
+    0xdea328364c50907cn,
+    0x1395d3b924857cf8n,
+    0x7d3ead0d5aec04e6n,
+    0xc2f12be3fed74668n,
+    0x0ba3c338f8c3d285n,
+];
+export const DIAG = [
+    0xc3b6c08e23ba9300n,
+    0xd84b5de94a324fb6n,
+    0x0d0c371c5b35b84fn,
+    0x7964f570e7188037n,
+    0x5daf18bbd996604bn,
+    0x6743bc47b9595257n,
+    0x5528b9362c59bb70n,
+    0xac45e25b7127b68bn,
+    0xa2077d7dfbb606b5n,
+    0xf3faac6faee378aen,
+    0x0c6388b51545e883n,
+    0xd27dbb6944917b60n,
+];

package/dist/protocol/lighter.d.ts

@@ -0,0 +1,52 @@
+/** Lighter's L2 chain id, which every transaction hash names. */
+export declare const LIGHTER_CHAIN_ID: number;
+/** The API key index of LaMarge's key on a taker's account. */
+export declare const TAKER_API_KEY = 254;
+/** A maker bot's API key slot, `LIGHTER_API_KEY_INDEX`: 4 unless set, below LaMarge's taker key. */
+export declare function makerKeySlot(value?: string): number;
+/** A taker's transfer moves USDC between collateral routes. */
+export declare const USDC_ASSET = 3;
+export declare const COLLATERAL_ROUTE = 0;
+/** Lighter's public API, read directly so account data does not depend on LaMarge. */
+export declare const LIGHTER_API = "https://mainnet.zklighter.elliot.ai";
+/** The address owning Lighter account `index`, as Lighter's public API reads it. */
+export declare function lighterAccountOwner(index: number, signal?: AbortSignal, fetcher?: (url: string, init: RequestInit) => Promise<Response>): Promise<string>;
+/** Hashes field elements to five, without padding: each block of 8 overwrites the rate. */
+export declare function hashToFp5(input: readonly bigint[]): bigint[];
+/** An internal transfer, as LaMarge's key and the account's owner sign it. */
+export interface LighterTransfer {
+    from: number;
+    apiKey: number;
+    to: number;
+    asset: number;
+    fromRoute: number;
+    toRoute: number;
+    amount: bigint;
+    fee: bigint;
+    memo: Uint8Array;
+    expiredAt: number;
+    nonce: number;
+}
+/** An API key registration, which LaMarge's key and the account's owner sign. */
+interface LighterKeyRegistration {
+    account: number;
+    apiKey: number;
+    publicKey: Uint8Array;
+    nonce: number;
+}
+/** The 40-byte hash a transfer's API key signs, also its Lighter transaction hash. */
+export declare function transferHash(t: LighterTransfer, chainId?: number): Uint8Array;
+export declare const toHex: (bytes: Uint8Array) => string;
+export declare const fromHex: (hex: string) => Uint8Array<ArrayBuffer>;
+/** The memo naming a fill: its id's 16 bytes then 16 zero bytes, as hex. */
+export declare const fillMemo: (fill: string) => string;
+/** The text the owner signs with `personal_sign` for a transfer to another owner. */
+export declare const transferMessage: (t: LighterTransfer, chainId?: number) => string;
+/** The text the owner signs with `personal_sign` to register a key. */
+export declare const registrationMessage: (r: LighterKeyRegistration) => string;
+/** A sent transfer read back from its `tx_info`, without transaction attributes. */
+export declare function readTransferTxInfo(info: Record<string, unknown>): {
+    transfer: LighterTransfer;
+    l1Signature: string;
+};
+export {};

package/dist/protocol/lighter.js

@@ -0,0 +1,132 @@
+/**
+ * Lighter transaction hashes and owner messages for the browser. The taker's wallet signs the
+ * owner message (`L1Sig`) for what LaMarge's API key on its account signs; trade proofs are
+ * checked by the transfer's Poseidon2 hash. Port of `server/src/lighter_sig`, itself ported
+ * from Lighter's Go libraries and checked against their vectors.
+ */
+import { DIAG, EXTERNAL, INTERNAL } from "./lighter-constants.js";
+import { CHAINS } from "./protocol.js";
+import { required } from "./validation.js";
+/** Lighter's L2 chain id, which every transaction hash names. */
+export const LIGHTER_CHAIN_ID = required(CHAINS.lighter).id;
+/** The API key index of LaMarge's key on a taker's account. */
+export const TAKER_API_KEY = 254;
+/** A maker bot's API key slot, `LIGHTER_API_KEY_INDEX`: 4 unless set, below LaMarge's taker key. */
+export function makerKeySlot(value = "4") {
+    const slot = Number(value);
+    if (!Number.isInteger(slot) || slot < 4 || slot >= TAKER_API_KEY)
+        throw new Error(`LIGHTER_API_KEY_INDEX is a key slot from 4 to ${TAKER_API_KEY - 1}: ${TAKER_API_KEY} is LaMarge's taker key`);
+    return slot;
+}
+/** A taker's transfer moves USDC between collateral routes. */
+export const USDC_ASSET = 3;
+export const COLLATERAL_ROUTE = 0;
+/** Lighter's public API, read directly so account data does not depend on LaMarge. */
+export const LIGHTER_API = "https://mainnet.zklighter.elliot.ai";
+/** The address owning Lighter account `index`, as Lighter's public API reads it. */
+export async function lighterAccountOwner(index, signal, fetcher = fetch) {
+    const response = await fetcher(`${LIGHTER_API}/api/v1/account?by=index&value=${index}`, signal ? { signal } : {});
+    const body = response.ok ? await response.json() : undefined;
+    const accounts = typeof body === "object" && body !== null ? Reflect.get(body, "accounts") : undefined;
+    const account = Array.isArray(accounts) && accounts.length === 1 ? accounts[0] : undefined;
+    const owner = typeof account === "object" && account !== null && Reflect.get(account, "index") === index ? Reflect.get(account, "l1_address") : undefined;
+    if (typeof owner !== "string")
+        throw new Error(`Lighter account #${index} is unreadable`);
+    return owner;
+}
+/** An element of a fixed-size array; out of range is a bug. */
+function at(values, index) {
+    const value = values[index];
+    if (value === undefined)
+        throw new RangeError(`index ${index} out of range`);
+    return value;
+}
+const P = 0xffffffff00000001n;
+const add = (a, b) => (a + b) % P;
+const mul = (a, b) => (a * b) % P;
+/** Five field elements as 40 little-endian bytes. */
+const toBytes = (x) => {
+    const out = new Uint8Array(40);
+    x.forEach((limb, i) => { for (let j = 0; j < 8; j++)
+        out[i * 8 + j] = Number((limb >> BigInt(8 * j)) & 0xffn); });
+    return out;
+};
+// Poseidon2 over Goldilocks, width 12, rate 8, as Lighter's plonky2 variant.
+function externalLayer(state) {
+    const s = [...state];
+    for (let i = 0; i < 12; i += 4) {
+        const t01 = at(s, i) + at(s, i + 1), t23 = at(s, i + 2) + at(s, i + 3), t0123 = t01 + t23;
+        const x0 = at(s, i), x2 = at(s, i + 2);
+        s[i] = t0123 + t01 + at(s, i + 1);
+        s[i + 1] = t0123 + at(s, i + 1) + 2n * x2;
+        s[i + 2] = t0123 + t23 + at(s, i + 3);
+        s[i + 3] = t0123 + at(s, i + 3) + 2n * x0;
+    }
+    const sums = [0, 1, 2, 3].map(i => at(s, i) + at(s, i + 4) + at(s, i + 8));
+    for (let i = 0; i < 12; i++)
+        state[i] = (at(s, i) + at(sums, i % 4)) % P;
+}
+const sbox = (x) => { const x3 = mul(mul(x, x), x); return mul(mul(x3, x3), x); };
+function permute(state) {
+    externalLayer(state);
+    for (let round = 0; round < 8; round++) {
+        // The partial rounds sit between the two halves of the full rounds.
+        if (round === 4)
+            for (const constant of INTERNAL) {
+                state[0] = sbox(add(at(state, 0), constant));
+                const sum = state.reduce(add, 0n);
+                for (let i = 0; i < 12; i++)
+                    state[i] = add(sum, mul(at(state, i), at(DIAG, i)));
+            }
+        for (let i = 0; i < 12; i++)
+            state[i] = sbox(add(at(state, i), at(at(EXTERNAL, round), i)));
+        externalLayer(state);
+    }
+}
+/** Hashes field elements to five, without padding: each block of 8 overwrites the rate. */
+export function hashToFp5(input) {
+    const state = Array(12).fill(0n);
+    for (let i = 0; i < input.length; i += 8) {
+        input.slice(i, i + 8).forEach((x, j) => { state[j] = x; });
+        permute(state);
+    }
+    return state.slice(0, 5);
+}
+const MASK32 = 0xffffffffn;
+/** The 40-byte hash a transfer's API key signs, also its Lighter transaction hash. */
+export function transferHash(t, chainId = LIGHTER_CHAIN_ID) {
+    return toBytes(hashToFp5([BigInt(chainId), 12n, BigInt(t.nonce), BigInt(t.expiredAt), BigInt(t.from), BigInt(t.apiKey), BigInt(t.to),
+        BigInt(t.asset), BigInt(t.fromRoute), BigInt(t.toRoute), t.amount & MASK32, t.amount >> 32n, t.fee & MASK32, t.fee >> 32n]));
+}
+const hex10 = (value) => `0x${BigInt(value).toString(16).padStart(16, "0")}`;
+export const toHex = (bytes) => Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+export const fromHex = (hex) => Uint8Array.from(hex.match(/../g) ?? [], byte => parseInt(byte, 16));
+/** The memo naming a fill: its id's 16 bytes then 16 zero bytes, as hex. */
+export const fillMemo = (fill) => fill.replaceAll("-", "").toLowerCase().padEnd(64, "0");
+/** The text the owner signs with `personal_sign` for a transfer to another owner. */
+export const transferMessage = (t, chainId = LIGHTER_CHAIN_ID) => `Transfer\n\nnonce: ${hex10(t.nonce)}\nfrom: ${hex10(t.from)} (route ${hex10(t.fromRoute)})\napi key: ${hex10(t.apiKey)}\nto: ${hex10(t.to)} (route ${hex10(t.toRoute)})\nasset: ${hex10(t.asset)}\namount: ${hex10(t.amount)}\nfee: ${hex10(t.fee)}\nchainId: ${hex10(chainId)}\nmemo: ${toHex(t.memo)}\nOnly sign this message for a trusted client!`;
+/** The text the owner signs with `personal_sign` to register a key. */
+export const registrationMessage = (r) => `Register Lighter Account\n\npubkey: 0x${toHex(r.publicKey)}\nnonce: ${hex10(r.nonce)}\naccount index: ${hex10(r.account)}\napi key index: ${hex10(r.apiKey)}\nOnly sign this message for a trusted client!`;
+/** A sent transfer read back from its `tx_info`, without transaction attributes. */
+export function readTransferTxInfo(info) {
+    const integer = (name) => {
+        const value = info[name];
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+            throw new Error(`Lighter transfer ${name} is unreadable`);
+        return value;
+    };
+    const attributes = info.L2TxAttributes;
+    if (attributes !== null && attributes !== undefined && Object.keys(attributes).length > 0)
+        throw new Error("Lighter transfer attributes are not accepted");
+    const memo = info.Memo, l1 = info.L1Sig;
+    if (!Array.isArray(memo) || memo.length !== 32 || !memo.every(byte => Number.isInteger(byte) && byte >= 0 && byte < 256))
+        throw new Error("Lighter transfer memo is unreadable");
+    if (typeof l1 !== "string")
+        throw new Error("Lighter transfer owner signature is unreadable");
+    return {
+        transfer: { from: integer("FromAccountIndex"), apiKey: integer("ApiKeyIndex"), to: integer("ToAccountIndex"), asset: integer("AssetIndex"),
+            fromRoute: integer("FromRouteType"), toRoute: integer("ToRouteType"), amount: BigInt(integer("Amount")), fee: BigInt(integer("USDCFee")),
+            memo: Uint8Array.from(memo), expiredAt: integer("ExpiredAt"), nonce: integer("Nonce") },
+        l1Signature: l1,
+    };
+}