jalin-sdk 0.1.0

package/dist/rpc-response.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reading a JSON-RPC reply, including the replies that are not JSON.
+ *
+ * A node under load, behind a proxy, or holding a rejected key answers with
+ * plain text or HTML. Calling `.json()` on that throws a SyntaxError whose
+ * message is "Unexpected token 'M'" — which is what a caller saw instead of
+ * "the node rejected this request", and which never mentions the status code
+ * that would have explained it.
+ *
+ * Pure so it can be tested: the failure paths here are the ones that only run
+ * when something is already wrong, which is exactly where untested code rots.
+ */
+export type RpcOutcome<T> = {
+    ok: true;
+    result: T;
+} | {
+    ok: false;
+    kind: 'node' | 'transport';
+    message: string;
+};
+export declare function interpretRpc<T>(status: number, body: string, method: string): RpcOutcome<T>;
+//# sourceMappingURL=rpc-response.d.ts.map

package/dist/rpc-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-response.d.ts","sourceRoot":"","sources":["../src/rpc-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GACvB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAK9D,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,UAAU,CAAC,CAAC,CAAC,CAiCf"}

package/dist/rpc-response.js

@@ -0,0 +1,44 @@
+/**
+ * Reading a JSON-RPC reply, including the replies that are not JSON.
+ *
+ * A node under load, behind a proxy, or holding a rejected key answers with
+ * plain text or HTML. Calling `.json()` on that throws a SyntaxError whose
+ * message is "Unexpected token 'M'" — which is what a caller saw instead of
+ * "the node rejected this request", and which never mentions the status code
+ * that would have explained it.
+ *
+ * Pure so it can be tested: the failure paths here are the ones that only run
+ * when something is already wrong, which is exactly where untested code rots.
+ */
+/** Enough of a non-JSON body to recognise it, and no more. */
+const SNIPPET = 120;
+export function interpretRpc(status, body, method) {
+    const trimmed = body.trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // Not JSON at all. The status is the useful part; the body is a hint.
+        const hint = trimmed.slice(0, SNIPPET) || '(empty body)';
+        return {
+            ok: false,
+            kind: status >= 400 ? 'node' : 'transport',
+            message: status >= 400
+                ? `the node answered ${status} and not JSON: ${hint}`
+                : `the node answered ${status} with something that is not JSON: ${hint}`,
+        };
+    }
+    if (parsed?.error) {
+        const code = parsed.error.code === undefined ? '' : ` (${parsed.error.code})`;
+        return { ok: false, kind: 'node', message: `${parsed.error.message ?? 'no message'}${code}` };
+    }
+    if (status >= 400) {
+        return { ok: false, kind: 'node', message: `the node answered ${status}` };
+    }
+    if (parsed?.result === undefined) {
+        return { ok: false, kind: 'node', message: `${method} returned no result` };
+    }
+    return { ok: true, result: parsed.result };
+}
+//# sourceMappingURL=rpc-response.js.map

package/dist/rpc-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-response.js","sourceRoot":"","sources":["../src/rpc-response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,8DAA8D;AAC9D,MAAM,OAAO,GAAG,GAAG,CAAA;AAEnB,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,IAAY,EACZ,MAAc;IAEd,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAE3B,IAAI,MAA+E,CAAA;IACnF,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAA;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,cAAc,CAAA;QACxD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW;YAC1C,OAAO,EACL,MAAM,IAAI,GAAG;gBACX,CAAC,CAAC,qBAAqB,MAAM,kBAAkB,IAAI,EAAE;gBACrD,CAAC,CAAC,qBAAqB,MAAM,qCAAqC,IAAI,EAAE;SAC7E,CAAA;IACH,CAAC;IAED,IAAI,MAAM,EAAE,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,CAAA;QAC7E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,YAAY,GAAG,IAAI,EAAE,EAAE,CAAA;IAC/F,CAAC;IAED,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,MAAM,EAAE,EAAE,CAAA;IAC5E,CAAC;IAED,IAAI,MAAM,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,qBAAqB,EAAE,CAAA;IAC7E,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAA;AAC5C,CAAC"}

package/dist/shadow.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shadow accounts through the Wallet API.
+ *
+ * A shadow account is a real Starknet account the wallet derives for a
+ * (dapp, nonce) pair from the user's private state. Calls made through it carry
+ * no public link to the user's main wallet, and - unlike the router - it can
+ * *hold* something between transactions: a lending position, a vault
+ * subscription, anything with a persistent owner. That is the case the router
+ * cannot serve by construction (invariant I4 says it ends every transaction
+ * empty), and the case this module exists for.
+ *
+ * Availability, stated plainly because the docs and this repository both said
+ * otherwise until now: the Wallet API route exists. starknet.js 10.6.0
+ * (29 July 2026) added the handling and `@starknet-io/types-js` 0.10.4 carries
+ * `shadow_account_invoke` and `wallet_strk20ShadowAccountCommitment`. Whether
+ * the wallet in front of you implements them is a separate question, answered
+ * by asking it - see `probe` in the app - and never assumed here.
+ *
+ * `strategyLabel` from `./subaccounts.ts` is the `dapp_name`: the same label
+ * every session, or the next session derives a different account and the funds
+ * look lost.
+ */
+import { type WireFelt } from './wallet.ts';
+/** A public call, in the Wallet API's spelling: `entry_point`, not the RPC selector. */
+export interface ShadowCall {
+    contract_address: WireFelt;
+    entry_point: string;
+    calldata?: WireFelt[];
+}
+/**
+ * How much of the shadow account's balance each open note collects once the
+ * calls have run. `diff` is the one a persistent position wants: it settles only
+ * what this interaction gained and leaves the position itself in place.
+ */
+export type CollectPolicy = {
+    type: 'all';
+} | {
+    type: 'diff';
+} | {
+    type: 'exact';
+    amount: WireFelt;
+};
+export interface ShadowInvokeAction {
+    type: 'shadow_account_invoke';
+    dapp_name: string;
+    nonce: WireFelt;
+    calls: ShadowCall[];
+    collect_policy: CollectPolicy;
+}
+/**
+ * One `shadow_account_invoke`, checked before it reaches a wallet.
+ *
+ * The wallet refuses a bad one with INVALID_REQUEST_PAYLOAD and, as this
+ * project learned twice, nothing more - so every rule the type carries is also
+ * enforced here in words. Calls are normalised through `toFelt` for the same
+ * reason the router's calldata is: a felt with leading zeros parses to the same
+ * number and is not the same string.
+ */
+export declare function shadowInvoke(args: {
+    dappName: string;
+    nonce: string | bigint;
+    calls: {
+        contract: string | bigint;
+        entryPoint: string;
+        calldata?: (string | bigint)[];
+    }[];
+    collect: CollectPolicy | {
+        type: 'exact';
+        amount: string | bigint;
+    };
+}): ShadowInvokeAction;
+//# sourceMappingURL=shadow.d.ts.map

package/dist/shadow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../src/shadow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEnD,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,gBAAgB,EAAE,QAAQ,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAA;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAA;AAEpG,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,uBAAuB,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,QAAQ,CAAA;IACf,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,cAAc,EAAE,aAAa,CAAA;CAC9B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;KAAE,EAAE,CAAA;IAC1F,OAAO,EAAE,aAAa,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;CACpE,GAAG,kBAAkB,CA+BrB"}

package/dist/shadow.js

@@ -0,0 +1,61 @@
+/**
+ * Shadow accounts through the Wallet API.
+ *
+ * A shadow account is a real Starknet account the wallet derives for a
+ * (dapp, nonce) pair from the user's private state. Calls made through it carry
+ * no public link to the user's main wallet, and - unlike the router - it can
+ * *hold* something between transactions: a lending position, a vault
+ * subscription, anything with a persistent owner. That is the case the router
+ * cannot serve by construction (invariant I4 says it ends every transaction
+ * empty), and the case this module exists for.
+ *
+ * Availability, stated plainly because the docs and this repository both said
+ * otherwise until now: the Wallet API route exists. starknet.js 10.6.0
+ * (29 July 2026) added the handling and `@starknet-io/types-js` 0.10.4 carries
+ * `shadow_account_invoke` and `wallet_strk20ShadowAccountCommitment`. Whether
+ * the wallet in front of you implements them is a separate question, answered
+ * by asking it - see `probe` in the app - and never assumed here.
+ *
+ * `strategyLabel` from `./subaccounts.ts` is the `dapp_name`: the same label
+ * every session, or the next session derives a different account and the funds
+ * look lost.
+ */
+import { toFelt } from "./wallet.js";
+/** A Cairo short string: ASCII, at most 31 bytes. Or an explicit felt. */
+const SHORT_STRING = /^[\x20-\x7e]{1,31}$/;
+const FELT = /^0x[0-9a-fA-F]{1,64}$/;
+/**
+ * One `shadow_account_invoke`, checked before it reaches a wallet.
+ *
+ * The wallet refuses a bad one with INVALID_REQUEST_PAYLOAD and, as this
+ * project learned twice, nothing more - so every rule the type carries is also
+ * enforced here in words. Calls are normalised through `toFelt` for the same
+ * reason the router's calldata is: a felt with leading zeros parses to the same
+ * number and is not the same string.
+ */
+export function shadowInvoke(args) {
+    if (!SHORT_STRING.test(args.dappName) && !FELT.test(args.dappName)) {
+        throw new Error(`dapp name "${args.dappName}" must be a felt or ASCII text of at most 31 characters, because the wallet encodes it as a Cairo short string`);
+    }
+    if (args.calls.length === 0) {
+        throw new Error('a shadow account invoke needs at least one call');
+    }
+    for (const [index, call] of args.calls.entries()) {
+        if (!call.entryPoint || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(call.entryPoint)) {
+            throw new Error(`call ${index} has entry point "${call.entryPoint}"; the Wallet API wants the function's name, not its selector`);
+        }
+    }
+    const collect = args.collect.type === 'exact' ? { type: 'exact', amount: toFelt(args.collect.amount) } : args.collect;
+    return {
+        type: 'shadow_account_invoke',
+        dapp_name: args.dappName,
+        nonce: toFelt(args.nonce),
+        calls: args.calls.map((call) => ({
+            contract_address: toFelt(call.contract),
+            entry_point: call.entryPoint,
+            ...(call.calldata ? { calldata: call.calldata.map(toFelt) } : {}),
+        })),
+        collect_policy: collect,
+    };
+}
+//# sourceMappingURL=shadow.js.map

package/dist/shadow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow.js","sourceRoot":"","sources":["../src/shadow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAA;AAwBnD,0EAA0E;AAC1E,MAAM,YAAY,GAAG,qBAAqB,CAAA;AAC1C,MAAM,IAAI,GAAG,uBAAuB,CAAA;AAEpC;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,IAK5B;IACC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,cAAc,IAAI,CAAC,QAAQ,gHAAgH,CAC5I,CAAA;IACH,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;IACpE,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,KAAK,CACb,QAAQ,KAAK,qBAAqB,IAAI,CAAC,UAAU,+DAA+D,CACjH,CAAA;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GACX,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAA;IAEvG,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,SAAS,EAAE,IAAI,CAAC,QAAQ;QACxB,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC/B,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;YACvC,WAAW,EAAE,IAAI,CAAC,UAAU;YAC5B,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClE,CAAC,CAAC;QACH,cAAc,EAAE,OAAO;KACxB,CAAA;AACH,CAAC"}

package/dist/share.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A composed plan, small enough to be a link.
+ *
+ * A plan is worth showing somebody, and until now the only way was to describe
+ * the typing. This encodes the draft — what a person actually filled in, decimal
+ * amounts and all, not the felts it compiles to — so the link reopens the
+ * composer exactly where they left it.
+ *
+ * Deliberately not a server-side store. A saved plan behind an id is a database,
+ * an expiry policy and a thing that knows who looked at what; the whole draft
+ * fits in the URL, so none of that has to exist.
+ */
+/** Matches the composer's form state field for field. */
+export interface SharedStep {
+    target: string;
+    selector: string;
+    approveToken: string;
+    approveAmount: string;
+    calldata: string;
+}
+export interface SharedOutput {
+    token: string;
+    minAmount: string;
+}
+export interface SharedDraft {
+    inputToken: string;
+    inputAmount: string;
+    steps: SharedStep[];
+    outputs: SharedOutput[];
+}
+/**
+ * Browsers, proxies and chat clients all disagree about how long a URL may be,
+ * and the ones that disagree quietly are the problem. 4000 characters is under
+ * every limit worth caring about and far past any plan the router will accept.
+ */
+export declare const MAX_SHARE_LENGTH = 4000;
+export declare function encodeDraft(draft: SharedDraft): string;
+/**
+ * Returns null rather than throwing for anything malformed.
+ *
+ * The input is a URL somebody was handed, so it is untrusted and it is also
+ * routinely damaged in transit — a chat client that ate the last character
+ * should reopen an empty composer, not an error page.
+ */
+export declare function decodeDraft(encoded: string): SharedDraft | null;
+//# sourceMappingURL=share.d.ts.map

package/dist/share.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share.d.ts","sourceRoot":"","sources":["../src/share.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAA;AAmDpC,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAQtD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAsB/D"}

package/dist/share.js

@@ -0,0 +1,99 @@
+/**
+ * A composed plan, small enough to be a link.
+ *
+ * A plan is worth showing somebody, and until now the only way was to describe
+ * the typing. This encodes the draft — what a person actually filled in, decimal
+ * amounts and all, not the felts it compiles to — so the link reopens the
+ * composer exactly where they left it.
+ *
+ * Deliberately not a server-side store. A saved plan behind an id is a database,
+ * an expiry policy and a thing that knows who looked at what; the whole draft
+ * fits in the URL, so none of that has to exist.
+ */
+/**
+ * Browsers, proxies and chat clients all disagree about how long a URL may be,
+ * and the ones that disagree quietly are the problem. 4000 characters is under
+ * every limit worth caring about and far past any plan the router will accept.
+ */
+export const MAX_SHARE_LENGTH = 4000;
+function pack(draft) {
+    return [
+        draft.inputToken,
+        draft.inputAmount,
+        draft.steps.map((step) => [
+            step.target,
+            step.selector,
+            step.approveToken,
+            step.approveAmount,
+            step.calldata,
+        ]),
+        draft.outputs.map((output) => [output.token, output.minAmount]),
+    ];
+}
+function unpack(packed) {
+    const [inputToken, inputAmount, steps, outputs] = packed;
+    return {
+        inputToken,
+        inputAmount,
+        steps: steps.map(([target, selector, approveToken, approveAmount, calldata]) => ({
+            target,
+            selector,
+            approveToken,
+            approveAmount,
+            calldata,
+        })),
+        outputs: outputs.map(([token, minAmount]) => ({ token, minAmount })),
+    };
+}
+/** base64url: `+/=` are all meaningful in a URL and `-_` are not. */
+function toBase64Url(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(encoded) {
+    const padded = encoded.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+export function encodeDraft(draft) {
+    const encoded = toBase64Url(JSON.stringify(pack(draft)));
+    if (encoded.length > MAX_SHARE_LENGTH) {
+        throw new Error(`this plan encodes to ${encoded.length} characters, over the ${MAX_SHARE_LENGTH} a link can carry`);
+    }
+    return encoded;
+}
+/**
+ * Returns null rather than throwing for anything malformed.
+ *
+ * The input is a URL somebody was handed, so it is untrusted and it is also
+ * routinely damaged in transit — a chat client that ate the last character
+ * should reopen an empty composer, not an error page.
+ */
+export function decodeDraft(encoded) {
+    if (!encoded || encoded.length > MAX_SHARE_LENGTH)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fromBase64Url(encoded));
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed) || parsed.length !== 4)
+        return null;
+    const [inputToken, inputAmount, steps, outputs] = parsed;
+    const isText = (value) => typeof value === 'string';
+    const isRow = (row, width) => Array.isArray(row) && row.length === width && row.every(isText);
+    if (!isText(inputToken) || !isText(inputAmount))
+        return null;
+    if (!Array.isArray(steps) || !steps.every((step) => isRow(step, 5)))
+        return null;
+    if (!Array.isArray(outputs) || !outputs.every((output) => isRow(output, 2)))
+        return null;
+    return unpack([inputToken, inputAmount, steps, outputs]);
+}
+//# sourceMappingURL=share.js.map

package/dist/share.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"share.js","sourceRoot":"","sources":["../src/share.ts"],"names":[],"mappings":"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"}

package/dist/subaccounts.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Sub-account portfolio layer.
+ *
+ * Sub-accounts are what stop two strategies run by the same person from being
+ * publicly the same person. Each strategy gets its own execution identity, and
+ * nothing on chain ties them together; the aggregation back into one portfolio
+ * happens here, on the client, from notes only the viewing key can read.
+ *
+ * Availability, kept current because it has changed under this file once
+ * already. The SDK route works as of Privacy SDK 0.14.3-rc.4 via
+ * `transfers.build().subaccounts(dappName).invoke(...)` - renamed to
+ * `shadowAccounts` in rc.5 - and needs a viewing key in hand. The Wallet API
+ * route, which this file used to say did not exist, does since starknet.js
+ * 10.6.0 and `@starknet-io/types-js` 0.10.4: `shadow_account_invoke` and
+ * `wallet_strk20ShadowAccountCommitment`. `./shadow.ts` builds the action and
+ * the app asks the connected wallet whether it answers, rather than assuming.
+ * `strategyLabel` below is what becomes its `dapp_name`.
+ */
+export declare const MIN_SDK_VERSION = "0.14.3-rc.4";
+/**
+ * Structural slice of the Privacy SDK this module needs. Declared here rather
+ * than imported so the package builds and its logic stays testable without the
+ * SDK present.
+ */
+export interface TransfersBuilder {
+    subaccounts(dappName: string): TransfersBuilder;
+    invoke(contract: string, calldata: unknown[]): TransfersBuilder;
+    execute(opts: {
+        provingBlockId: number;
+    }): Promise<unknown>;
+}
+/**
+ * The `dappName` handed to `.subaccounts()` is what separates one execution
+ * identity from another, so it has to be derived the same way every time or the
+ * next session lands in a different sub-account and the funds look lost.
+ */
+export declare function strategyLabel(app: string, strategy: string): string;
+export interface Position {
+    strategy: string;
+    token: string;
+    amount: bigint;
+}
+export interface PortfolioLine {
+    token: string;
+    total: bigint;
+    /** Per-strategy split, largest first. Never leaves the client. */
+    byStrategy: {
+        strategy: string;
+        amount: bigint;
+    }[];
+}
+/**
+ * Rolls unlinkable positions back into one view. Externally these are separate
+ * identities; internally they are one balance sheet.
+ */
+export declare function aggregate(positions: Position[]): PortfolioLine[];
+/**
+ * How many strategies would have to be linked before a given one stops hiding in
+ * the crowd. A single-strategy portfolio has no internal anonymity at all, and
+ * saying so is more useful than a green tick.
+ */
+export declare function linkabilityWarnings(positions: Position[]): string[];
+//# sourceMappingURL=subaccounts.d.ts.map

package/dist/subaccounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subaccounts.d.ts","sourceRoot":"","sources":["../src/subaccounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,eAAe,gBAAgB,CAAA;AAE5C;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAA;IAC/C,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAA;IAC/D,OAAO,CAAC,IAAI,EAAE;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC5D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAcnE;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,kEAAkE;IAClE,UAAU,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACnD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,aAAa,EAAE,CAmBhE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAuBnE"}

package/dist/subaccounts.js

@@ -0,0 +1,83 @@
+/**
+ * Sub-account portfolio layer.
+ *
+ * Sub-accounts are what stop two strategies run by the same person from being
+ * publicly the same person. Each strategy gets its own execution identity, and
+ * nothing on chain ties them together; the aggregation back into one portfolio
+ * happens here, on the client, from notes only the viewing key can read.
+ *
+ * Availability, kept current because it has changed under this file once
+ * already. The SDK route works as of Privacy SDK 0.14.3-rc.4 via
+ * `transfers.build().subaccounts(dappName).invoke(...)` - renamed to
+ * `shadowAccounts` in rc.5 - and needs a viewing key in hand. The Wallet API
+ * route, which this file used to say did not exist, does since starknet.js
+ * 10.6.0 and `@starknet-io/types-js` 0.10.4: `shadow_account_invoke` and
+ * `wallet_strk20ShadowAccountCommitment`. `./shadow.ts` builds the action and
+ * the app asks the connected wallet whether it answers, rather than assuming.
+ * `strategyLabel` below is what becomes its `dapp_name`.
+ */
+export const MIN_SDK_VERSION = '0.14.3-rc.4';
+/**
+ * The `dappName` handed to `.subaccounts()` is what separates one execution
+ * identity from another, so it has to be derived the same way every time or the
+ * next session lands in a different sub-account and the funds look lost.
+ */
+export function strategyLabel(app, strategy) {
+    const normalise = (s) => s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    const a = normalise(app);
+    const s = normalise(strategy);
+    if (!a || !s) {
+        throw new Error(`strategy label needs a non-empty app and strategy, got "${app}"/"${strategy}"`);
+    }
+    return `${a}:${s}`;
+}
+/**
+ * Rolls unlinkable positions back into one view. Externally these are separate
+ * identities; internally they are one balance sheet.
+ */
+export function aggregate(positions) {
+    const byToken = new Map();
+    for (const { strategy, token, amount } of positions) {
+        if (amount === 0n)
+            continue;
+        const strategies = byToken.get(token) ?? new Map();
+        strategies.set(strategy, (strategies.get(strategy) ?? 0n) + amount);
+        byToken.set(token, strategies);
+    }
+    return [...byToken.entries()]
+        .map(([token, strategies]) => ({
+        token,
+        total: [...strategies.values()].reduce((a, b) => a + b, 0n),
+        byStrategy: [...strategies.entries()]
+            .map(([strategy, amount]) => ({ strategy, amount }))
+            .sort((a, b) => (b.amount > a.amount ? 1 : b.amount < a.amount ? -1 : 0)),
+    }))
+        .sort((a, b) => (b.total > a.total ? 1 : b.total < a.total ? -1 : 0));
+}
+/**
+ * How many strategies would have to be linked before a given one stops hiding in
+ * the crowd. A single-strategy portfolio has no internal anonymity at all, and
+ * saying so is more useful than a green tick.
+ */
+export function linkabilityWarnings(positions) {
+    const strategies = new Set(positions.map((p) => p.strategy));
+    const warnings = [];
+    if (strategies.size <= 1) {
+        warnings.push('Everything is running in one sub-account, so nothing here is unlinkable from anything else.');
+    }
+    const byToken = new Map();
+    for (const { token, strategy } of positions) {
+        byToken.set(token, (byToken.get(token) ?? new Set()).add(strategy));
+    }
+    for (const [token, owners] of byToken) {
+        if (owners.size === 1 && strategies.size > 1) {
+            warnings.push(`Only one strategy holds ${token}, so any activity in it points straight back at that strategy.`);
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=subaccounts.js.map

package/dist/subaccounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subaccounts.js","sourceRoot":"","sources":["../src/subaccounts.ts"],"names":[],"mappings":"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"}

package/dist/wallet.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 { type Felt, type Plan } from './plan.ts';
+/**
+ * A felt as it travels to the wallet: canonical hex, or a placeholder the wallet
+ * resolves at submit time.
+ *
+ * Typed rather than described. `string` for these fields let the transfer amount
+ * be declared `string | 'OPEN'`, which collapses to `string` - the literal read
+ * as a constraint and enforced nothing. Written this way the union survives, and
+ * so does every other field's shape.
+ */
+export type WireFelt = `0x${string}` | `\${${string}}`;
+/** Matches `STRK20_ACTION` from `@starknet-io/types-js`, structurally. */
+export type Strk20Action = {
+    type: 'deposit';
+    token: WireFelt;
+    amount: WireFelt;
+} | {
+    type: 'withdraw';
+    token: WireFelt;
+    amount: WireFelt;
+    recipient: WireFelt;
+} | {
+    type: 'transfer';
+    token: WireFelt;
+    amount: WireFelt | 'OPEN';
+    recipient: WireFelt;
+} | {
+    type: 'invoke';
+    contract: WireFelt;
+    calldata: WireFelt[];
+} | import('./shadow.ts').ShadowInvokeAction;
+/**
+ * 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 declare function toFelt(felt: string | bigint): WireFelt;
+export declare function feltsToStrings(felts: (string | bigint)[]): WireFelt[];
+export interface WalletActionArgs {
+    /** Deployed JalinRouter address. */
+    router: string;
+    /** What the pool must send to the router before the plan runs. */
+    inputs: {
+        token: string;
+        amount: bigint;
+    }[];
+    /** Who the open notes belong to - normally the connected account. */
+    recipient: string;
+}
+export declare function toWalletActions(plan: Plan, args: WalletActionArgs): Strk20Action[];
+/** One open note the pool created for this transaction, in creation order. */
+export interface OpenNote {
+    noteId: string | bigint;
+    token: string | bigint;
+}
+/**
+ * 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 declare function toInvokeCall(plan: Plan, args: {
+    router: string;
+    openNotes: OpenNote[];
+    poolAddress: string | bigint;
+}): {
+    contractAddress: string;
+    calldata: (string | bigint)[];
+};
+/**
+ * The felts a wallet will actually see, with placeholders left as strings.
+ * Useful for showing a user what they are about to sign.
+ */
+export declare function previewCalldata(plan: Plan, poolAddress?: Felt): string[];
+//# sourceMappingURL=wallet.d.ts.map

package/dist/wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../src/wallet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAwB,KAAK,IAAI,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAA;AAEtE;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,MAAM,EAAE,GAAG,MAAM,MAAM,GAAG,CAAA;AAEtD,0EAA0E;AAC1E,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,QAAQ,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,SAAS,EAAE,QAAQ,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC5D,OAAO,aAAa,EAAE,kBAAkB,CAAA;AAK5C;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAMtD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,CAErE;AAED,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC3C,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAA;CAClB;AAqBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,GAAG,YAAY,EAAE,CA8ClF;AAED,8EAA8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;IACvB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,QAAQ,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAC5E;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;CAAE,CAwB5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,CAIxE"}