jalin-sdk 0.1.0

package/dist/wallet.js

@@ -0,0 +1,135 @@
+/**
+ * Turning a plan into STRK20 wallet actions.
+ *
+ * This is the part that is easy to get subtly wrong. Three rules, none of them
+ * obvious from the plan on its own:
+ *
+ * 1. The pool has to be told to fund the router. That is a `withdraw` action with
+ *    the router as recipient - a plain public transfer, which is why the phase
+ *    order is withdraw before invoke.
+ * 2. `${openNoteIds[N]}` means "the Nth transfer action with amount OPEN", not
+ *    "the Nth output". They are the same thing only if the OPEN transfers are
+ *    emitted in output order, which is what this module guarantees.
+ * 3. One invoke per pool transaction. A plan is one invoke no matter how many
+ *    steps it has; that is the entire reason the router exists.
+ */
+import { encodePlan, openNote } from "./plan.js";
+/** `${openNoteIds[N]}` or `${poolAddress}` - resolved by the wallet, not by us. */
+const PLACEHOLDER = /^\$\{(?:openNoteIds\[[0-9]+\]|poolAddress)\}$/;
+/**
+ * One felt, canonically encoded for the wallet.
+ *
+ * Two things are being fixed here, and both fail the same way. JSON has no
+ * bigint, so `JSON.stringify` throws on one rather than coercing it. And a felt
+ * written with leading zeros - `0x0471…` for `0x471…` - is *non-canonical*: it
+ * parses to the same number and is not the same string, and the STRK20 stack
+ * treats non-canonically encoded addresses as a distinct case rather than
+ * normalising them for you.
+ *
+ * Placeholders pass through untouched. Normalising one would destroy it.
+ */
+export function toFelt(felt) {
+    // The regex proves the shape; TypeScript cannot read a regex, so this is the
+    // one place the two have to be trusted to agree. Both are right here, and
+    // both are tested.
+    if (typeof felt === 'string' && PLACEHOLDER.test(felt))
+        return felt;
+    return `0x${BigInt(felt).toString(16)}`;
+}
+export function feltsToStrings(felts) {
+    return felts.map(toFelt);
+}
+/**
+ * Rejects a plan whose note ids are not `openNote(0..n-1)` in order.
+ *
+ * Getting this wrong does not fail loudly: the wallet resolves the placeholder to
+ * a real note id, the router credits a real amount, and the value lands in the
+ * wrong note. Better to refuse to build the transaction.
+ */
+function assertNoteIdsAreInOrder(plan) {
+    plan.outputs.forEach((output, index) => {
+        const expected = openNote(index);
+        if (output.noteId !== expected) {
+            throw new Error(`output ${index} carries note id ${String(output.noteId)}, expected ${expected}. ` +
+                'Open notes are numbered by the order of the OPEN transfer actions, so output N must use openNote(N).');
+        }
+    });
+}
+export function toWalletActions(plan, args) {
+    assertNoteIdsAreInOrder(plan);
+    if (args.inputs.length === 0 && plan.steps.some((s) => s.approvals.length > 0)) {
+        throw new Error('this plan approves tokens it was never funded with; add the inputs the pool should withdraw to the router');
+    }
+    const actions = [];
+    // 1. Fund the router. Public, and visible as the pool paying the router.
+    //
+    // There is no deposit action here, and that is a finding rather than an
+    // omission. Shielding in the same transaction that spends the note is the
+    // obvious way to onboard somebody in one step, and it does not work: mainnet
+    // answers INSUFFICIENT_PRIVATE_BALANCE. Across the pool's whole life - 342
+    // transactions carrying a Deposit and 247 carrying an invoke - not one
+    // carries both. Shield in one transaction, spend in the next.
+    for (const input of args.inputs) {
+        actions.push({
+            type: 'withdraw',
+            token: toFelt(input.token),
+            amount: toFelt(input.amount),
+            recipient: toFelt(args.router),
+        });
+    }
+    // 2. One open note per output, in output order. This is what numbers them.
+    for (const output of plan.outputs) {
+        actions.push({
+            type: 'transfer',
+            token: toFelt(output.token),
+            amount: 'OPEN',
+            recipient: toFelt(args.recipient),
+        });
+    }
+    // 3. The plan itself, as the single permitted invoke.
+    actions.push({
+        type: 'invoke',
+        contract: toFelt(args.router),
+        calldata: feltsToStrings(encodePlan(plan)),
+    });
+    return actions;
+}
+/**
+ * The same plan, for the SDK route rather than the wallet route.
+ *
+ * The two routes differ in one place that is easy to miss: a wallet resolves
+ * `${openNoteIds[N]}` itself, while the SDK hands you the real note ids in the
+ * `invoke` callback and expects them substituted before encoding. Passing a
+ * placeholder string here would be encoded as a literal and the pool would
+ * credit nothing.
+ *
+ * Returns starknet.js `CallDetails`. The entry point is implied - the pool calls
+ * the helper through its own `INVOKE_SELECTOR`, not through a name.
+ */
+export function toInvokeCall(plan, args) {
+    if (plan.outputs.length !== args.openNotes.length) {
+        throw new Error(`plan declares ${plan.outputs.length} outputs but the pool opened ${args.openNotes.length} notes; they are matched by position`);
+    }
+    const resolved = {
+        steps: plan.steps,
+        outputs: plan.outputs.map((output, index) => {
+            const note = args.openNotes[index];
+            if (BigInt(note.token) !== BigInt(output.token)) {
+                throw new Error(`output ${index} is for token ${String(output.token)} but open note ${index} is for ${String(note.token)}`);
+            }
+            return { ...output, noteId: note.noteId };
+        }),
+    };
+    return {
+        contractAddress: args.router,
+        calldata: encodePlan(resolved, args.poolAddress),
+    };
+}
+/**
+ * The felts a wallet will actually see, with placeholders left as strings.
+ * Useful for showing a user what they are about to sign.
+ */
+export function previewCalldata(plan, poolAddress) {
+    return encodePlan(plan, poolAddress).map((felt) => typeof felt === 'bigint' ? `0x${felt.toString(16)}` : felt);
+}
+//# sourceMappingURL=wallet.js.map

package/dist/wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../src/wallet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAwB,MAAM,WAAW,CAAA;AAqBtE,mFAAmF;AACnF,MAAM,WAAW,GAAG,+CAA+C,CAAA;AAEnE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,IAAqB;IAC1C,6EAA6E;IAC7E,0EAA0E;IAC1E,mBAAmB;IACnB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAgB,CAAA;IAC/E,OAAO,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAA;AACzC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAA0B;IACvD,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;AAC1B,CAAC;AAWD;;;;;;GAMG;AACH,SAAS,uBAAuB,CAAC,IAAU;IACzC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QACrC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;QAChC,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CACb,UAAU,KAAK,oBAAoB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,QAAQ,IAAI;gBAChF,sGAAsG,CACzG,CAAA;QACH,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAU,EAAE,IAAsB;IAChE,uBAAuB,CAAC,IAAI,CAAC,CAAA;IAE7B,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAC/E,MAAM,IAAI,KAAK,CACb,2GAA2G,CAC5G,CAAA;IACH,CAAC;IAED,MAAM,OAAO,GAAmB,EAAE,CAAA;IAElC,yEAAyE;IACzE,EAAE;IACF,wEAAwE;IACxE,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,uEAAuE;IACvE,8DAA8D;IAC9D,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,UAAU;YAChB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;YAC1B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;YAC5B,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SAC/B,CAAC,CAAA;IACJ,CAAC;IAED,2EAA2E;IAC3E,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,UAAU;YAChB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YAC3B,MAAM,EAAE,MAAM;YACd,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;SAClC,CAAC,CAAA;IACJ,CAAC;IAED,sDAAsD;IACtD,OAAO,CAAC,IAAI,CAAC;QACX,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAC7B,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;KAC3C,CAAC,CAAA;IAEF,OAAO,OAAO,CAAA;AAChB,CAAC;AAQD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAU,EACV,IAA6E;IAE7E,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,CAAC,OAAO,CAAC,MAAM,gCAAgC,IAAI,CAAC,SAAS,CAAC,MAAM,sCAAsC,CAChI,CAAA;IACH,CAAC;IAED,MAAM,QAAQ,GAAS;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAE,CAAA;YACnC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChD,MAAM,IAAI,KAAK,CACb,UAAU,KAAK,iBAAiB,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,KAAK,WAAW,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAC3G,CAAA;YACH,CAAC;YACD,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAA;QAC3C,CAAC,CAAC;KACH,CAAA;IAED,OAAO;QACL,eAAe,EAAE,IAAI,CAAC,MAAM;QAC5B,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;KACjD,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAU,EAAE,WAAkB;IAC5D,OAAO,UAAU,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAChD,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAC3D,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "jalin-sdk",
+  "version": "0.1.0",
+  "description": "Plan encoding and sub-account portfolio helpers for the Jalin router on STRK20",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "starknet",
+    "strk20",
+    "privacy",
+    "cairo",
+    "defi",
+    "shielded-pool"
+  ],
+  "homepage": "https://github.com/PugarHuda/jalin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PugarHuda/jalin.git",
+    "directory": "sdk"
+  },
+  "bugs": "https://github.com/PugarHuda/jalin/issues",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts"
+}