@totalis/hip4-client 0.75.0 → 0.76.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 `@totalis/hip4-client` follows [semantic versioning](https://semver.org).
 The contract version the generated types come from is `sdkVersion` in `./version`.
 
+## 0.76.0
+
+Vault agents (TT-2554), one Combo leg per question (TT-2605) and no legs on
+unpriced markets (TT-2606). Generated from contract
+`205.0.0-device-vault-agents`. Additive: 0.75 code runs unchanged, but
+`createRfq` now refuses two legs from one question and legs with a null
+`chance`.
+
+### Added
+
+- Vault agents (TT-2554). `agent` in `createTotalis` takes a key the account
+  granted; it then signs the account's `TakerAccept`, `SellBack`,
+  `CashoutTransfer` and Exits to HyperCore or the account's wallet instead of
+  `signer`, so those need no wallet prompt. `signer` still names the account
+  and signs USDC authorizations, HyperCore actions, grants and run-off claims.
+- `grantVaultAgent({ agent, validUntil })` has the account sign an
+  `AgentGrant` and relays it (`POST /v1/me/vault-agents`); `revokeVaultAgent`
+  sends `validUntil` 0, and `vaultAgents()` iterates the live agents.
+- `agentGrantTypedData` in `typed-data`, checked against the vault's vectors.
+- A grant or revoke's default nonce rises past any nonce this client sent
+  explicitly for that agent, so it isn't refused for not exceeding it.
+
+### Changed
+
+- `createRfq` refuses a Combo with two legs from one native question
+  (TT-2605): the second such leg is named in `field_violations` as
+  `/legs/{i}/outcome_id` with reason `SAME_QUESTION` (`400
+  INVALID_REQUEST`). Makers never quoted these legs, so such an RFQ used
+  to open and get no quotes. Allow one leg per `native_question_id` in your
+  slip; standalone markets have none and always combine.
+- `createRfq` refuses a leg whose market has a side with a null `chance`
+  (an empty, dust or one-sided book with no recent evidence), with reason
+  `CHANCE_UNAVAILABLE` on `/legs/{i}/outcome_id` (`400 INVALID_REQUEST`).
+  Makers price from the book, and on such a book one small order sets the
+  price. Show `chance`, not `value`, and treat `chance: null` as unpriced
+  (TT-2606).
+
 ## 0.75.0
 
 Maker capital on the stream (TT-2584), a stream that cannot hang in

package/dist/generated/openapi.d.ts

@@ -2843,7 +2843,7 @@ export type components = {
         readonly CreateRfqCommand: {
             /** @description Stake in atomic USDC (6 decimals), before taker fees; must be positive. Quotes carry the same stake. */
             readonly stake: components["schemas"]["$defs-Amount"];
-            /** @description 1 to 5 legs in strictly increasing outcome_id order. */
+            /** @description 1 to 5 legs in strictly increasing outcome_id order, at most one per native question. Every leg's market must have eligibility ENABLED and combo OPEN, and a chance on each side. */
             readonly legs: readonly components["schemas"]["$defs-Leg"][];
             /** @description Optional partner attribution code, from any credential. From an account a partner admitted, it must be one of that partner's active codes and needs no signature; with none, the partner's account code is recorded. From any other account it needs builder_authorization_expiry and builder_signature from the partner's registered signer and is honoured only from the code's registered browser origin, so an API-key request (no Origin) from such an account cannot send one. A refused code returns INVALID_REQUEST naming /builder_code. Revocation rejects new RFQs without vetoing an already-created RFQ. Partners get codes from Totalis. */
             readonly builder_code?: string;
@@ -9558,7 +9558,7 @@ export interface operations {
                     readonly "application/json": components["schemas"]["RfqCreated"];
                 };
             };
-            /** @description `INVALID_REQUEST`: the body is malformed, or a leg's market refuses new positions now. A refused leg is named in `field_violations` as `/legs/{i}/outcome_id`, and the message gives the reason, such as `REFERENCE_UNAVAILABLE` or `OUTSIDE_WINDOW`; the market's `eligibility` and `combo` show when it clears. */
+            /** @description `INVALID_REQUEST`: the body is malformed, or a leg's market refuses new positions now. A refused leg is named in `field_violations` as `/legs/{i}/outcome_id`, and the message gives the reason, such as `REFERENCE_UNAVAILABLE`, `OUTSIDE_WINDOW`, `CHANCE_UNAVAILABLE` for a side whose `chance` is null, or `SAME_QUESTION` for a leg whose `native_question_id` an earlier leg already has; the market's `eligibility` and `combo` show when it clears. */
             readonly 400: components["responses"]["Error"];
             readonly 401: components["responses"]["Error"];
             readonly 403: components["responses"]["Error"];

package/dist/generated/version.d.ts

@@ -1,5 +1,5 @@
 export declare const sdkVersion = "205.0.0-device-vault-agents";
-export declare const openapiSha256 = "e742feade28ca115077a4275e4a6260646278e9adcf0839987b8566a2221c8f5";
+export declare const openapiSha256 = "93141e0bf50949fc37ebceef7c64555eb50a70f69c71c89c8fdc12780e0dd168";
 export declare const realtimeSha256 = "1cac740e108e84ad1979f6ccc71089efd840404cb72d1612a86edc02769637e3";
 export declare const jsonSchemaSha256: {
     readonly "account.schema.json": "5106e2d53abef190990eff113f6692dd27df5848439cf5a80a42c11e89f2bef6";

package/dist/generated/version.js

@@ -1,6 +1,6 @@
 // Generated by scripts/generate.mjs; do not edit.
 export const sdkVersion = "205.0.0-device-vault-agents";
-export const openapiSha256 = "e742feade28ca115077a4275e4a6260646278e9adcf0839987b8566a2221c8f5";
+export const openapiSha256 = "93141e0bf50949fc37ebceef7c64555eb50a70f69c71c89c8fdc12780e0dd168";
 export const realtimeSha256 = "1cac740e108e84ad1979f6ccc71089efd840404cb72d1612a86edc02769637e3";
 export const jsonSchemaSha256 = {
     "account.schema.json": "5106e2d53abef190990eff113f6692dd27df5848439cf5a80a42c11e89f2bef6",

package/dist/totalis.d.ts

@@ -185,6 +185,15 @@ export type TotalisOptions = Omit<ApiClientOptions, "accessToken"> & {
     readonly accessToken: AccessToken;
     /** The account's signer (GET /v1/me `wallet`); required for flows that sign. Never stored. */
     readonly signer?: SignerInput;
+    /**
+     * A key the account granted as a vault agent (`grantVaultAgent`). When set,
+     * it signs the account's TakerAccept, SellBack, CashoutTransfer and Exits to
+     * its wallet or HyperCore instead of `signer`, so those need no wallet
+     * prompt. `signer` still names the account and signs everything else: USDC
+     * authorizations, HyperCore actions, grants and run-off claims. The venue
+     * refuses an agent whose grant ends before the signed expiry.
+     */
+    readonly agent?: SignerInput;
     /** Stream options; `subscription` adds account subscription fields such as `open_rfqs`. */
     readonly stream?: Omit<StreamOptions, "subscription" | "accessToken" | "environment" | "baseUrl" | "streamBaseUrl"> & {
         readonly subscription?: Omit<Extract<StreamSubscription, {
@@ -638,6 +647,27 @@ export declare function createTotalis(options: TotalisOptions): {
         readonly signal?: AbortSignal;
     }) => Promise<CoreExit>;
     directDepositCalls: (amount: Amount) => Promise<readonly WalletCall[]>;
+    grantVaultAgent: (request: {
+        readonly agent: string;
+        readonly validUntil: number | string;
+        readonly nonce?: number | string;
+        readonly idempotencyKey?: string;
+    }) => Promise<{
+        readonly operation_id: import("./generated/openapi.js").components["schemas"]["Hash32"];
+    }>;
+    revokeVaultAgent: (request: {
+        readonly agent: string;
+        readonly nonce?: number | string;
+        readonly idempotencyKey?: string;
+    }) => Promise<{
+        readonly operation_id: import("./generated/openapi.js").components["schemas"]["Hash32"];
+    }>;
+    vaultAgents: (limit?: number) => AsyncGenerator<{
+        readonly agent: import("./generated/openapi.js").components["schemas"]["Address"];
+        readonly valid_until: import("./generated/openapi.js").components["schemas"]["UInt64String"];
+        readonly nonce: import("./generated/openapi.js").components["schemas"]["UInt64String"];
+        readonly copy_agent: boolean;
+    }, void, any>;
     /** Render an RFQ's live quotes (entry or cash-out) from the stream; `[]` while the stream is down. */
     watchQuotes: (rfqId: string, listener: (quotes: readonly Quote[], serverNowMs: number) => void) => () => void;
     /** Issue a personal `ttk_` key; the signer must be the account wallet (embedded, or a wallet-only account's own). */

package/dist/totalis.js

@@ -7,7 +7,8 @@ import { spendableCash } from "./money.js";
 import { ApiError, backoffDelay, envelope, NetworkError, randomBytes32, resendable, retryingFetch, sendOnce, singleFetch, sleep, unwrap, uuidv7 } from "./request.js";
 import { toTotalisSigner } from "./signer.js";
 import { TotalisStream } from "./stream.js";
-import { address, cashoutTransferTypedData, exitTypedData, receiveWithAuthorizationTypedData, sellBackTypedData, takerAcceptTypedData, payoutNonce, transferWithAuthorizationTypedData, } from "./typed-data.js";
+import { items } from "./pagination.js";
+import { address, agentGrantTypedData, cashoutTransferTypedData, exitTypedData, receiveWithAuthorizationTypedData, sellBackTypedData, takerAcceptTypedData, payoutNonce, transferWithAuthorizationTypedData, } from "./typed-data.js";
 /**
  * What an entry's bridge may have moved to its wallet, by its state: nothing
  * before it is sent, once discarded or refused. Only `LANDED` proves it
@@ -314,7 +315,7 @@ function streamQuotes(stream, read) {
  * stream; HTTP reads recover after a reconnect or answer a doorbell.
  */
 export function createTotalis(options) {
-    const { environment, signer: signerInput, stream: streamOptions, streamBaseUrl, accessToken, ...clientOptions } = options;
+    const { environment, signer: signerInput, agent: agentInput, stream: streamOptions, streamBaseUrl, accessToken, ...clientOptions } = options;
     const client = audienceClient(environment, { ...clientOptions, accessToken });
     const keys = createApiKeyClient(environment, { ...clientOptions, accessToken });
     const stream = new TotalisStream({
@@ -337,6 +338,22 @@ export function createTotalis(options) {
     };
     const signer = signerInput === undefined ? undefined : toTotalisSigner(signerInput);
     const requireSigner = () => signer ?? Promise.reject(new Error("this flow needs a signer"));
+    const agent = agentInput === undefined ? undefined : toTotalisSigner(agentInput);
+    // The vault reverts a grant whose nonce does not exceed the agent's last, so
+    // two grants for one agent in one second (a grant, then its revoke) must not
+    // share one, and a default after an explicit nonce must exceed it too. The
+    // vault counts per agent, so the mark is per agent.
+    const lastGrantNonce = new Map();
+    const grantNonce = (agentAddress, explicit) => {
+        const last = lastGrantNonce.get(agentAddress) ?? 0n;
+        const clock = BigInt(now());
+        const nonce = explicit !== undefined ? BigInt(explicit) : clock > last ? clock : last + 1n;
+        if (nonce < 1n || nonce > 2n ** 64n - 1n)
+            throw new Error(`grant nonce ${nonce} is outside 1..2^64-1`);
+        if (nonce > last)
+            lastGrantNonce.set(agentAddress, nonce);
+        return String(nonce);
+    };
     let deploymentRead;
     const deployment = () => (deploymentRead ??= client.GET("/v1/deployment").then(unwrap).catch((error) => {
         deploymentRead = undefined;
@@ -585,7 +602,7 @@ export function createTotalis(options) {
         const signer = await requireSigner();
         const account = await signer.address();
         const chain = await deployment();
-        return { signer, account, chain, scope: { account, chainId: chain.chain_id, vault: address(chain.vault_address.toLowerCase()) } };
+        return { signer, vaultSigner: agent ?? signer, account, chain, scope: { account, chainId: chain.chain_id, vault: address(chain.vault_address.toLowerCase()) } };
     }
     /** A stored record signs nothing more, so without a signer the session's wallet (GET /v1/me) stands for the account. */
     async function checkScope(signed) {
@@ -626,14 +643,14 @@ export function createTotalis(options) {
     }
     async function signEntryWith(request, funding) {
         const { quote, cash } = request;
-        const { signer, account, chain, scope } = await recordScope();
+        const { signer, vaultSigner, account, chain, scope } = await recordScope();
         if (quote.entry.taker.toLowerCase() !== account)
             throw new Error("the quote is for another taker");
         const stake = BigInt(quote.entry.stake);
         const core = request.core === undefined || request.core === null ? request.core : BigInt(request.core);
         // Known cash is planned before any prompt, so a plan that fails asks the wallet for nothing.
         let plan = funding === "plan" && cash !== undefined ? planEntry(stake, core, cash) : undefined;
-        const signing = signer.signTypedData(takerAcceptTypedData(chain, quote.entry));
+        const signing = vaultSigner.signTypedData(takerAcceptTypedData(chain, quote.entry));
         if (funding === "plan" && cash === undefined) {
             // The quote signature names no amount, so the wallet signs it while the balances are read; a refusal stops the read and is the call's error.
             const reading = new AbortController();
@@ -682,12 +699,12 @@ export function createTotalis(options) {
     /** Sign a cash-out quote as the position's owner without sending it: the same SellBack or CashoutTransfer digest the maker signs. */
     async function signCashout(request) {
         const { quote } = request;
-        const { signer, account, chain, scope } = await recordScope();
+        const { vaultSigner, account, chain, scope } = await recordScope();
         const seller = quote.kind === "SELL_BACK" ? quote.sell_back.owner : quote.transfer.seller;
         if (seller.toLowerCase() !== account)
             throw new Error("the quote sells another owner's position");
         const typedData = quote.kind === "SELL_BACK" ? sellBackTypedData(chain, quote.sell_back) : cashoutTransferTypedData(chain, quote.transfer);
-        const taker_signature = await signer.signTypedData(typedData);
+        const taker_signature = await vaultSigner.signTypedData(typedData);
         return {
             kind: "CASHOUT", acceptanceId: request.acceptanceId ?? uuidv7(), rfqId: quote.rfq_id, quoteId: quote.quote_id, ...scope,
             positionId: termsOf(quote).position_id, command: { taker_signature },
@@ -913,7 +930,7 @@ export function createTotalis(options) {
         let vault_withdrawal;
         if (shortfall > 0n) {
             const exit = { amount: shortfall.toString(), expiry: String(issued + 600), salt: BigInt(randomBytes32()).toString() };
-            vault_withdrawal = { ...exit, signature: await signer.signTypedData(exitTypedData(chain, { account, to: account, ...exit })) };
+            vault_withdrawal = { ...exit, signature: await (agent ?? signer).signTypedData(exitTypedData(chain, { account, to: account, ...exit })) };
             deadline = issued + 600;
         }
         // The venue requires the payout to outlive the vault leg by 300 s; a minute more absorbs clock skew.
@@ -1065,7 +1082,7 @@ export function createTotalis(options) {
         const to = address(route.router_address.toLowerCase());
         // A minute inside the venue's maximum life absorbs clock skew.
         const exit = { amount: BigInt(request.amount).toString(), expiry: String(now() + Math.min(route.maximum_life_seconds - 60, 600)), salt: BigInt(randomBytes32()).toString() };
-        const signature = await signer.signTypedData(exitTypedData(chain, { account, to, ...exit }));
+        const signature = await (agent ?? signer).signTypedData(exitTypedData(chain, { account, to, ...exit }));
         const body = envelope({ account, to, ...exit, signature, purpose: request.purpose ?? "ORDER", ...(request.activationFeeAccepted ? { activation_fee_accepted: true } : {}) });
         return { exitId, account, body };
     }
@@ -1190,6 +1207,36 @@ export function createTotalis(options) {
             throw new Error(`core exit ${exitId} ended ${exit.status}, not credited on HyperCore`);
         return exit;
     }
+    /**
+     * Grant `agent`, a key one of the account's devices holds, as a vault agent
+     * until `validUntil` (unix seconds, at most 180 days away): the account's
+     * `signer` signs the AgentGrant and Totalis relays it to the vault, paying
+     * the gas. Pass that key as `agent` to sign accepts, cash-outs and Exits
+     * back to the account without a wallet prompt. The nonce defaults to the
+     * venue's clock in seconds, and rises past this client's last grant, so a
+     * later grant or revoke supersedes an earlier one. The
+     * 202 is admission: follow `operation_id` with `waitForOperation`; the agent
+     * signs once it lands. A resend of the same `idempotencyKey` returns the
+     * same operation.
+     */
+    async function grantVaultAgent(request) {
+        const signer = await requireSigner();
+        const account = address((await signer.address()).toLowerCase());
+        const agentAddress = address(request.agent.toLowerCase());
+        const grant = { account, agent: agentAddress, valid_until: String(request.validUntil), nonce: grantNonce(agentAddress, request.nonce) };
+        const signature = await signer.signTypedData(agentGrantTypedData(await deployment(), grant));
+        const key = request.idempotencyKey ?? uuidv7();
+        return sendOnce(() => client.POST("/v1/me/vault-agents", { params: { header: idempotency(key) },
+            body: { agent: grant.agent, valid_until: grant.valid_until, nonce: grant.nonce, signature } }));
+    }
+    /** The agent keeps signing until the revoke's operation lands; `waitForOperation` before treating it as gone. */
+    function revokeVaultAgent(request) {
+        return grantVaultAgent({ ...request, validUntil: 0 });
+    }
+    /** The account's live vault agents, every page; `copy_agent` marks a Combo copy agent's key. */
+    function vaultAgents(limit = 200) {
+        return items((query) => client.GET("/v1/me/vault-agents", { params: { query: { ...query, limit } } }).then(unwrap), (page) => page.agents);
+    }
     /**
      * The transactions a wallet sends itself to deposit USDC from HyperEVM into
      * its vault balance, paying its own gas: approve the vault for `amount`, then
@@ -1239,6 +1286,9 @@ export function createTotalis(options) {
         sendReturnToCore,
         returnToCore,
         directDepositCalls,
+        grantVaultAgent,
+        revokeVaultAgent,
+        vaultAgents,
         /** Render an RFQ's live quotes (entry or cash-out) from the stream; `[]` while the stream is down. */
         watchQuotes,
         /** Issue a personal `ttk_` key; the signer must be the account wallet (embedded, or a wallet-only account's own). */

package/dist/typed-data.d.ts

@@ -127,15 +127,34 @@ export declare const totalisTypes: {
         readonly name: "salt";
         readonly type: "uint256";
     }];
+    readonly AgentGrant: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly name: "agent";
+        readonly type: "address";
+    }, {
+        readonly name: "validUntil";
+        readonly type: "uint64";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint64";
+    }];
 };
 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. */
+/**
+ * Who signs each struct: the maker's signer, the taker's signer, or either
+ * side of a cash-out. A vault agent the account granted may sign the taker's
+ * TakerAccept, SellBack and CashoutTransfer, and an Exit back to the account;
+ * only the account itself signs an AgentGrant.
+ */
 export declare const signedBy: {
     readonly Quote: "maker";
     readonly TakerAccept: "taker";
     readonly SellBack: "maker_and_taker";
     readonly CashoutTransfer: "maker_and_taker";
     readonly Exit: "taker";
+    readonly AgentGrant: "taker";
 };
 /** The vault deployment a signature binds to: GET /v1/deployment. */
 export type TotalisDeployment = Pick<Schemas["Deployment"], "chain_id" | "vault_address">;
@@ -201,6 +220,17 @@ export declare function exitTypedData(deployment: TotalisDeployment, exit: {
     expiry: string;
     salt: string;
 }): TotalisTypedData<"Exit">;
+/**
+ * The account's grant to a vault agent: a key it holds signs for the account
+ * until `valid_until` (unix seconds, at most 180 days away; 0 revokes). The
+ * nonce must exceed the agent's last grant. Relay it with POST /v1/me/vault-agents.
+ */
+export declare function agentGrantTypedData(deployment: TotalisDeployment, grant: {
+    account: Hex;
+    agent: Hex;
+    valid_until: string;
+    nonce: string;
+}): TotalisTypedData<"AgentGrant">;
 export declare const domainTypes: {
     readonly EIP712Domain: readonly [{
         readonly name: "name";

package/dist/typed-data.js

@@ -47,14 +47,26 @@ export const totalisTypes = {
         { name: "expiry", type: "uint64" },
         { name: "salt", type: "uint256" },
     ],
+    AgentGrant: [
+        { name: "account", type: "address" },
+        { name: "agent", type: "address" },
+        { name: "validUntil", type: "uint64" },
+        { name: "nonce", type: "uint64" },
+    ],
 };
-/** Who signs each struct: the maker's signer, the taker's signer, or either side of a cash-out. */
+/**
+ * Who signs each struct: the maker's signer, the taker's signer, or either
+ * side of a cash-out. A vault agent the account granted may sign the taker's
+ * TakerAccept, SellBack and CashoutTransfer, and an Exit back to the account;
+ * only the account itself signs an AgentGrant.
+ */
 export const signedBy = {
     Quote: "maker",
     TakerAccept: "taker",
     SellBack: "maker_and_taker",
     CashoutTransfer: "maker_and_taker",
     Exit: "taker",
+    AgentGrant: "taker",
 };
 /** A 20-byte hex address, or a TypeError. */
 export function address(value) {
@@ -122,6 +134,17 @@ export function exitTypedData(deployment, exit) {
         message: { account: exit.account, to: exit.to, amount: BigInt(exit.amount), expiry: BigInt(exit.expiry), salt: BigInt(exit.salt) },
     };
 }
+/**
+ * The account's grant to a vault agent: a key it holds signs for the account
+ * until `valid_until` (unix seconds, at most 180 days away; 0 revokes). The
+ * nonce must exceed the agent's last grant. Relay it with POST /v1/me/vault-agents.
+ */
+export function agentGrantTypedData(deployment, grant) {
+    return {
+        domain: domain(deployment), types: { AgentGrant: totalisTypes.AgentGrant }, primaryType: "AgentGrant",
+        message: { account: address(grant.account), agent: address(grant.agent), validUntil: BigInt(grant.valid_until), nonce: BigInt(grant.nonce) },
+    };
+}
 // ---------------------------------------------------------------------------
 // EIP-712 hashing, so makers can compute quote_digest and every signer can be
 // checked against the contract's vectors without a wallet library.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalis/hip4-client",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "Totalis HIP-4 SDK: typed HTTP clients, signer-agnostic typed data, a retrying request layer, pagination, a realtime stream and taker/maker flows",
   "type": "module",
   "files": [