@pulsepairs/sdk 0.2.0 → 0.3.0

package/README.md

@@ -138,6 +138,45 @@ const signOrder = bareErc1271Signer((td) => rainSmartWalletClient.signTypedData(
 const signature = await signOrder(buildOrderTypedData({ cfg, settlementAddress, message }));
 ```
 
+### Low-level "raw tx" tier (v0.3.0) — send with your own AA session
+
+If you run your own Account-Abstraction send path (like rain.trade's `sendTxs`
+through their root session), use the **transport-free primitives** instead of the
+signer class. They return rain's exact `RawTransaction` shape (`{ to, data, value? }`)
+for the on-chain setup, and sign orders **locally** with the popup-less
+order-session key — the part your send-only session structurally cannot do
+(a root session packs the *owner* entity → `isValidSignature` returns `0xffffffff`).
+
+The one mental-model flip: **placing an order is not a transaction.** It is an
+off-chain EIP-712 signature POSTed to the matcher; the relayer transacts the fill.
+So there is no `buildPlaceOrderTx` — you `signWithOrderSession(...)` and `postOrder`.
+
+```ts
+import {
+  buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession,
+  buildOrderTypedData,
+} from "@pulsepairs/sdk";
+import { arbitrum } from "viem/chains";
+
+// Onboard once — batch both raw txs into ONE userOp through YOUR session:
+const approveTx = buildApproveSettlementTx({ usdt: cfg.usdtAddress, settlement });
+const { tx: installTx, session } = await buildInstallOrderSessionTx({ sca, chain: arbitrum });
+await sendTxs([approveTx, installTx]);   // your batched, gasless send
+persist(session);                        // { v, privateKey, entityId, expirySec }
+
+// Every order after that — no chain, no gas, no popup:
+const typedData = buildOrderTypedData({ cfg, settlementAddress, message /* maker: sca, maxFee, … */ });
+const signature = await signWithOrderSession({ session, sca, chain: arbitrum, alchemyApiKey, typedData });
+await api.postOrder({ maker: sca, /* … */, signature });
+```
+
+Two tiers, adopt in order: **MVP** = `approve` (1 raw tx) + `bareErc1271Signer`
+owner-path (1 popup/order, zero new code) → **Production** = `approve` + install
+(batched) + `signWithOrderSession` (popup-less). Full walkthrough in
+[`examples/rain-taker.ts`](examples/rain-taker.ts); rationale in
+`UPDOWN_RAIN_RAWTX_SDK_DESIGN.md`. The on-chain acceptance of these bytes on
+rain's exact MA-v2 impl is proven by `updown-contracts/test/OrderSessionForkTest.t.sol`.
+
 ---
 
 ## Account Kit: the two rules you cannot break
@@ -231,6 +270,8 @@ Account Kit      UpDownAccountKitSigner (connect, onboard, approve, withdraw,
                  signTypedDataBare, signWsAuth, isDeployed, grantSession,
                  ensureOrderSession, revokeOrderSession, hasOrderSession),
                  bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature
+Raw-tx tier      buildApproveSettlementTx, buildInstallOrderSessionTx,
+(v0.3.0)         signWithOrderSession, RawTransaction, OrderSessionRecord
 L2 HMAC auth     CLOB_AUTH_TYPES, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS
 Enums/types      OrderType, OrderSide, Option, ApiConfig, PairConfig, PostOrderBody, …
 ```

package/dist/accountKit.d.ts

@@ -64,6 +64,17 @@ export declare function isErc6492Signature(signature: Hex): boolean;
  */
 export declare function stripErc6492Wrapper(signature: Hex): Hex;
 export type RawTypedDataSigner = (typedData: TypedDataDefinition) => Promise<Hex>;
+/**
+ * A pending on-chain call, shaped EXACTLY like rain.trade's `RawTransaction`
+ * (`rain-sdk/tx/*` → `{ to, data, value? }`) so the low-level builders below
+ * drop straight into their `sendTxs`/`sendCalls` without any adapter. `value`
+ * is optional and defaults to 0 for the UpDown setup calls (approve / install).
+ */
+export type RawTransaction = {
+    to: Address;
+    data: Hex;
+    value?: bigint;
+};
 /**
  * Wrap ANY raw typed-data signer so its output is a BARE ERC-1271 signature
  * the UpDown settlement can verify. Use this when the host app already owns an
@@ -126,6 +137,17 @@ export type GrantSessionResult = {
     context: Hex;
     expirySec: number;
 };
+export type OrderSessionRecord = {
+    v: 1;
+    /** Session private key — browser/host custody, same trust class as RainAA's
+     *  IndexedDB session keys but with a strictly narrower blast radius (1271
+     *  signing only, no UserOp execution). */
+    privateKey: Hex;
+    /** MA-v2 validation entity id the key is installed under on the SCA. */
+    entityId: number;
+    /** Client-side expiry (unix sec). NOT enforced on-chain. */
+    expirySec: number;
+};
 /**
  * Owner-key ERC-1271 order signer + gasless custody sends on an Alchemy SCA.
  *
@@ -202,7 +224,9 @@ export declare class UpDownAccountKitSigner {
     /**
      * Build the `installValidation` self-call that registers a fresh session
      * key on the SCA as a signature-validation-ONLY entity (validated flow:
-     * updown-frontend/scripts/poc-session-key-fe-flow.mjs).
+     * updown-frontend/scripts/poc-session-key-fe-flow.mjs). Delegates to the
+     * shared, transport-free `buildOrderSessionInstall(...)` so the class and the
+     * standalone `buildInstallOrderSessionTx(...)` emit byte-identical calldata.
      */
     private buildOrderSessionInstallCall;
     /** The @account-kit/infra chain (Alchemy RPC config baked in) for MA-v2 clients. */
@@ -263,3 +287,46 @@ export declare class UpDownAccountKitSigner {
     /** Clear in-memory state (persisted sessions, if any, are left intact). */
     disconnect(): void;
 }
+/**
+ * Raw `approve(settlement, amount)` on the USDT contract as a `RawTransaction`.
+ * Defaults to an unlimited (MAX_UINT256) allowance — the amount `enterPosition`
+ * needs — matching what `UpDownAccountKitSigner.onboard/approve` send. Push it
+ * straight into rain's `sendTxs` (batched with `buildInstallOrderSessionTx`).
+ * Pure calldata: synchronous, no peer deps, no network.
+ */
+export declare function buildApproveSettlementTx(args: {
+    usdt: Address;
+    settlement: Address;
+    amount?: bigint;
+}): RawTransaction;
+/**
+ * Build the one-time popup-less-order-session install as a `RawTransaction`
+ * (the `installValidation` self-call) plus the `OrderSessionRecord` the host
+ * must persist and later feed to `signWithOrderSession`. Send `tx` through the
+ * host's own AA session — batched with `buildApproveSettlementTx` it costs one
+ * userOp. Requires the `@account-kit/*` peer deps (lazy-imported). The `sca`
+ * MUST be the account the session installs on (order.maker); `chain` is the
+ * viem chain the SCA lives on (Arbitrum One / Sepolia).
+ */
+export declare function buildInstallOrderSessionTx(args: {
+    sca: Address;
+    chain: Chain;
+}): Promise<{
+    tx: RawTransaction;
+    session: OrderSessionRecord;
+}>;
+/**
+ * Sign EIP-712 typed data (an Order / Cancel / WS-auth) LOCALLY with a
+ * persisted order-session key, yielding the BARE ERC-1271 signature the UpDown
+ * matcher accepts. Pure local ECDSA over a MA-v2 `signerEntity` — no bundler,
+ * gas, popup, or network. The `sca` must be deployed and carry the session
+ * entity (via `buildInstallOrderSessionTx`'s tx) before the signature is used
+ * in a fill. This is the piece rain's send-only session structurally cannot do.
+ */
+export declare function signWithOrderSession(args: {
+    session: OrderSessionRecord;
+    sca: Address;
+    chain: Chain;
+    alchemyApiKey: string;
+    typedData: TypedDataDefinition;
+}): Promise<Hex>;

package/dist/accountKit.js

@@ -356,24 +356,12 @@ export class UpDownAccountKitSigner {
         }
         this._orderSession = rec;
         if (!this._orderSessionClient) {
-            const [aaCore, scMod, infraMod] = await Promise.all([
-                // @ts-ignore peer dep
-                import("@aa-sdk/core"),
-                // @ts-ignore peer dep
-                import("@account-kit/smart-contracts"),
-                // @ts-ignore peer dep
-                import("@account-kit/infra"),
-            ]);
-            const { LocalAccountSigner } = aaCore;
-            const { createModularAccountV2Client } = scMod;
-            const { alchemy } = infraMod;
-            this._orderSessionClient = await createModularAccountV2Client({
-                mode: "default",
-                chain: await this.infraChain(),
-                transport: alchemy({ apiKey: this.config.alchemyApiKey }),
-                signer: LocalAccountSigner.privateKeyToAccountSigner(rec.privateKey),
-                accountAddress: this._address,
-                signerEntity: { entityId: rec.entityId, isGlobalValidation: false },
+            this._orderSessionClient = await buildOrderSessionClient({
+                sca: this._address,
+                chainId: this.config.chain.id,
+                alchemyApiKey: this.config.alchemyApiKey,
+                privateKey: rec.privateKey,
+                entityId: rec.entityId,
             });
         }
         return this._orderSessionClient.account;
@@ -400,51 +388,17 @@ export class UpDownAccountKitSigner {
     /**
      * Build the `installValidation` self-call that registers a fresh session
      * key on the SCA as a signature-validation-ONLY entity (validated flow:
-     * updown-frontend/scripts/poc-session-key-fe-flow.mjs).
+     * updown-frontend/scripts/poc-session-key-fe-flow.mjs). Delegates to the
+     * shared, transport-free `buildOrderSessionInstall(...)` so the class and the
+     * standalone `buildInstallOrderSessionTx(...)` emit byte-identical calldata.
      */
     async buildOrderSessionInstallCall() {
-        const [viemAccounts, expMod, viemMod] = await Promise.all([
-            // @ts-ignore viem subpath
-            import("viem/accounts"),
-            // @ts-ignore peer dep
-            import("@account-kit/smart-contracts/experimental"),
-            // @ts-ignore viem
-            import("viem"),
-        ]);
-        const { generatePrivateKey, privateKeyToAccount } = viemAccounts;
-        const { getDefaultSingleSignerValidationModuleAddress, SingleSignerValidationModule, serializeValidationConfig, semiModularAccountBytecodeAbi, } = expMod;
-        const privateKey = generatePrivateKey();
-        const sessionAddress = privateKeyToAccount(privateKey).address;
-        // Random 4-byte entity id (≥2): 0 is the owner entity, and installing an
-        // id that already exists on the account reverts — random keeps collisions
-        // with prior sessions (lost storage, other hosts) vanishingly unlikely.
-        const entityId = 2 + Math.floor(Math.random() * 0x7ffffff0);
-        const data = viemMod.encodeFunctionData({
-            abi: semiModularAccountBytecodeAbi,
-            functionName: "installValidation",
-            args: [
-                serializeValidationConfig({
-                    moduleAddress: getDefaultSingleSignerValidationModuleAddress(await this.infraChain()),
-                    entityId,
-                    isGlobal: false,
-                    isSignatureValidation: true, // can answer ERC-1271…
-                    isUserOpValidation: false, // …but can never execute a UserOp
-                }),
-                [],
-                SingleSignerValidationModule.encodeOnInstallData({ entityId, signer: sessionAddress }),
-                [],
-            ],
-        });
-        return {
-            call: { to: this.address, data },
-            record: { v: 1, privateKey, entityId, expirySec: Math.floor(Date.now() / 1000) + ORDER_SESSION_TTL_SEC },
-        };
+        const { tx, session } = await buildOrderSessionInstall(this.address, await this.infraChain());
+        return { call: { to: tx.to, data: tx.data }, record: session };
     }
     /** The @account-kit/infra chain (Alchemy RPC config baked in) for MA-v2 clients. */
-    async infraChain() {
-        // @ts-ignore peer dep
-        const infra = (await import("@account-kit/infra"));
-        return this.config.chain.id === 421614 ? infra.arbitrumSepolia : infra.arbitrum;
+    infraChain() {
+        return infraChainFor(this.config.chain.id);
     }
     /**
      * Build + owner-sign a WS-auth handshake and package it as `WsAuthCredentials`
@@ -621,11 +575,142 @@ export class UpDownAccountKitSigner {
         this._mods = null;
     }
 }
+/* ═══════════════════════════════════════════════════════════════════════
+ *  Low-level ("raw tx") tier — transport-free primitives (design doc §4)
+ *
+ *  These surface the exact calldata + local-signing logic the
+ *  `UpDownAccountKitSigner` class uses privately, so a host that owns its own
+ *  Account-Abstraction send path (rain.trade's shared session) can:
+ *    1. get UpDown's setup calls as `RawTransaction`s and push them through
+ *       ITS batched userOp (`sendTxs`),  and
+ *    2. sign UpDown orders LOCALLY with the popup-less order-session key.
+ *  The class delegates to the same `buildOrderSessionInstall` /
+ *  `buildOrderSessionClient` helpers, guaranteeing identical bytes.
+ * ═══════════════════════════════════════════════════════════════════════ */
+/** The @account-kit/infra chain (Alchemy RPC baked in) for MA-v2 clients. */
+async function infraChainFor(chainId) {
+    // @ts-ignore peer dep
+    const infra = (await import("@account-kit/infra"));
+    return chainId === 421614 ? infra.arbitrumSepolia : infra.arbitrum;
+}
+/**
+ * Build the `installValidation` self-call that registers a fresh order-session
+ * key on `sca` as a signature-validation-ONLY MA-v2 entity, plus the session
+ * material to persist. Transport-free: pure local key-gen + calldata encoding —
+ * no bundler, gas, popup, or network. `moduleChain` only selects the
+ * `SingleSignerValidationModule` address (a constant across chains today), so
+ * either an `@account-kit/infra` chain or a viem `Chain` works.
+ */
+async function buildOrderSessionInstall(sca, moduleChain) {
+    const [viemAccounts, expMod, viemMod] = await Promise.all([
+        // @ts-ignore viem subpath
+        import("viem/accounts"),
+        // @ts-ignore peer dep
+        import("@account-kit/smart-contracts/experimental"),
+        // @ts-ignore viem
+        import("viem"),
+    ]);
+    const { generatePrivateKey, privateKeyToAccount } = viemAccounts;
+    const { getDefaultSingleSignerValidationModuleAddress, SingleSignerValidationModule, serializeValidationConfig, semiModularAccountBytecodeAbi, } = expMod;
+    const privateKey = generatePrivateKey();
+    const sessionAddress = privateKeyToAccount(privateKey).address;
+    // Random 4-byte entity id (≥2): 0 is the owner entity, and installing an
+    // id that already exists on the account reverts — random keeps collisions
+    // with prior sessions (lost storage, other hosts) vanishingly unlikely.
+    const entityId = 2 + Math.floor(Math.random() * 0x7ffffff0);
+    const data = viemMod.encodeFunctionData({
+        abi: semiModularAccountBytecodeAbi,
+        functionName: "installValidation",
+        args: [
+            serializeValidationConfig({
+                moduleAddress: getDefaultSingleSignerValidationModuleAddress(moduleChain),
+                entityId,
+                isGlobal: false,
+                isSignatureValidation: true, // can answer ERC-1271…
+                isUserOpValidation: false, // …but can never execute a UserOp
+            }),
+            [],
+            SingleSignerValidationModule.encodeOnInstallData({ entityId, signer: sessionAddress }),
+            [],
+        ],
+    });
+    return {
+        tx: { to: sca, data },
+        session: { v: 1, privateKey, entityId, expirySec: Math.floor(Date.now() / 1000) + ORDER_SESSION_TTL_SEC },
+    };
+}
+/**
+ * Build a MA-v2 smart-wallet client bound to an order-session key's validation
+ * entity. Used only for LOCAL ERC-1271 signing (`account.signTypedData`) — the
+ * entity cannot execute UserOps — so no bundler/gas/network is exercised by the
+ * signing path. Shared by the class and the standalone `signWithOrderSession`.
+ */
+async function buildOrderSessionClient(args) {
+    const [aaCore, scMod, infraMod] = await Promise.all([
+        // @ts-ignore peer dep
+        import("@aa-sdk/core"),
+        // @ts-ignore peer dep
+        import("@account-kit/smart-contracts"),
+        // @ts-ignore peer dep
+        import("@account-kit/infra"),
+    ]);
+    const { LocalAccountSigner } = aaCore;
+    const { createModularAccountV2Client } = scMod;
+    const { alchemy } = infraMod;
+    return createModularAccountV2Client({
+        mode: "default",
+        chain: await infraChainFor(args.chainId),
+        transport: alchemy({ apiKey: args.alchemyApiKey }),
+        signer: LocalAccountSigner.privateKeyToAccountSigner(args.privateKey),
+        accountAddress: args.sca,
+        signerEntity: { entityId: args.entityId, isGlobalValidation: false },
+    });
+}
+/**
+ * Raw `approve(settlement, amount)` on the USDT contract as a `RawTransaction`.
+ * Defaults to an unlimited (MAX_UINT256) allowance — the amount `enterPosition`
+ * needs — matching what `UpDownAccountKitSigner.onboard/approve` send. Push it
+ * straight into rain's `sendTxs` (batched with `buildInstallOrderSessionTx`).
+ * Pure calldata: synchronous, no peer deps, no network.
+ */
+export function buildApproveSettlementTx(args) {
+    return { to: args.usdt, data: encodeApprove(args.settlement, args.amount ?? MAX_UINT256) };
+}
+/**
+ * Build the one-time popup-less-order-session install as a `RawTransaction`
+ * (the `installValidation` self-call) plus the `OrderSessionRecord` the host
+ * must persist and later feed to `signWithOrderSession`. Send `tx` through the
+ * host's own AA session — batched with `buildApproveSettlementTx` it costs one
+ * userOp. Requires the `@account-kit/*` peer deps (lazy-imported). The `sca`
+ * MUST be the account the session installs on (order.maker); `chain` is the
+ * viem chain the SCA lives on (Arbitrum One / Sepolia).
+ */
+export function buildInstallOrderSessionTx(args) {
+    return buildOrderSessionInstall(args.sca, args.chain);
+}
+/**
+ * Sign EIP-712 typed data (an Order / Cancel / WS-auth) LOCALLY with a
+ * persisted order-session key, yielding the BARE ERC-1271 signature the UpDown
+ * matcher accepts. Pure local ECDSA over a MA-v2 `signerEntity` — no bundler,
+ * gas, popup, or network. The `sca` must be deployed and carry the session
+ * entity (via `buildInstallOrderSessionTx`'s tx) before the signature is used
+ * in a fill. This is the piece rain's send-only session structurally cannot do.
+ */
+export async function signWithOrderSession(args) {
+    const client = await buildOrderSessionClient({
+        sca: args.sca,
+        chainId: args.chain.id,
+        alchemyApiKey: args.alchemyApiKey,
+        privateKey: args.session.privateKey,
+        entityId: args.session.entityId,
+    });
+    return (await client.account.signTypedData(args.typedData));
+}
 /* ───────────────────────── calldata encoders ───────────────────────── */
 const MAX_UINT256 = (1n << 256n) - 1n;
-function encodeApprove(spender) {
+function encodeApprove(spender, amount = MAX_UINT256) {
     // approve(address,uint256) selector 0x095ea7b3
-    return ("0x095ea7b3" + pad(spender) + pad(MAX_UINT256));
+    return ("0x095ea7b3" + pad(spender) + pad(amount));
 }
 function encodeTransfer(to, amount) {
     // transfer(address,uint256) selector 0xa9059cbb

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCan
 export { CLOB_AUTH_TYPES, CLOB_AUTH_MESSAGE, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS, type ClobAuthDomain, type ClobAuthMessage, } from "./auth.js";
 export { ensureSettlementAllowance, MAX_UINT256, type EnsureAllowanceResult, } from "./approve.js";
 export { UpDownAccountKitSigner, bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature, type UpDownAccountKitConfig, type Eip1193Provider, type GrantSessionResult, type RawTypedDataSigner, } from "./accountKit.js";
+export { buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession, type RawTransaction, type OrderSessionRecord, } from "./accountKit.js";
 export { OrderType, OrderSide, Option, type ApiConfig, type Balance, type CancelOrderBody, type Eip712Domain, type MarketDetail, type MarketListItem, type OptionValue, type OrderBookFull, type OrderBookLevel, type OrderBookSide, type OrderRow, type OrderSideKey, type OrderSideValue, type OrderStatus, type OrderTypeKey, type OrderTypeValue, type OrdersResponse, type PairConfig, type PairSymbol, type PostOrderBody, type Position, type Stats, type Trade, type Version, } from "./types.js";

package/dist/index.js

@@ -11,5 +11,10 @@ export { ensureSettlementAllowance, MAX_UINT256, } from "./approve.js";
 // Peer deps (@account-kit/*, @aa-sdk/core) are lazy-imported; importing this
 // module does NOT require them unless you construct/connect the signer.
 export { UpDownAccountKitSigner, bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature, } from "./accountKit.js";
+// Low-level "raw tx" tier (design doc §4) — transport-free primitives for hosts
+// that own their own Account-Abstraction send path (e.g. rain.trade's shared
+// session): on-chain setup builders → rain's exact `RawTransaction` shape, plus
+// a local order-session signer for the off-chain sigs their session can't make.
+export { buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession, } from "./accountKit.js";
 // Types
 export { OrderType, OrderSide, Option, } from "./types.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsepairs/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets — matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
   "license": "UNLICENSED",
   "type": "module",
@@ -21,7 +21,7 @@
   "scripts": {
     "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc",
-    "test": "node scripts/eip712-golden.test.mjs",
+    "test": "node scripts/eip712-golden.test.mjs && node scripts/rawtx-tier.test.mjs",
     "prepublishOnly": "npm run build && npm test",
     "example:taker": "npx tsx examples/simple-taker.ts",
     "example:maker": "npx tsx examples/simple-maker.ts",