perp-cli 0.14.2 → 0.15.0

package/dist/exchanges/risex/session.d.ts

@@ -0,0 +1,71 @@
+/**
+ * RISEx signing context: the EIP-712 domain, the permit target (router) and the maintenance flag,
+ * fetched at runtime and checked against the per-network pins (typed-data.ts RISEX_PINS) before
+ * anything is signed. Also the master / signer nonce allocation and on-chain permission reads.
+ */
+import type { Network } from "../venue-types.js";
+import type { RisexClient } from "./client.js";
+import { type NonceSlot, type RisexDomain } from "./typed-data.js";
+export interface RisexSigningContext {
+    domain: RisexDomain;
+    router: string;
+    auth: string;
+}
+interface SystemConfig {
+    addresses?: {
+        router?: unknown;
+        auth?: unknown;
+    };
+    is_maintenance_mode?: unknown;
+    maintenance_message?: unknown;
+    maintenance_end_time?: unknown;
+}
+/** Refuse writes during venue maintenance (system config `is_maintenance_mode`). */
+export declare function assertNotMaintenance(cfg: SystemConfig): void;
+export declare function loadSigningContext(client: RisexClient, net: Network): Promise<RisexSigningContext>;
+/** Allocate (and burn) the next nonce pair for `account` (see nonce.ts). */
+export declare function allocateAccountNonce(client: RisexClient, net: Network, account: string, dir?: string): Promise<NonceSlot>;
+export interface RisexSessionKey {
+    /** uint32 unix seconds (word 0). */
+    expiration: number;
+    /** Permission bitmap (word 1); a new signer has 0xffffffff. */
+    bitmap: bigint;
+    /** 1 = Active, 3 = Revoked (word 2). */
+    status: number;
+}
+export interface RisexChainReader {
+    hasPermission(account: string, signer: string, permission: number): Promise<boolean>;
+    isNonceUsed(account: string, slot: NonceSlot): Promise<boolean>;
+    /** Raw `sessionKeys(account, signer)` (selector 0x96ade1f9): three 32-byte words. */
+    sessionKey(account: string, signer: string): Promise<RisexSessionKey>;
+    /** Whether permission id `id` exists (hasPermission does not revert for it). RPC failures throw. */
+    permissionIdExists(id: number): Promise<boolean>;
+    /** EIP-1967 implementation address of `proxy`. */
+    implementationOf(proxy: string): Promise<string>;
+    /** Authorization.getAccountRegistry(). */
+    accountRegistry(): Promise<string>;
+}
+/** Decode the 96-byte `sessionKeys` return (expiration, bitmap, status). */
+export declare function decodeSessionKey(raw: string): RisexSessionKey;
+/** What to do when a pinned RISEx contract changed (F4): everything signed is refused until re-review. */
+export declare function risexUpgradeRemediation(net: Network): string;
+/**
+ * The contracts perp-cli reviewed are still the ones deployed (read-only): the EIP-1967
+ * implementations of the Authorization, the router and the account registry, the registry address
+ * the Authorization reads, and no permission id ≥ 5. Any change → POLICY_DENIED (fail closed).
+ * The RISEx admin can upgrade any of them; this is the detection, not a prevention.
+ */
+export declare function assertReviewedContracts(chain: RisexChainReader, net: Network): Promise<void>;
+/**
+ * Prove on chain that `signer` can only trade for `account` (read-only):
+ *  1. assertReviewedContracts (pinned implementations of Authorization / router / account registry,
+ *     no permission id ≥ 5) — bits 5–31 of the bitmap, which a new signer holds and which cannot be
+ *     cleared, map to no permission while this holds;
+ *  2. the signer is Active and its raw bitmap's permission bits 0..4 are exactly {2} (trading);
+ *  3. hasPermission(0..4) agrees ({2} only) — so the verdict does not rest on the bit mapping alone.
+ * Throws POLICY_DENIED (never a default) when any check fails; RPC failures propagate.
+ */
+export declare function assertTradingOnlyOnChain(chain: RisexChainReader, net: Network, account: string, signer: string): Promise<RisexSessionKey>;
+/** Read-only on-chain reads against the pinned Authorization contract. */
+export declare function chainReader(net: Network): RisexChainReader;
+export {};

package/dist/exchanges/risex/session.js

@@ -0,0 +1,171 @@
+/**
+ * RISEx signing context: the EIP-712 domain, the permit target (router) and the maintenance flag,
+ * fetched at runtime and checked against the per-network pins (typed-data.ts RISEX_PINS) before
+ * anything is signed. Also the master / signer nonce allocation and on-chain permission reads.
+ */
+import { Interface, getAddress } from "ethers";
+import { PerpError } from "../../errors.js";
+import { assertRpcChainId, evmProvider } from "../../evm-master-tx.js";
+import { allocateNonce, parseRemoteNonceState } from "./nonce.js";
+import { assertPinned, EIP1967_IMPLEMENTATION_SLOT, RISEX_AUTH_IFACE, RISEX_PERMISSION_ID_MASK, RISEX_PERMISSION_IDS, RISEX_PINS, RISEX_TRADING_ONLY_BITS, RISEX_TRADING_PERMISSION, } from "./typed-data.js";
+/** Refuse writes during venue maintenance (system config `is_maintenance_mode`). */
+export function assertNotMaintenance(cfg) {
+    if (cfg.is_maintenance_mode === true) {
+        const end = typeof cfg.maintenance_end_time === "string" && /^\d+$/.test(cfg.maintenance_end_time)
+            ? new Date(Number(cfg.maintenance_end_time) * 1000).toISOString() : null;
+        throw new PerpError("EXCHANGE_UNREACHABLE", `RISEx is in maintenance${typeof cfg.maintenance_message === "string" && cfg.maintenance_message !== "" ? `: ${cfg.maintenance_message}` : ""} — nothing was sent`, {
+            exchange: "risex", sent: false, remediation: end !== null ? `Retry after ${end}` : "Retry after the maintenance window",
+        });
+    }
+}
+export async function loadSigningContext(client, net) {
+    const [d, cfg] = await Promise.all([
+        client.get("/v1/auth/eip712-domain"),
+        client.get("/v1/system/config"),
+    ]);
+    if (typeof d.name !== "string" || typeof d.version !== "string" || typeof d.chain_id !== "string" || typeof d.verifying_contract !== "string") {
+        throw new PerpError("EXCHANGE_ERROR", "RISEx /v1/auth/eip712-domain: malformed response", { exchange: "risex" });
+    }
+    const router = cfg.addresses?.router;
+    const auth = cfg.addresses?.auth;
+    if (typeof router !== "string" || typeof auth !== "string") {
+        throw new PerpError("EXCHANGE_ERROR", "RISEx /v1/system/config: no addresses.router / addresses.auth", { exchange: "risex" });
+    }
+    const domain = { name: d.name, version: d.version, chainId: Number(d.chain_id), verifyingContract: d.verifying_contract };
+    assertPinned(net, domain, router, auth);
+    assertNotMaintenance(cfg);
+    return { domain, router, auth };
+}
+/** Allocate (and burn) the next nonce pair for `account` (see nonce.ts). */
+export function allocateAccountNonce(client, net, account, dir) {
+    return allocateNonce(net, account, async () => parseRemoteNonceState(await client.get(`/v1/nonce-state/${account.toLowerCase()}`)), dir);
+}
+/** Decode the 96-byte `sessionKeys` return (expiration, bitmap, status). */
+export function decodeSessionKey(raw) {
+    if (!/^0x[0-9a-fA-F]{192}$/.test(raw)) {
+        throw new PerpError("EXCHANGE_ERROR", `RISEx sessionKeys returned ${raw.length} hex chars (expected 3 words)`, { exchange: "risex" });
+    }
+    const word = (k) => BigInt(`0x${raw.slice(2 + 64 * k, 66 + 64 * k)}`);
+    return { expiration: Number(word(0)), bitmap: word(1), status: Number(word(2)) };
+}
+/** What to do when a pinned RISEx contract changed (F4): everything signed is refused until re-review. */
+export function risexUpgradeRemediation(net) {
+    const n = net === "testnet" ? " -n testnet" : "";
+    return "Every signed RISEx action is refused through perp-cli until the new contract is reviewed — this includes cancel and cancel-all, which also go through a permit. " +
+        "Manage open orders and positions in the RISEx app (app.rise.trade). If you do not trust the new implementation, revoke the signer: " +
+        `perp${n} wallet agent revoke risex <name>. Update perp-cli once a release has reviewed the new implementation.`;
+}
+/**
+ * The contracts perp-cli reviewed are still the ones deployed (read-only): the EIP-1967
+ * implementations of the Authorization, the router and the account registry, the registry address
+ * the Authorization reads, and no permission id ≥ 5. Any change → POLICY_DENIED (fail closed).
+ * The RISEx admin can upgrade any of them; this is the detection, not a prevention.
+ */
+export async function assertReviewedContracts(chain, net) {
+    const pin = RISEX_PINS[net];
+    const refuse = (what) => new PerpError("POLICY_DENIED", `RISEx ${what} — its permission model must be re-reviewed before perp-cli signs anything`, {
+        exchange: "risex", remediation: risexUpgradeRemediation(net),
+    });
+    const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+    const [authImpl, routerImpl, registry] = await Promise.all([
+        chain.implementationOf(pin.auth), chain.implementationOf(pin.router), chain.accountRegistry(),
+    ]);
+    if (!same(authImpl, pin.authImplementation))
+        throw refuse(`Authorization contract was upgraded (implementation ${authImpl}, reviewed ${pin.authImplementation})`);
+    if (!same(routerImpl, pin.routerImplementation))
+        throw refuse(`router was upgraded (implementation ${routerImpl}, reviewed ${pin.routerImplementation})`);
+    if (!same(registry, pin.accountRegistry))
+        throw refuse(`Authorization now reads account registry ${registry} (reviewed ${pin.accountRegistry})`);
+    const registryImpl = await chain.implementationOf(pin.accountRegistry);
+    if (!same(registryImpl, pin.accountRegistryImplementation))
+        throw refuse(`account registry was upgraded (implementation ${registryImpl}, reviewed ${pin.accountRegistryImplementation})`);
+    if (await chain.permissionIdExists(RISEX_PERMISSION_IDS.length)) {
+        throw refuse(`now has permission id ${RISEX_PERMISSION_IDS.length}: signers approved by perp-cli may hold it (their bitmap bits ≥5 are set)`);
+    }
+}
+/**
+ * Prove on chain that `signer` can only trade for `account` (read-only):
+ *  1. assertReviewedContracts (pinned implementations of Authorization / router / account registry,
+ *     no permission id ≥ 5) — bits 5–31 of the bitmap, which a new signer holds and which cannot be
+ *     cleared, map to no permission while this holds;
+ *  2. the signer is Active and its raw bitmap's permission bits 0..4 are exactly {2} (trading);
+ *  3. hasPermission(0..4) agrees ({2} only) — so the verdict does not rest on the bit mapping alone.
+ * Throws POLICY_DENIED (never a default) when any check fails; RPC failures propagate.
+ */
+export async function assertTradingOnlyOnChain(chain, net, account, signer) {
+    await assertReviewedContracts(chain, net);
+    const sk = await chain.sessionKey(account, signer);
+    const low = sk.bitmap & RISEX_PERMISSION_ID_MASK;
+    const notTradingOnly = (why) => new PerpError("POLICY_DENIED", `RISEx signer ${signer} is not trading-only on chain (${why})`, {
+        exchange: "risex", signer, bitmap: `0x${sk.bitmap.toString(16)}`, status: sk.status,
+        remediation: "Revoke it (perp wallet agent revoke risex <name>) and approve a new signer",
+    });
+    if (sk.status !== 1 || low !== RISEX_TRADING_ONLY_BITS) {
+        throw notTradingOnly(`status ${sk.status}, permission bitmap 0x${sk.bitmap.toString(16)}, ids 0..4 = 0b${low.toString(2).padStart(5, "0")}, required 0b00100`);
+    }
+    const per = await Promise.all(RISEX_PERMISSION_IDS.map(async (id) => [id, await chain.hasPermission(account, signer, id)]));
+    const wrong = per.filter(([id, on]) => on !== (id === RISEX_TRADING_PERMISSION));
+    if (wrong.length > 0)
+        throw notTradingOnly(`hasPermission disagrees with the bitmap: ${wrong.map(([id, on]) => `${id}=${on}`).join(", ")}`);
+    return sk;
+}
+const SESSION_KEYS_IFACE = new Interface(["function sessionKeys(address account, address signer) view returns (bytes32, bytes32, bytes32)"]);
+const ZERO_ONE = "0x0000000000000000000000000000000000000001";
+const ZERO_TWO = "0x0000000000000000000000000000000000000002";
+const NONCE_IFACE_FN = "function isNonceUsed(address account, uint48 nonceAnchor, uint8 nonceBitmap) view returns (bool)";
+/** Read-only on-chain reads against the pinned Authorization contract. */
+export function chainReader(net) {
+    const pin = RISEX_PINS[net];
+    if (pin.rpcUrl === null) {
+        throw new PerpError("NOT_IMPLEMENTED", `RISEx ${net} has no known RPC endpoint`, { exchange: "risex" });
+    }
+    const rpc = evmProvider(pin.rpcUrl, pin.chainId);
+    const rpcUrl = pin.rpcUrl;
+    // The RPC must serve the pinned chain before any answer from it is trusted (same check as the sender).
+    let chainChecked = null;
+    const checked = () => (chainChecked ??= assertRpcChainId(rpc, rpcUrl, pin.chainId, "risex").catch(e => { chainChecked = null; throw e; }));
+    return {
+        async hasPermission(account, signer, permission) {
+            if (!RISEX_PERMISSION_IDS.includes(permission))
+                throw new PerpError("INVALID_PARAMS", `RISEx permission ${permission} is not 0..4`);
+            await checked();
+            const raw = await rpc.call({ to: pin.auth, data: RISEX_AUTH_IFACE.encodeFunctionData("hasPermission", [account, signer, permission]) });
+            return RISEX_AUTH_IFACE.decodeFunctionResult("hasPermission", raw)[0];
+        },
+        async sessionKey(account, signer) {
+            await checked();
+            return decodeSessionKey(await rpc.call({ to: pin.auth, data: SESSION_KEYS_IFACE.encodeFunctionData("sessionKeys", [account, signer]) }));
+        },
+        async permissionIdExists(id) {
+            await checked();
+            try {
+                await rpc.call({ to: pin.auth, data: RISEX_AUTH_IFACE.encodeFunctionData("hasPermission", [ZERO_ONE, ZERO_TWO, id]) });
+                return true;
+            }
+            catch (e) {
+                // A revert (enum decode of an unknown id) answers "no"; anything else is a failed read.
+                if (e.code === "CALL_EXCEPTION")
+                    return false;
+                throw e;
+            }
+        },
+        async implementationOf(proxy) {
+            await checked();
+            const word = await rpc.getStorage(proxy, EIP1967_IMPLEMENTATION_SLOT);
+            return getAddress(`0x${word.slice(-40)}`);
+        },
+        async accountRegistry() {
+            await checked();
+            const word = await rpc.call({ to: pin.auth, data: "0x0ab142ed" }); // getAccountRegistry()
+            if (!/^0x[0-9a-fA-F]{64}$/.test(word))
+                throw new PerpError("EXCHANGE_ERROR", "RISEx getAccountRegistry(): malformed return", { exchange: "risex" });
+            return getAddress(`0x${word.slice(-40)}`);
+        },
+        async isNonceUsed(account, slot) {
+            await checked();
+            const i = new Interface([NONCE_IFACE_FN]);
+            const raw = await rpc.call({ to: pin.auth, data: i.encodeFunctionData("isNonceUsed", [account, slot.anchor, slot.bit]) });
+            return i.decodeFunctionResult("isNonceUsed", raw)[0];
+        },
+    };
+}

package/dist/exchanges/risex/typed-data.d.ts

@@ -0,0 +1,173 @@
+/**
+ * RISEx EIP-712 typed data, action hashes and order packing (developer.rise.trade "Integration",
+ * checked by RISEx against the mainnet contracts on 2026-08-07).
+ *
+ * Every signature uses ONE domain: GET /v1/auth/eip712-domain (name "RISEx", version "1",
+ * chainId, verifyingContract = the Authorization contract = system-config `addresses.auth`).
+ * The permit `target` is the RISExUniversalRouter (`addresses.router`), never the auth contract.
+ * Both are pinned per network below and cross-checked at runtime: a mismatch refuses to sign.
+ *
+ * Type strings are hashed literally (no spaces). Golden typehashes (read off the mainnet
+ * Authorization contract) are asserted in tests.
+ *
+ * Signer permissions (Authorization contract, verified on mainnet 2026-10-14): `sessionKeys`
+ * stores a permission bitmap (new signers: 0xffffffff = all); `hasPermission(account, signer, p)`
+ * accepts p = 0..4. Every router action (place / cancel / cancel-all / leverage / margin) checks
+ * permission 2 (`verifyWitnessSignature(…, permission = 2, …)`, traced on mainnet router txs) —
+ * RISEX_TRADING_PERMISSION. perp-cli restricts a signer to trading-only by disabling every other
+ * permission with a `DisablePermission` signed by the SIGNER itself (typehash below, matched against
+ * the contract's DISABLE_PERMISSION_TYPEHASH(); a master-signed one reverts InvalidSignerSignature),
+ * sent on-chain by the master. EnablePermission must be signed by the account, so a signer cannot
+ * restore what it gave up (both checked by eth_call on testnet 2026-10-14). The calldata outcomes,
+ * revert selectors, the permission-id map and the router traces are recorded in
+ * src/__tests__/fixtures/risex/permissions-evidence.json (asserted by risex-evidence.test.ts). The
+ * implementation source is not verified on the explorer, so permission NAMES are unknown.
+ */
+import { Interface } from "ethers";
+import type { EvmSigner } from "../../signer/interface.js";
+import type { Network } from "../venue-types.js";
+export interface RisexPins {
+    chainId: number;
+    /** Authorization contract = EIP-712 verifyingContract. */
+    auth: string;
+    /** RISExUniversalRouter = permit target. */
+    router: string;
+    /** JSON-RPC for the on-chain permission restriction / reads; null = none known. */
+    rpcUrl: string | null;
+    /**
+     * EIP-1967 implementation of the Authorization proxy whose permission model was reviewed
+     * (ids 0..4; ids ≥5 rejected by ABI enum decoding). An upgrade refuses trading until re-reviewed.
+     */
+    authImplementation: string;
+    /** EIP-1967 implementation of the RISExUniversalRouter proxy (every permit-gated action). */
+    routerImplementation: string;
+    /** The account registry the Authorization contract reads (`getAccountRegistry()`; its getUserId is STATICCALLed by hasPermission / sessionKeys). */
+    accountRegistry: string;
+    /** EIP-1967 implementation of the account registry proxy. */
+    accountRegistryImplementation: string;
+}
+/** Verified 2026-10-14 from GET /v1/system/config and /v1/auth/eip712-domain on each network. */
+export declare const RISEX_PINS: Readonly<Record<Network, RisexPins>>;
+export interface RisexDomain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+/** Check a fetched domain + router against the pins. Throws EXCHANGE_ERROR (nothing is signed). */
+export declare function assertPinned(net: Network, domain: RisexDomain, router: string, auth: string): void;
+type Fields = Array<{
+    name: string;
+    type: string;
+}>;
+export declare const RISEX_TYPES: {
+    readonly RegisterSigner: Fields;
+    readonly VerifySigner: Fields;
+    readonly RevokeSigner: Fields;
+    readonly VerifyWitness: Fields;
+    readonly DisablePermission: Fields;
+};
+export type RisexPrimaryType = keyof typeof RISEX_TYPES;
+/** Canonical EIP-712 type string ("Name(type a,type b)"). */
+export declare function typeString(primary: RisexPrimaryType): string;
+export declare function typeHash(primary: RisexPrimaryType): string;
+/** Read off the mainnet Authorization contract (docs "Verification" + eth_call 2026-10-14). */
+export declare const RISEX_GOLDEN_TYPEHASHES: Readonly<Record<RisexPrimaryType, string>>;
+/** The permission every router action checks (place / cancel / cancel-all / leverage / margin). */
+export declare const RISEX_TRADING_PERMISSION = 2;
+/** EIP-1967 implementation slot (keccak256("eip1967.proxy.implementation") − 1). */
+export declare const EIP1967_IMPLEMENTATION_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+/**
+ * The low bits of `sessionKeys(account, signer)` word 1 that map to permission ids 0..4; a
+ * trading-only signer has exactly bit 2 set among them. Bits 5–31 (set to 1 on every new signer,
+ * bitmap 0xffffffff) have no permission id in the reviewed implementation: hasPermission and
+ * disablePermission both reject ids ≥5 at ABI decoding, so those bits can neither be read as a
+ * permission nor cleared. They are guarded instead by the implementation pin and the "no id 5" probe
+ * (assertTradingOnlyOnChain, session.ts).
+ */
+export declare const RISEX_PERMISSION_ID_MASK = 31n;
+export declare const RISEX_TRADING_ONLY_BITS: bigint;
+/** Valid permission ids (hasPermission reverts above 4). */
+export declare const RISEX_PERMISSION_IDS: readonly number[];
+/** Permissions perp-cli disables right after registration (all except trading). */
+export declare const RISEX_NON_TRADING_PERMISSIONS: readonly number[];
+export declare const RISEX_AUTH_IFACE: Interface;
+export declare const ACTION: {
+    readonly PLACE_ORDER: "RISE_PERPS_PLACE_ORDER_V1";
+    readonly CANCEL_ORDER: "RISE_PERPS_CANCEL_ORDER_V1";
+    readonly CANCEL_ALL_ORDERS: "RISE_PERPS_CANCEL_ALL_ORDERS_V1";
+    readonly UPDATE_LEVERAGE: "RISE_PERPS_UPDATE_LEVERAGE_V1";
+    readonly UPDATE_MARGIN_MODE: "RISE_PERPS_UPDATE_MARGIN_MODE_V1";
+};
+export declare const SIDE: {
+    readonly buy: 0;
+    readonly sell: 1;
+};
+export declare const ORDER_TYPE: {
+    readonly market: 0;
+    readonly limit: 1;
+};
+/** Venue TIF codes. ALO is GTC + post_only. */
+export declare const TIF_CODE: {
+    readonly GTC: 0;
+    readonly GTT: 1;
+    readonly FOK: 2;
+    readonly IOC: 3;
+};
+export declare const STP_EXPIRE_MAKER = 0;
+export declare const MARGIN_MODE_CODE: {
+    readonly cross: 0;
+    readonly isolated: 1;
+};
+export interface PackedOrderFields {
+    marketId: number;
+    sizeSteps: bigint;
+    priceTicks: bigint;
+    side: 0 | 1;
+    postOnly: boolean;
+    reduceOnly: boolean;
+    stpMode: number;
+    orderType: 0 | 1;
+    tif: 0 | 1 | 2 | 3;
+}
+/** uint88 order word: [87:70] market, [69:38] size steps, [37:14] price ticks, [13:6] flags, [5:1] version 1. */
+export declare function packOrder(o: PackedOrderFields): bigint;
+/** Inverse of packOrder (tests / diagnostics). */
+export declare function unpackOrder(word: bigint): PackedOrderFields & {
+    version: number;
+};
+/** Header flags: 0x01 permit (always), 0x04 client order id present. Builder (0x02) / TTL (0x10) are never sent. */
+export declare function headerFlags(clientOrderId: bigint): number;
+/** keccak256(abi.encode(sel, uint8 header, uint88 order, uint16 builderId=0, uint64 clientOrderId, uint16 ttl=0)). */
+export declare function placeOrderHash(order: bigint, clientOrderId: bigint): string;
+export declare function cancelOrderHash(marketId: number, restingOrderId: bigint): string;
+export declare function cancelAllHash(marketId: number): string;
+export declare function leverageHash(marketId: number, leverage: number): string;
+export declare function marginModeHash(marketId: number, mode: 0 | 1): string;
+export interface NonceSlot {
+    anchor: bigint;
+    bit: number;
+}
+export interface RisexPermit {
+    account: string;
+    signer: string;
+    nonce_anchor: string;
+    nonce_bitmap_index: number;
+    deadline: number;
+    signature: string;
+}
+/** Sign typed data and verify it recovers `expected` (an OWS canonicalization slip never leaves this process). */
+export declare function signChecked(signer: EvmSigner, domain: RisexDomain, primary: RisexPrimaryType, message: Record<string, unknown>): Promise<string>;
+/** 65-byte r‖s‖v hex → base64 (the permit field is protobuf bytes). */
+export declare function permitSignatureBase64(hexSig: string): string;
+/** The signer's VerifyWitness permit for one action hash. */
+export declare function signPermit(p: {
+    signer: EvmSigner;
+    account: string;
+    router: string;
+    domain: RisexDomain;
+    actionHash: string;
+    slot: NonceSlot;
+    deadline: number;
+}): Promise<RisexPermit>;
+export {};

package/dist/exchanges/risex/typed-data.js

@@ -0,0 +1,240 @@
+/**
+ * RISEx EIP-712 typed data, action hashes and order packing (developer.rise.trade "Integration",
+ * checked by RISEx against the mainnet contracts on 2026-08-07).
+ *
+ * Every signature uses ONE domain: GET /v1/auth/eip712-domain (name "RISEx", version "1",
+ * chainId, verifyingContract = the Authorization contract = system-config `addresses.auth`).
+ * The permit `target` is the RISExUniversalRouter (`addresses.router`), never the auth contract.
+ * Both are pinned per network below and cross-checked at runtime: a mismatch refuses to sign.
+ *
+ * Type strings are hashed literally (no spaces). Golden typehashes (read off the mainnet
+ * Authorization contract) are asserted in tests.
+ *
+ * Signer permissions (Authorization contract, verified on mainnet 2026-10-14): `sessionKeys`
+ * stores a permission bitmap (new signers: 0xffffffff = all); `hasPermission(account, signer, p)`
+ * accepts p = 0..4. Every router action (place / cancel / cancel-all / leverage / margin) checks
+ * permission 2 (`verifyWitnessSignature(…, permission = 2, …)`, traced on mainnet router txs) —
+ * RISEX_TRADING_PERMISSION. perp-cli restricts a signer to trading-only by disabling every other
+ * permission with a `DisablePermission` signed by the SIGNER itself (typehash below, matched against
+ * the contract's DISABLE_PERMISSION_TYPEHASH(); a master-signed one reverts InvalidSignerSignature),
+ * sent on-chain by the master. EnablePermission must be signed by the account, so a signer cannot
+ * restore what it gave up (both checked by eth_call on testnet 2026-10-14). The calldata outcomes,
+ * revert selectors, the permission-id map and the router traces are recorded in
+ * src/__tests__/fixtures/risex/permissions-evidence.json (asserted by risex-evidence.test.ts). The
+ * implementation source is not verified on the explorer, so permission NAMES are unknown.
+ */
+import { AbiCoder, Interface, Signature, getAddress, keccak256, toUtf8Bytes, verifyTypedData } from "ethers";
+import { PerpError } from "../../errors.js";
+import { UINT24_MAX, UINT32_MAX, UINT64_MAX } from "./units.js";
+/** Verified 2026-10-14 from GET /v1/system/config and /v1/auth/eip712-domain on each network. */
+export const RISEX_PINS = {
+    mainnet: {
+        chainId: 4153,
+        auth: "0x0D919DAA3f12AE715744Eb648c00066c5DBd66f0",
+        router: "0xaadde0cea454f2bcb26f46ed54c5709b7bb34a7e",
+        rpcUrl: "https://rpc.risechain.com",
+        // eth_getStorageAt(auth, EIP-1967 implementation slot), 2026-10-14.
+        authImplementation: "0xCCCb0483342d77AbC4337f3e12514eC8E78b3e28",
+        routerImplementation: "0xe2da7a94a81fe9ee58f70ebce862a176280092ae",
+        accountRegistry: "0x1238991cac4e65902c08213e79909a9c813eebc3",
+        accountRegistryImplementation: "0x531a0c7687cbaf02383b21443619487eb18b91e5",
+    },
+    testnet: {
+        chainId: 11155931,
+        auth: "0x6da86f486b5e6536358f5b122dbe184522ca0ee3",
+        router: "0x980b8621b8e03c3f396e1dc34c00b14d84f2a20f",
+        // eth_chainId 0xaa39db = 11155931 (verified); the testnet system config lists no RPC.
+        rpcUrl: "https://testnet.riselabs.xyz",
+        authImplementation: "0xc5b84461547eb5397a7c3fd067abfcbc24b53663",
+        routerImplementation: "0x9218cd0d7626d9611b62e55dc3659936f9e57f68",
+        accountRegistry: "0xf733038054cfb47fa9da1a1d6e79be6fb61f0a70",
+        accountRegistryImplementation: "0x99ccc05d52b69bd889a8ab4bc7c12b47aca94b58",
+    },
+};
+/** Check a fetched domain + router against the pins. Throws EXCHANGE_ERROR (nothing is signed). */
+export function assertPinned(net, domain, router, auth) {
+    const pin = RISEX_PINS[net];
+    const problems = [];
+    if (domain.name !== "RISEx" || domain.version !== "1")
+        problems.push(`domain ${domain.name}/${domain.version} (expected RISEx/1)`);
+    if (domain.chainId !== pin.chainId)
+        problems.push(`chainId ${domain.chainId} (pinned ${pin.chainId})`);
+    if (domain.verifyingContract.toLowerCase() !== pin.auth.toLowerCase())
+        problems.push(`verifyingContract ${domain.verifyingContract} (pinned ${pin.auth})`);
+    if (auth.toLowerCase() !== pin.auth.toLowerCase())
+        problems.push(`addresses.auth ${auth} (pinned ${pin.auth})`);
+    if (router.toLowerCase() !== pin.router.toLowerCase())
+        problems.push(`addresses.router ${router} (pinned ${pin.router})`);
+    if (problems.length > 0) {
+        throw new PerpError("EXCHANGE_ERROR", `RISEx ${net} signing configuration changed: ${problems.join("; ")} — nothing was signed`, {
+            exchange: "risex",
+            remediation: "RISEx redeployed or changed its contracts. perp-cli refuses to sign against unpinned addresses; update perp-cli (RISEX_PINS)",
+        });
+    }
+}
+export const RISEX_TYPES = {
+    RegisterSigner: [
+        { name: "account", type: "address" }, { name: "signer", type: "address" }, { name: "message", type: "string" },
+        { name: "expiration", type: "uint32" }, { name: "nonceAnchor", type: "uint48" }, { name: "nonceBitmap", type: "uint8" },
+    ],
+    VerifySigner: [
+        { name: "account", type: "address" }, { name: "nonceAnchor", type: "uint48" }, { name: "nonceBitmap", type: "uint8" },
+    ],
+    RevokeSigner: [
+        { name: "account", type: "address" }, { name: "signer", type: "address" },
+        { name: "nonceAnchor", type: "uint48" }, { name: "nonceBitmap", type: "uint8" },
+    ],
+    VerifyWitness: [
+        { name: "account", type: "address" }, { name: "target", type: "address" }, { name: "hash", type: "bytes32" },
+        { name: "nonceAnchor", type: "uint48" }, { name: "nonceBitmap", type: "uint8" }, { name: "deadline", type: "uint32" },
+    ],
+    DisablePermission: [
+        { name: "account", type: "address" }, { name: "signer", type: "address" }, { name: "permission", type: "uint8" },
+        { name: "nonceAnchor", type: "uint48" }, { name: "nonceBitmap", type: "uint8" },
+    ],
+};
+/** Canonical EIP-712 type string ("Name(type a,type b)"). */
+export function typeString(primary) {
+    return `${primary}(${RISEX_TYPES[primary].map(f => `${f.type} ${f.name}`).join(",")})`;
+}
+export function typeHash(primary) {
+    return keccak256(toUtf8Bytes(typeString(primary)));
+}
+/** Read off the mainnet Authorization contract (docs "Verification" + eth_call 2026-10-14). */
+export const RISEX_GOLDEN_TYPEHASHES = {
+    RegisterSigner: "0xa526f63b3968e56ae1b177ce9b3dc29766e0891e6397a9c23cf8c53ee8fc8f62",
+    VerifySigner: "0x4d298dcceb691695f582cc337308236426a0c97201a31834625e8eadc44d4230",
+    RevokeSigner: "0x36db7f392f548b56f37d89469115d138685addf06be45684f9e5b0e8b5d28000",
+    VerifyWitness: "0x055e6bcbf2ba5ff1c2ba5dc95b6648a5de6aaab3185251a34e3b88c11e116821",
+    DisablePermission: "0xd0246e99c52bee7c7802e154da708a9795b727ad05cb8463639505c1baf0f897",
+};
+// ── Permissions ──
+/** The permission every router action checks (place / cancel / cancel-all / leverage / margin). */
+export const RISEX_TRADING_PERMISSION = 2;
+/** EIP-1967 implementation slot (keccak256("eip1967.proxy.implementation") − 1). */
+export const EIP1967_IMPLEMENTATION_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+/**
+ * The low bits of `sessionKeys(account, signer)` word 1 that map to permission ids 0..4; a
+ * trading-only signer has exactly bit 2 set among them. Bits 5–31 (set to 1 on every new signer,
+ * bitmap 0xffffffff) have no permission id in the reviewed implementation: hasPermission and
+ * disablePermission both reject ids ≥5 at ABI decoding, so those bits can neither be read as a
+ * permission nor cleared. They are guarded instead by the implementation pin and the "no id 5" probe
+ * (assertTradingOnlyOnChain, session.ts).
+ */
+export const RISEX_PERMISSION_ID_MASK = 0x1fn;
+export const RISEX_TRADING_ONLY_BITS = 1n << 2n;
+/** Valid permission ids (hasPermission reverts above 4). */
+export const RISEX_PERMISSION_IDS = [0, 1, 2, 3, 4];
+/** Permissions perp-cli disables right after registration (all except trading). */
+export const RISEX_NON_TRADING_PERMISSIONS = RISEX_PERMISSION_IDS.filter(p => p !== RISEX_TRADING_PERMISSION);
+export const RISEX_AUTH_IFACE = new Interface([
+    "function disablePermission(address account, address signer, uint48 nonceAnchor, uint8 nonceBitmap, uint8 permission, bytes signature)",
+    "function hasPermission(address account, address signer, uint8 permission) view returns (bool)",
+    "function getSessionKeyStatus(address account, address signer) view returns (uint8)",
+]);
+// ── Action hashes ──
+const coder = AbiCoder.defaultAbiCoder();
+const selector = (name) => keccak256(toUtf8Bytes(name));
+export const ACTION = {
+    PLACE_ORDER: "RISE_PERPS_PLACE_ORDER_V1",
+    CANCEL_ORDER: "RISE_PERPS_CANCEL_ORDER_V1",
+    CANCEL_ALL_ORDERS: "RISE_PERPS_CANCEL_ALL_ORDERS_V1",
+    UPDATE_LEVERAGE: "RISE_PERPS_UPDATE_LEVERAGE_V1",
+    UPDATE_MARGIN_MODE: "RISE_PERPS_UPDATE_MARGIN_MODE_V1",
+};
+export const SIDE = { buy: 0, sell: 1 };
+export const ORDER_TYPE = { market: 0, limit: 1 };
+/** Venue TIF codes. ALO is GTC + post_only. */
+export const TIF_CODE = { GTC: 0, GTT: 1, FOK: 2, IOC: 3 };
+export const STP_EXPIRE_MAKER = 0;
+export const MARGIN_MODE_CODE = { cross: 0, isolated: 1 };
+/** uint88 order word: [87:70] market, [69:38] size steps, [37:14] price ticks, [13:6] flags, [5:1] version 1. */
+export function packOrder(o) {
+    if (!Number.isInteger(o.marketId) || o.marketId < 0 || o.marketId > 0xffff)
+        throw new PerpError("INVALID_PARAMS", `RISEx market id ${o.marketId} out of uint16 range`);
+    if (o.sizeSteps <= 0n || o.sizeSteps > UINT32_MAX)
+        throw new PerpError("INVALID_PARAMS", `RISEx size steps ${o.sizeSteps} out of uint32 range`);
+    if (o.priceTicks < 0n || o.priceTicks > UINT24_MAX)
+        throw new PerpError("INVALID_PARAMS", `RISEx price ticks ${o.priceTicks} out of uint24 range`);
+    const flags = (o.side & 1) | ((o.postOnly ? 1 : 0) << 1) | ((o.reduceOnly ? 1 : 0) << 2)
+        | ((o.stpMode & 3) << 3) | ((o.orderType & 1) << 5) | ((o.tif & 3) << 6);
+    return (BigInt(o.marketId) << 70n) | (o.sizeSteps << 38n) | (o.priceTicks << 14n) | (BigInt(flags) << 6n) | (1n << 1n);
+}
+/** Inverse of packOrder (tests / diagnostics). */
+export function unpackOrder(word) {
+    const flags = Number((word >> 6n) & 0xffn);
+    return {
+        marketId: Number((word >> 70n) & 0xffffn),
+        sizeSteps: (word >> 38n) & UINT32_MAX,
+        priceTicks: (word >> 14n) & UINT24_MAX,
+        side: (flags & 1),
+        postOnly: ((flags >> 1) & 1) === 1,
+        reduceOnly: ((flags >> 2) & 1) === 1,
+        stpMode: (flags >> 3) & 3,
+        orderType: ((flags >> 5) & 1),
+        tif: ((flags >> 6) & 3),
+        version: Number((word >> 1n) & 0x1fn),
+    };
+}
+/** Header flags: 0x01 permit (always), 0x04 client order id present. Builder (0x02) / TTL (0x10) are never sent. */
+export function headerFlags(clientOrderId) {
+    return 0x01 | (clientOrderId !== 0n ? 0x04 : 0);
+}
+/** keccak256(abi.encode(sel, uint8 header, uint88 order, uint16 builderId=0, uint64 clientOrderId, uint16 ttl=0)). */
+export function placeOrderHash(order, clientOrderId) {
+    if (clientOrderId < 0n || clientOrderId > UINT64_MAX)
+        throw new PerpError("INVALID_PARAMS", `RISEx client order id ${clientOrderId} out of uint64 range`);
+    return keccak256(coder.encode(["bytes32", "uint8", "uint256", "uint16", "uint64", "uint16"], [selector(ACTION.PLACE_ORDER), headerFlags(clientOrderId), order, 0, clientOrderId, 0]));
+}
+export function cancelOrderHash(marketId, restingOrderId) {
+    return keccak256(coder.encode(["bytes32", "uint256", "uint256"], [selector(ACTION.CANCEL_ORDER), BigInt(marketId), restingOrderId]));
+}
+export function cancelAllHash(marketId) {
+    return keccak256(coder.encode(["bytes32", "uint256"], [selector(ACTION.CANCEL_ALL_ORDERS), BigInt(marketId)]));
+}
+export function leverageHash(marketId, leverage) {
+    if (!Number.isInteger(leverage) || leverage < 1 || leverage > 255)
+        throw new PerpError("INVALID_PARAMS", `RISEx leverage must be an integer 1..255 (got ${leverage})`);
+    return keccak256(coder.encode(["bytes32", "uint16", "uint8"], [selector(ACTION.UPDATE_LEVERAGE), marketId, leverage]));
+}
+export function marginModeHash(marketId, mode) {
+    return keccak256(coder.encode(["bytes32", "uint16", "uint8"], [selector(ACTION.UPDATE_MARGIN_MODE), marketId, mode]));
+}
+function domainOf(d) {
+    return { name: d.name, version: d.version, chainId: d.chainId, verifyingContract: getAddress(d.verifyingContract) };
+}
+/** Sign typed data and verify it recovers `expected` (an OWS canonicalization slip never leaves this process). */
+export async function signChecked(signer, domain, primary, message) {
+    const types = { [primary]: RISEX_TYPES[primary] };
+    const sig = await signer.signTypedData(domainOf(domain), types, message);
+    const recovered = verifyTypedData(domainOf(domain), types, message, sig);
+    if (recovered.toLowerCase() !== signer.getAddress().toLowerCase()) {
+        throw new PerpError("SIGNATURE_FAILED", `RISEx ${primary} signature recovers ${recovered}, expected ${signer.getAddress()} — nothing was sent`, { exchange: "risex" });
+    }
+    return Signature.from(sig).serialized;
+}
+/** 65-byte r‖s‖v hex → base64 (the permit field is protobuf bytes). */
+export function permitSignatureBase64(hexSig) {
+    const bytes = Buffer.from(hexSig.replace(/^0x/, ""), "hex");
+    if (bytes.length !== 65)
+        throw new PerpError("SIGNATURE_FAILED", `RISEx permit signature is ${bytes.length} bytes, expected 65`, { exchange: "risex" });
+    return bytes.toString("base64");
+}
+/** The signer's VerifyWitness permit for one action hash. */
+export async function signPermit(p) {
+    if (p.slot.bit < 0 || p.slot.bit > 207)
+        throw new PerpError("INVALID_PARAMS", `RISEx nonce bit ${p.slot.bit} out of 0..207`);
+    const message = {
+        account: getAddress(p.account), target: getAddress(p.router), hash: p.actionHash,
+        nonceAnchor: p.slot.anchor, nonceBitmap: p.slot.bit, deadline: p.deadline,
+    };
+    const sig = await signChecked(p.signer, p.domain, "VerifyWitness", message);
+    return {
+        account: getAddress(p.account),
+        signer: getAddress(p.signer.getAddress()),
+        nonce_anchor: p.slot.anchor.toString(),
+        nonce_bitmap_index: p.slot.bit,
+        deadline: p.deadline,
+        signature: permitSignatureBase64(sig),
+    };
+}