@centrifuge/sdk 1.10.0 → 1.12.1

package/dist/utils/variables.js

@@ -0,0 +1,105 @@
+// ---------------------------------------------------------------------------
+// Magic variable keys
+// ---------------------------------------------------------------------------
+/**
+ * All well-known magic variable keys. Each is prefixed with `$` to
+ * distinguish them from protocol-specific manifest variables.
+ *
+ * Magic variables are resolved automatically by the SDK from pool metadata;
+ * they are always pinned (stateBitmap bit = 1).
+ */
+export const MAGIC_VARIABLE_KEYS = [
+    '$executor',
+    '$onchainPM',
+    '$poolEscrow',
+    '$onOffRamp',
+    '$poolId',
+    '$scId',
+    '$accountingTokenId',
+    '$accountingTokenAssetId',
+];
+// ---------------------------------------------------------------------------
+// resolveMagicVariables
+// ---------------------------------------------------------------------------
+/** Matches exactly 32 bytes ABI-encoded as a 0x-prefixed hex string. */
+const BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;
+function assertBytes32(key, value) {
+    if (!BYTES32_RE.test(value)) {
+        throw new Error(`resolveMagicVariables: "${key}" must be a 32-byte ABI-encoded hex string (0x + 64 hex chars), got "${value}". ` +
+            `Addresses must be left-zero-padded; uint values must be right-aligned to 32 bytes.`);
+    }
+}
+/**
+ * Builds a `PoolContext` from a typed `MagicVariableContext` by mapping
+ * each `$`-prefixed magic variable key to its resolved value.
+ *
+ * Pass the returned object as `poolContext` in `buildScript()`:
+ *
+ * ```typescript
+ * const poolContext = resolveMagicVariables(ctx)
+ * const script = buildScript(workflow, { poolContext, configurableValues })
+ * ```
+ *
+ * @throws if any value is not a valid 32-byte ABI-encoded hex string
+ */
+export function resolveMagicVariables(context) {
+    assertBytes32('executor', context.executor);
+    assertBytes32('poolEscrow', context.poolEscrow);
+    assertBytes32('onOffRamp', context.onOffRamp);
+    assertBytes32('poolId', context.poolId);
+    assertBytes32('scId', context.scId);
+    assertBytes32('accountingTokenId', context.accountingTokenId);
+    assertBytes32('accountingTokenAssetId', context.accountingTokenAssetId);
+    return {
+        $executor: context.executor,
+        // $onchainPM is an alias for $executor — the current "executor" used by
+        // workflows is always an OnchainPM instance. Templates may use either key.
+        $onchainPM: context.executor,
+        $poolEscrow: context.poolEscrow,
+        $onOffRamp: context.onOffRamp,
+        $poolId: context.poolId,
+        $scId: context.scId,
+        $accountingTokenId: context.accountingTokenId,
+        $accountingTokenAssetId: context.accountingTokenAssetId,
+    };
+}
+// ---------------------------------------------------------------------------
+// resolveVariableLabel
+// ---------------------------------------------------------------------------
+/**
+ * Returns a human-readable `{ value, label }` pair for a resolved variable.
+ *
+ * Used by the backend to enrich API responses so the frontend never displays
+ * raw on-chain data. Example:
+ *
+ * ```typescript
+ * resolveVariableLabel('$scId', '0x00010000000000010000000000000001', meta)
+ * // → { value: '0x000100...', label: 'JTRSY' }
+ * ```
+ *
+ * Label resolution priority:
+ * 1. `poolMetadata.addressLabels[value]` — pool-manager-maintained free-form map
+ * 2. Key-specific fallbacks (e.g. pool name for `$poolId`)
+ * 3. Raw hex string as final fallback
+ *
+ * Pool managers can register labels for any address or slot value via the
+ * `addressLabels` field of the pool metadata to customise what the UI shows.
+ */
+export function resolveVariableLabel(key, value, poolMetadata) {
+    const { addressLabels } = poolMetadata;
+    // Normalised lookup (case-insensitive for addresses)
+    const explicit = addressLabels?.[value] ??
+        addressLabels?.[value.toLowerCase()] ??
+        addressLabels?.[value.toUpperCase()];
+    if (explicit !== undefined) {
+        return { value, label: explicit };
+    }
+    // Key-specific fallbacks
+    switch (key) {
+        case '$poolId':
+            return { value, label: poolMetadata.pool.name };
+        default:
+            return { value, label: value };
+    }
+}
+//# sourceMappingURL=variables.js.map

package/dist/utils/variables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../src/utils/variables.ts"],"names":[],"mappings":"AAIA,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,WAAW;IACX,YAAY;IACZ,aAAa;IACb,YAAY;IACZ,SAAS;IACT,OAAO;IACP,oBAAoB;IACpB,yBAAyB;CACjB,CAAA;AAqCV,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,wEAAwE;AACxE,MAAM,UAAU,GAAG,qBAAqB,CAAA;AAExC,SAAS,aAAa,CAAC,GAAW,EAAE,KAAgB;IAClD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,2BAA2B,GAAG,wEAAwE,KAAK,KAAK;YAC9G,oFAAoF,CACvF,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA6B;IACjE,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC3C,aAAa,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,CAAA;IAC/C,aAAa,CAAC,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;IAC7C,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACvC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,aAAa,CAAC,mBAAmB,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC7D,aAAa,CAAC,wBAAwB,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAEvE,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,QAAQ;QAC3B,wEAAwE;QACxE,2EAA2E;QAC3E,UAAU,EAAE,OAAO,CAAC,QAAQ;QAC5B,WAAW,EAAE,OAAO,CAAC,UAAU;QAC/B,UAAU,EAAE,OAAO,CAAC,SAAS;QAC7B,OAAO,EAAE,OAAO,CAAC,MAAM;QACvB,KAAK,EAAE,OAAO,CAAC,IAAI;QACnB,kBAAkB,EAAE,OAAO,CAAC,iBAAiB;QAC7C,uBAAuB,EAAE,OAAO,CAAC,sBAAsB;KACxD,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAW,EACX,KAAgB,EAChB,YAA0B;IAE1B,MAAM,EAAE,aAAa,EAAE,GAAG,YAAY,CAAA;IAEtC,qDAAqD;IACrD,MAAM,QAAQ,GACZ,aAAa,EAAE,CAAC,KAAK,CAAC;QACtB,aAAa,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QACpC,aAAa,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;IAEtC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;IACnC,CAAC;IAED,yBAAyB;IACzB,QAAQ,GAAgC,EAAE,CAAC;QACzC,KAAK,SAAS;YACZ,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;QACjD;YACE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;IAClC,CAAC;AACH,CAAC"}

package/dist/utils/variables.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=variables.test.d.ts.map

package/dist/utils/variables.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.test.d.ts","sourceRoot":"","sources":["../../src/utils/variables.test.ts"],"names":[],"mappings":""}

package/dist/utils/variables.test.js

@@ -0,0 +1,110 @@
+import { expect } from 'chai';
+import { MAGIC_VARIABLE_KEYS, resolveMagicVariables, resolveVariableLabel } from './variables.js';
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+const CTX = {
+    executor: '0x000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+    poolEscrow: '0x000000000000000000000000bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+    onOffRamp: '0x000000000000000000000000cccccccccccccccccccccccccccccccccccccccc',
+    poolId: '0x0000000000000000000000000000000000000000000000000000000000000001',
+    scId: '0x0001000000000001000000000000000100000000000000000000000000000000',
+    accountingTokenId: '0x0000000000000000000000000000000000000000000000000000000000000002',
+    accountingTokenAssetId: '0x0000000000000000000000000000000000000000000000000000000000000003',
+};
+// Minimal pool metadata
+const POOL_META = {
+    pool: { name: 'Test Pool' },
+    shareClasses: {},
+};
+describe('utils/variables', () => {
+    describe('MAGIC_VARIABLE_KEYS', () => {
+        it('contains exactly the eight expected keys', () => {
+            expect(MAGIC_VARIABLE_KEYS).to.include('$executor');
+            expect(MAGIC_VARIABLE_KEYS).to.include('$onchainPM');
+            expect(MAGIC_VARIABLE_KEYS).to.include('$poolEscrow');
+            expect(MAGIC_VARIABLE_KEYS).to.include('$onOffRamp');
+            expect(MAGIC_VARIABLE_KEYS).to.include('$poolId');
+            expect(MAGIC_VARIABLE_KEYS).to.include('$scId');
+            expect(MAGIC_VARIABLE_KEYS).to.include('$accountingTokenId');
+            expect(MAGIC_VARIABLE_KEYS).to.include('$accountingTokenAssetId');
+            expect(MAGIC_VARIABLE_KEYS).to.have.length(8);
+        });
+        it('every key starts with $', () => {
+            for (const key of MAGIC_VARIABLE_KEYS) {
+                expect(key).to.match(/^\$/);
+            }
+        });
+    });
+    describe('resolveMagicVariables', () => {
+        it('maps all eight keys into a PoolContext', () => {
+            const ctx = resolveMagicVariables(CTX);
+            expect(ctx['$executor']).to.equal(CTX.executor);
+            expect(ctx['$onchainPM']).to.equal(CTX.executor);
+            expect(ctx['$poolEscrow']).to.equal(CTX.poolEscrow);
+            expect(ctx['$onOffRamp']).to.equal(CTX.onOffRamp);
+            expect(ctx['$poolId']).to.equal(CTX.poolId);
+            expect(ctx['$scId']).to.equal(CTX.scId);
+            expect(ctx['$accountingTokenId']).to.equal(CTX.accountingTokenId);
+            expect(ctx['$accountingTokenAssetId']).to.equal(CTX.accountingTokenAssetId);
+        });
+        it('produces exactly eight entries — no extras', () => {
+            const ctx = resolveMagicVariables(CTX);
+            expect(Object.keys(ctx)).to.have.length(8);
+        });
+        it('result keys match MAGIC_VARIABLE_KEYS', () => {
+            const ctx = resolveMagicVariables(CTX);
+            for (const key of MAGIC_VARIABLE_KEYS) {
+                expect(ctx).to.have.property(key);
+            }
+        });
+        it('is usable as poolContext in buildScript without throwing', () => {
+            // Just verifies the types are compatible — no actual execution needed.
+            const ctx = resolveMagicVariables(CTX);
+            expect(ctx).to.be.an('object');
+        });
+    });
+    describe('resolveVariableLabel', () => {
+        it('falls back to pool name for $poolId when no addressLabel exists', () => {
+            const result = resolveVariableLabel('$poolId', CTX.poolId, POOL_META);
+            expect(result.value).to.equal(CTX.poolId);
+            expect(result.label).to.equal('Test Pool');
+        });
+        it('falls back to raw hex for unknown keys without addressLabel', () => {
+            const result = resolveVariableLabel('$executor', CTX.executor, POOL_META);
+            expect(result.value).to.equal(CTX.executor);
+            expect(result.label).to.equal(CTX.executor);
+        });
+        it('uses addressLabels when present — exact match', () => {
+            const meta = {
+                ...POOL_META,
+                addressLabels: { [CTX.scId]: 'JTRSY' },
+            };
+            const result = resolveVariableLabel('$scId', CTX.scId, meta);
+            expect(result.value).to.equal(CTX.scId);
+            expect(result.label).to.equal('JTRSY');
+        });
+        it('uses addressLabels — case-insensitive lowercase match', () => {
+            const meta = {
+                ...POOL_META,
+                addressLabels: { [CTX.executor.toLowerCase()]: 'Strategist' },
+            };
+            const result = resolveVariableLabel('$executor', CTX.executor, meta);
+            expect(result.label).to.equal('Strategist');
+        });
+        it('addressLabel takes priority over key-specific fallback', () => {
+            const meta = {
+                ...POOL_META,
+                pool: { name: 'Should NOT appear' },
+                addressLabels: { [CTX.poolId]: 'Custom Pool Label' },
+            };
+            const result = resolveVariableLabel('$poolId', CTX.poolId, meta);
+            expect(result.label).to.equal('Custom Pool Label');
+        });
+        it('always returns the original value unchanged', () => {
+            const result = resolveVariableLabel('$anything', CTX.executor, POOL_META);
+            expect(result.value).to.equal(CTX.executor);
+        });
+    });
+});
+//# sourceMappingURL=variables.test.js.map

package/dist/utils/variables.test.js.map

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

package/dist/utils/weiroll.d.ts

@@ -0,0 +1,176 @@
+import type { HexString } from '../types/index.js';
+/** State-changing call. */
+export declare const CALL: 1;
+/** Read-only call. */
+export declare const STATICCALL: 2;
+/** ETH-value call — ETH amount is taken from the first input specifier's state slot. */
+export declare const VALUECALL: 3;
+/** Raw calldata mode — set in the flags byte to bypass ABI encoding. */
+export declare const FLAG_RAW: 32;
+/** Extended command mode — the next command word contains up to 32 input specifiers. */
+export declare const FLAG_EXTENDED_COMMAND: 64;
+/** Sentinel value for unused input slots or a discarded return value. */
+export declare const UNUSED_SLOT: 255;
+export type WeirollCallType = typeof CALL | typeof STATICCALL | typeof VALUECALL;
+export type WeirollTarget = HexString | {
+    type: 'magic';
+    key: string;
+};
+/** A single step in a weiroll script. */
+export interface WeirollAction {
+    /** 20-byte target contract address. */
+    target: WeirollTarget;
+    /** 4-byte function selector (e.g. `0x12345678`). */
+    selector: HexString;
+    callType: WeirollCallType;
+    /**
+     * Weiroll input specifiers for the call's inputs.
+     * Fixed-length arguments use the state slot index directly.
+     * Variable-length arguments set the high bit and store the state slot index in
+     * the low 7 bits.
+     */
+    inputs: number[];
+    /** Weiroll output specifier, or UNUSED_SLOT to discard. */
+    output: number;
+    /** When true, sets FLAG_RAW — use for manually ABI-encoded calldata. */
+    rawMode?: boolean;
+}
+/**
+ * Describes the initial value of a single state slot.
+ *
+ * - `literal`      — fixed ABI-encoded value, pinned at whitelist time
+ * - `magic`        — resolved from PoolContext by key
+ * - `configurable` — resolved from configurableValues by key
+ * - `runtime`      — placeholder filled at execution time (not pinned)
+ */
+export type WorkflowStateSlot = {
+    type: 'literal';
+    value: HexString;
+} | {
+    type: 'magic';
+    key: string;
+} | {
+    type: 'configurable';
+    key: string;
+    label?: string;
+    parameter?: string;
+    actionName?: string;
+    actionIndex?: number;
+    inputIndex?: number;
+    anonymous?: boolean;
+    system?: 'payableValue';
+} | {
+    type: 'rawcalldata';
+    selector: HexString;
+    parameterTypes: string[];
+    sourceSlots: number[];
+    actionName?: string;
+    actionIndex?: number;
+} | {
+    type: 'template';
+    workflow: WorkflowDefinition;
+    label?: string;
+    actionName?: string;
+    actionIndex?: number;
+    inputIndex?: number;
+} | {
+    type: 'runtime';
+    key: string;
+    label?: string;
+    parameter?: string;
+    actionName?: string;
+    actionIndex?: number;
+    inputIndex?: number;
+    anonymous?: boolean;
+    system?: 'payableValue';
+};
+/** The full description of a workflow: its actions and initial state layout. */
+export interface WorkflowDefinition {
+    /** Stable identifier for the workflow (matches the catalog ref). */
+    workflowRef: string;
+    actions: WeirollAction[];
+    state: WorkflowStateSlot[];
+    /**
+     * Named runtime variables required at execution time. Copied from
+     * MarketplaceWorkflow. One input per entry; the value is written into every
+     * state slot whose key matches, enforcing a single value across multiple uses.
+     */
+    runtimeVariables?: string[];
+}
+/**
+ * Protocol-level values available for magic variable resolution.
+ * All values must already be ABI-encoded (e.g. uint256 as a 32-byte hex).
+ */
+export type PoolContext = Record<string, HexString>;
+export interface ScriptResult {
+    /** ABI-encoded bytes32 command words, one per action. */
+    commands: HexString[];
+    /** ABI-encoded state slot values. Runtime slots are initialized to empty bytes. */
+    state: HexString[];
+    /**
+     * uint128 where bit i = 1 means state[i] is pinned (known at whitelist time).
+     * Bit i = 0 means runtime — the executor fills the slot at call time.
+     */
+    stateBitmap: bigint;
+}
+/**
+ * Fills runtime state slots with execution-time values.
+ *
+ * `buildScript()` initializes runtime slots to empty bytes. Before calling
+ * `OnchainPM.execute()`, the strategist must fill each runtime slot with the
+ * concrete value for this particular execution.
+ *
+ * Returns a copy of `state` with each runtime slot replaced by the
+ * corresponding value from `runtimeValues` (keyed by the slot's `key` field).
+ *
+ * @throws if any required runtime variable in `workflow.runtimeVariables` has no
+ * corresponding entry in `runtimeValues`
+ *
+ * @example
+ * ```typescript
+ * const { commands, state, stateBitmap } = buildScript(workflow, { poolContext, configurableValues })
+ * const filledState = fillRuntimeSlots(state, workflow, { amount: '0x000...0de0b6b3a7640000' })
+ * // submit OnchainPM.execute(commands, filledState, stateBitmap, [], proof)
+ * ```
+ */
+export declare function fillRuntimeSlots(state: HexString[], workflow: WorkflowDefinition, runtimeValues: Record<string, HexString>): HexString[];
+/**
+ * Packs a single weiroll command into a 32-byte word.
+ *
+ * Bit layout (from MSB):
+ * ```
+ * bits [255:224]  selector  (bytes4)  — function selector
+ * bits [223:216]  flags     (uint8)   — callType | FLAG_RAW
+ * bits [215:168]  inputs    (bytes6)  — 6 × 1-byte input specifiers, MSB first
+ * bits [167:160]  output    (uint8)   — output specifier or UNUSED_SLOT
+ * bits [159:0]    target    (address) — 20-byte contract address
+ * ```
+ *
+ * Equivalent Solidity expression:
+ * ```solidity
+ * (uint256(uint32(selector)) << 224) | (flags << 216) | (indices << 168) | (output << 160) | uint160(target)
+ * ```
+ */
+export declare function encodeCommand(selector: HexString, // 4 bytes
+flags: number, // 1 byte: callType | optional FLAG_RAW
+inputs: number[], // up to 6 weiroll input specifiers (padded to 6 with UNUSED_SLOT)
+output: number, // output specifier or UNUSED_SLOT
+target: HexString): HexString;
+/**
+ * Builds the weiroll commands array and initial state from a workflow
+ * definition, resolving magic variables and configurable values.
+ *
+ * State slots classified as `literal`, `magic`, or `configurable` are pinned:
+ * their bit in `stateBitmap` is set to 1 and the resolved value is placed in
+ * `state[i]`. Slots classified as `runtime` are initialized to empty bytes
+ * with their bit set to 0 — the executor fills them at call time.
+ *
+ * @throws if a magic variable key is absent from `poolContext`
+ * @throws if a configurable key is absent from `configurableValues`
+ * @throws if the workflow has more than 128 state slots
+ */
+export declare function buildScript(workflow: WorkflowDefinition, context: {
+    poolContext: PoolContext;
+    configurableValues: Record<string, HexString>;
+}): ScriptResult;
+//# sourceMappingURL=weiroll.d.ts.map

package/dist/utils/weiroll.d.ts.map

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