@newton-xyz/policy-pack-shared 0.1.1 → 0.3.0

package/dist/index.cjs

@@ -21,10 +21,36 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   UnsupportedChainError: () => UnsupportedChainError,
-  getDeployment: () => getDeployment
+  decodePolicyParams: () => decodePolicyParams,
+  encodePolicyParams: () => encodePolicyParams,
+  getDeployment: () => getDeployment,
+  wrapOutput: () => wrapOutput
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/encoding.ts
+var import_viem = require("viem");
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value && typeof value === "object") {
+    const obj = value;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = sortKeysDeep(obj[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+function encodePolicyParams(pack, params) {
+  const validated = pack.paramsSchema.parse(params);
+  return (0, import_viem.toHex)(JSON.stringify(sortKeysDeep(validated)));
+}
+function decodePolicyParams(pack, encoded) {
+  const json = new TextDecoder("utf-8", { fatal: true }).decode((0, import_viem.hexToBytes)(encoded));
+  return pack.paramsSchema.parse(JSON.parse(json));
+}
+
 // src/pack.ts
 function getDeployment(pack, chainId) {
   const deployment = pack.deployments[chainId];
@@ -51,4 +77,9 @@ var UnsupportedChainError = class extends Error {
   supportedChainIds;
   name = "UnsupportedChainError";
 };
+
+// src/wrap.ts
+function wrapOutput(packId, valueOrError) {
+  return JSON.stringify({ [packId]: valueOrError });
+}
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/pack.ts"],"sourcesContent":["export type { ChainId, Deployment } from \"./deployment\";\nexport type {\n\tPolicyPack,\n\tPrepareQueryArgs,\n\tPrepareQueryResult,\n} from \"./pack\";\nexport {\n\tgetDeployment,\n\tUnsupportedChainError,\n} from \"./pack\";\n","import type { Address, Hex, PublicClient } from \"viem\";\nimport type { z } from \"zod\";\nimport type { ChainId, Deployment } from \"./deployment\";\n\n/**\n * Inputs that a pack's `prepareQuery` reads at intent-build time.\n *\n * The Shield SDK passes a viem `PublicClient` (so the pack can read on-chain\n * state) and the vault address the curator is acting on. Packs that don't\n * need on-chain state can ignore both — `prepareQuery` is optional.\n */\nexport interface PrepareQueryArgs {\n\treadonly publicClient: PublicClient;\n\treadonly vault: Address;\n}\n\n/**\n * `wasmArgs` payload (untyped at this layer; each pack narrows it via its own\n * `WasmArgsSchema`) plus an optional pre-image hash for binding the AVS-side\n * evaluation to a specific on-chain state. VaultsFYI uses this to bind the\n * evaluation to a `keccak(supplyQueue)` snapshot so the policy can reject\n * attestations whose underlying allocation has shifted between intent build\n * and on-chain submission.\n */\nexport interface PrepareQueryResult<TWasmArgs> {\n\treadonly wasmArgs: TWasmArgs;\n\treadonly freshnessHash?: Hex;\n}\n\n/**\n * Canonical typed contract every published `@newton-xyz/policy-pack-<name>`\n * package implements. `@newton-xyz/newton-shield-sdk`'s `createShield(...)`\n * accepts `PolicyPack<P, W, S>` as the curator's pack argument.\n *\n * Type parameters:\n * - `TParams`   — the shape stored on-chain in `NewtonPolicyData.policyParams`\n *                  (e.g. risk envelope thresholds for VaultsFYI).\n * - `TWasmArgs` — the shape passed to the policy's WASM oracle at evaluation\n *                  time (e.g. `{ vault, network, lastKnownAllocationHash }`).\n * - `TSecrets`  — required API credentials uploaded before any run/sim.\n *\n * The fields:\n * - `id`             — stable identifier of the form `<pack>/<purpose>/<version>`,\n *                       e.g. `vaultsfyi/risk-envelope/v1`. Used for telemetry\n *                       and for cross-referencing the `policy_metadata.json`.\n * - `paramsSchema`   — zod schema enforced at curator setup time when the\n *                       pack is bound to a `NewtonPolicyData`.\n * - `wasmArgsSchema` — zod schema enforced per call when the SDK builds the\n *                       intent and forwards `wasmArgs` to the gateway.\n * - `secretsSchema`  — zod schema enforced at upload-time. Validates the\n *                       shape of the secrets the operator stores in the AVS.\n * - `encodeParams` / `decodeParams` — ABI round-trip for the on-chain\n *                       `policyParams` bytes. Must round-trip cleanly so the\n *                       SDK can read the on-chain value back and confirm it\n *                       matches the curator's intended config.\n * - `prepareQuery`   — optional. When present, the SDK invokes it on every\n *                       call to gather chain-state freshness inputs. Packs\n *                       that don't need this (e.g. KYC-only packs) omit it.\n *                       The optional second `options` argument is a\n *                       pack-typed escape hatch for per-call overrides —\n *                       e.g. VaultsFYI's `previousAllocationHash` for\n *                       freshness binding. Each concrete pack narrows it\n *                       via its own `prepareQuery` signature; the shared\n *                       interface keeps it `unknown` so the SDK can\n *                       forward it verbatim.\n * - `deployments`    — `chainId → Deployment` map sliced from the upstream\n *                       `deployments.json` for this pack only. Typed as\n *                       `Partial<Record<ChainId, Deployment>>` so callers\n *                       must handle `undefined` for unsupported chains\n *                       rather than silently reading `.policy` off nothing.\n *                       Use `getDeployment(pack, chainId)` from this package\n *                       for the safe lookup.\n * - `metadata`       — static identity from the pack's `policy_metadata.json`.\n */\nexport interface PolicyPack<TParams, TWasmArgs, TSecrets> {\n\treadonly id: string;\n\treadonly paramsSchema: z.ZodType<TParams>;\n\treadonly wasmArgsSchema: z.ZodType<TWasmArgs>;\n\treadonly secretsSchema: z.ZodType<TSecrets>;\n\tencodeParams(params: TParams): Hex;\n\tdecodeParams(encoded: Hex): TParams;\n\tprepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;\n\treadonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;\n\treadonly metadata: {\n\t\treadonly name: string;\n\t\treadonly version: string;\n\t\treadonly description: string;\n\t\treadonly author?: string;\n\t\treadonly link?: string;\n\t};\n}\n\n/**\n * Safe lookup helper. Returns the `Deployment` for `chainId` if the pack is\n * deployed on that chain, or throws `UnsupportedChainError` with the list of\n * chain ids the pack is known to support. Use this at every SDK callsite that\n * reads `pack.deployments[chainId]` so unsupported-chain failures surface\n * immediately rather than as `undefined.policy` further down.\n */\nexport function getDeployment<TParams, TWasmArgs, TSecrets>(\n\tpack: PolicyPack<TParams, TWasmArgs, TSecrets>,\n\tchainId: ChainId,\n): Deployment {\n\tconst deployment = pack.deployments[chainId];\n\tif (!deployment) {\n\t\tconst supported = Object.keys(pack.deployments).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedChainError(\n\t\t\t`Pack \\`${pack.id}\\` is not deployed on chain ${chainId}. Supported: ${supported}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tObject.keys(pack.deployments),\n\t\t);\n\t}\n\treturn deployment;\n}\n\n/**\n * Thrown by `getDeployment` when a pack is asked for a chain it isn't\n * deployed on. SDK consumers can catch this specifically to surface a\n * curator-friendly error rather than a `TypeError: Cannot read property\n * 'policy' of undefined`.\n */\nexport class UnsupportedChainError extends Error {\n\toverride readonly name = \"UnsupportedChainError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly supportedChainIds: ReadonlyArray<ChainId>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmGO,SAAS,cACf,MACA,SACa;AACb,QAAM,aAAa,KAAK,YAAY,OAAO;AAC3C,MAAI,CAAC,YAAY;AAChB,UAAM,YAAY,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AACrE,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,+BAA+B,OAAO,gBAAgB,SAAS;AAAA,MAChF,KAAK;AAAA,MACL;AAAA,MACA,OAAO,KAAK,KAAK,WAAW;AAAA,IAC7B;AAAA,EACD;AACA,SAAO;AACR;AAQO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAEhD,YACC,SACS,QACA,SACA,mBACR;AACD,UAAM,OAAO;AAJJ;AACA;AACA;AAAA,EAGV;AAAA,EALU;AAAA,EACA;AAAA,EACA;AAAA,EALQ,OAAO;AAS1B;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/encoding.ts","../src/pack.ts","../src/wrap.ts"],"sourcesContent":["export type { ChainId, Deployment } from \"./deployment\";\nexport { decodePolicyParams, encodePolicyParams } from \"./encoding\";\nexport type {\n\tPolicyPack,\n\tPrepareQueryArgs,\n\tPrepareQueryResult,\n} from \"./pack\";\nexport {\n\tgetDeployment,\n\tUnsupportedChainError,\n} from \"./pack\";\nexport { wrapOutput } from \"./wrap\";\n","import { type Hex, hexToBytes, toHex } from \"viem\";\nimport type { z } from \"zod\";\n\n/**\n * The on-chain `policyParams` byte format is a Newton-protocol invariant. The\n * AVS host reads it as `String::from_utf8 → serde_json::from_str` (see\n * `newton-prover-avs/crates/core/src/common/task.rs:402-408`); the SDK must\n * therefore write **UTF-8 JSON**. Keys are sorted recursively so two\n * semantically-equal params objects always produce byte-identical output —\n * the SDK's `verifyPolicyBinding` does a byte-equality check against\n * `getPolicyConfig().policyParams`, which would otherwise depend on JS\n * `JSON.stringify` insertion order.\n */\nfunction sortKeysDeep(value: unknown): unknown {\n\tif (Array.isArray(value)) return value.map(sortKeysDeep);\n\tif (value && typeof value === \"object\") {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tconst sorted: Record<string, unknown> = {};\n\t\tfor (const key of Object.keys(obj).sort()) {\n\t\t\tsorted[key] = sortKeysDeep(obj[key]);\n\t\t}\n\t\treturn sorted;\n\t}\n\treturn value;\n}\n\n/**\n * Encode a pack's params for on-chain storage. Validates against the pack's\n * `paramsSchema` so a curator typo throws here rather than silently writing\n * AVS-rejecting bytes. Returns `Hex` so it drops directly into a viem\n * `setPolicy(bytes)` call.\n */\nexport function encodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tparams: T,\n): Hex {\n\tconst validated = pack.paramsSchema.parse(params);\n\treturn toHex(JSON.stringify(sortKeysDeep(validated)));\n}\n\n/**\n * Decode `policyParams` bytes read from `getPolicyConfig().policyParams` back\n * into the pack's typed params shape. Revalidates against `paramsSchema` so a\n * stale or corrupted on-chain blob throws at the SDK boundary rather than\n * yielding a partially-valid object that crashes deeper in the call.\n *\n * `fatal: true` matches AVS-side `String::from_utf8` behavior — invalid UTF-8\n * throws here rather than silently becoming U+FFFD and diverging from a path\n * the AVS would reject.\n */\nexport function decodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tencoded: Hex,\n): T {\n\tconst json = new TextDecoder(\"utf-8\", { fatal: true }).decode(hexToBytes(encoded));\n\treturn pack.paramsSchema.parse(JSON.parse(json));\n}\n","import type { Address, Hex, PublicClient } from \"viem\";\nimport type { z } from \"zod\";\nimport type { ChainId, Deployment } from \"./deployment\";\n\n/**\n * Inputs that a pack's `prepareQuery` reads at intent-build time.\n *\n * The Shield SDK passes a viem `PublicClient` (so the pack can read on-chain\n * state) and the vault address the curator is acting on. Packs that don't\n * need on-chain state can ignore both — `prepareQuery` is optional.\n */\nexport interface PrepareQueryArgs {\n\treadonly publicClient: PublicClient;\n\treadonly vault: Address;\n}\n\n/**\n * `wasmArgs` payload (untyped at this layer; each pack narrows it via its own\n * `WasmArgsSchema`) plus an optional pre-image hash for binding the AVS-side\n * evaluation to a specific on-chain state. VaultsFYI uses this to bind the\n * evaluation to a `keccak(supplyQueue)` snapshot so the policy can reject\n * attestations whose underlying allocation has shifted between intent build\n * and on-chain submission.\n */\nexport interface PrepareQueryResult<TWasmArgs> {\n\treadonly wasmArgs: TWasmArgs;\n\treadonly freshnessHash?: Hex;\n}\n\n/**\n * Canonical typed contract every published `@newton-xyz/policy-pack-<name>`\n * package implements. `@newton-xyz/newton-shield-sdk`'s `createShield(...)`\n * accepts `PolicyPack<P, W, S>` as the curator's pack argument.\n *\n * Type parameters:\n * - `TParams`   — the shape stored on-chain in `NewtonPolicyData.policyParams`\n *                  (e.g. risk envelope thresholds for VaultsFYI).\n * - `TWasmArgs` — the shape passed to the policy's WASM oracle at evaluation\n *                  time (e.g. `{ vault, network, lastKnownAllocationHash }`).\n * - `TSecrets`  — required API credentials uploaded before any run/sim.\n *\n * The fields:\n * - `id`             — stable identifier of the form `<pack>/<purpose>/<version>`,\n *                       e.g. `vaultsfyi/risk-envelope/v1`. Used for telemetry\n *                       and for cross-referencing the `policy_metadata.json`.\n * - `paramsSchema`   — zod schema enforced at curator setup time when the\n *                       pack is bound to a `NewtonPolicyData`.\n * - `wasmArgsSchema` — zod schema enforced per call when the SDK builds the\n *                       intent and forwards `wasmArgs` to the gateway.\n * - `secretsSchema`  — zod schema enforced at upload-time. Validates the\n *                       shape of the secrets the operator stores in the AVS.\n *\n * Encoding is *not* a per-pack concern. The on-chain `policyParams` byte\n * format is a Newton-protocol invariant — UTF-8 JSON, sorted keys —\n * implemented once in this package as `encodePolicyParams` /\n * `decodePolicyParams`. See `./encoding.ts`. Earlier shapes of this\n * interface required each pack to ship its own `encodeParams` /\n * `decodeParams`; that structurally invited drift (vaultsfyi@0.2.0 shipped\n * ABI bytes against an AVS that reads `serde_json::from_str`, breaking\n * every call). The interface now leaves byte-format to the protocol.\n *\n * - `prepareQuery`   — optional. When present, the SDK invokes it on every\n *                       call to gather chain-state freshness inputs. Packs\n *                       that don't need this (e.g. KYC-only packs) omit it.\n *                       The optional second `options` argument is a\n *                       pack-typed escape hatch for per-call overrides —\n *                       e.g. VaultsFYI's `previousAllocationHash` for\n *                       freshness binding. Each concrete pack narrows it\n *                       via its own `prepareQuery` signature; the shared\n *                       interface keeps it `unknown` so the SDK can\n *                       forward it verbatim.\n * - `deployments`    — `chainId → Deployment` map sliced from the upstream\n *                       `deployments.json` for this pack only. Typed as\n *                       `Partial<Record<ChainId, Deployment>>` so callers\n *                       must handle `undefined` for unsupported chains\n *                       rather than silently reading `.policy` off nothing.\n *                       Use `getDeployment(pack, chainId)` from this package\n *                       for the safe lookup.\n * - `metadata`       — static identity from the pack's `policy_metadata.json`.\n */\nexport interface PolicyPack<TParams, TWasmArgs, TSecrets> {\n\treadonly id: string;\n\treadonly paramsSchema: z.ZodType<TParams>;\n\treadonly wasmArgsSchema: z.ZodType<TWasmArgs>;\n\treadonly secretsSchema: z.ZodType<TSecrets>;\n\tprepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;\n\treadonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;\n\treadonly metadata: {\n\t\treadonly name: string;\n\t\treadonly version: string;\n\t\treadonly description: string;\n\t\treadonly author?: string;\n\t\treadonly link?: string;\n\t};\n}\n\n/**\n * Safe lookup helper. Returns the `Deployment` for `chainId` if the pack is\n * deployed on that chain, or throws `UnsupportedChainError` with the list of\n * chain ids the pack is known to support. Use this at every SDK callsite that\n * reads `pack.deployments[chainId]` so unsupported-chain failures surface\n * immediately rather than as `undefined.policy` further down.\n */\nexport function getDeployment<TParams, TWasmArgs, TSecrets>(\n\tpack: PolicyPack<TParams, TWasmArgs, TSecrets>,\n\tchainId: ChainId,\n): Deployment {\n\tconst deployment = pack.deployments[chainId];\n\tif (!deployment) {\n\t\tconst supported = Object.keys(pack.deployments).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedChainError(\n\t\t\t`Pack \\`${pack.id}\\` is not deployed on chain ${chainId}. Supported: ${supported}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tObject.keys(pack.deployments),\n\t\t);\n\t}\n\treturn deployment;\n}\n\n/**\n * Thrown by `getDeployment` when a pack is asked for a chain it isn't\n * deployed on. SDK consumers can catch this specifically to surface a\n * curator-friendly error rather than a `TypeError: Cannot read property\n * 'policy' of undefined`.\n */\nexport class UnsupportedChainError extends Error {\n\toverride readonly name = \"UnsupportedChainError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly supportedChainIds: ReadonlyArray<ChainId>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n","/**\n * Wrap a pack's WASM oracle output under its top-level `PACK_ID` key. Every\n * `policy.js` MUST call this on every return path (success AND error) so the\n * AVS-side `merge_jsons` (`newton-prover-avs/crates/operator/src/simulation.rs:296`)\n * composes cleanly across packs without top-level key collisions.\n *\n * The merge is shallow + last-wins: pre-namespacing, vaultsfyi's\n * `risk_score: number` would silently clobber chainalysis's `risk_score: string`\n * under composition. After namespacing, every pack's output sits under its\n * unique `PACK_ID` key and merges into a single `data.wasm` blob that\n * composite Rego can reference unambiguously as `data.wasm.<pack-id>.<field>`.\n *\n * The contract this helper locks:\n * - **Output is JSON-stringified** so `policy.js` can `return wrapOutput(...)`\n *   directly. The AVS host parses every PolicyData WASM's stdout as UTF-8\n *   JSON before merging.\n * - **Top-level keys are exactly `[packId]`** — assertable in\n *   `<pack>/wrapping_test.rego` with a fixture `data.wasm.<pack-id>` shape.\n *   To be enforced at PR time by an AST-lint CI guard (Phase 0 § Stream C,\n *   shipped in a separate PR) that flags any raw `return JSON.stringify(...)`\n *   callsite in `<pack>/policy.js` not routed through this helper.\n * - **`undefined` and other JSON-nonrepresentable payloads** (functions,\n *   symbols) cause `JSON.stringify` to omit the key, returning `'{}'` rather\n *   than `{ [packId]: undefined }`. The AVS contract doesn't admit such\n *   payloads — every `policy.js` returns either a structured success object\n *   or `{ error: \"...\" }` — so this is documented as out-of-contract input\n *   rather than guarded at runtime. The Stream C AST-lint catches the\n *   shape upstream.\n * - **Both success and error paths route through here.** Returning\n *   `{\"error\": \"...\"}` directly from `policy.js` would collide across packs in\n *   `merge_jsons` (every pack's error key would land at the top level and\n *   the last one wins). Wrapping the error under `[packId]` keeps per-pack\n *   error semantics (composite Rego can selectively deny on\n *   `data.wasm.<pack-id>.error`).\n *\n * @param packId The pack's stable id, matching the `<name>OracleModule.id`\n *               that ships in Phase 1 and the `KNOWN_PACK_IDS` registry in\n *               Phase 2. Convention: lowercase single-word, matches the\n *               pack's folder name (e.g. `\"vaultsfyi\"`, `\"chainalysis\"`).\n * @param valueOrError The pack's output payload — `{ score, risk_score, ... }`\n *                     for success, `{ error: \"...\" }` for failure paths.\n *                     Untyped at this layer because each pack's WASM emits\n *                     its own shape and the `PolicyPack` /  `OracleModule`\n *                     interfaces today carry input schemas (`paramsSchema`,\n *                     `wasmArgsSchema`, `secretsSchema`) but no on-chain\n *                     output schema — composite Rego references fields by\n *                     name (`data.wasm.<pack-id>.<field>`) and trusts the\n *                     pack-specific WASM bindings paired to each\n *                     `wasm_cid` in the manifest (Phase 1.5).\n * @returns JSON-stringified `{ [packId]: valueOrError }` ready to drop into\n *          a `policy.js` `return` statement.\n *\n * @example\n *   // vaultsfyi/policy.js (success path)\n *   return wrapOutput(\"vaultsfyi\", { score: 80, risk_score: 75, timestamp });\n *   // → '{\"vaultsfyi\":{\"score\":80,\"risk_score\":75,\"timestamp\":...}}'\n *\n *   // vaultsfyi/policy.js (error path)\n *   return wrapOutput(\"vaultsfyi\", { error: String(e) });\n *   // → '{\"vaultsfyi\":{\"error\":\"...\"}}'  — namespaced, won't collide\n */\nexport function wrapOutput(packId: string, valueOrError: unknown): string {\n\treturn JSON.stringify({ [packId]: valueOrError });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,kBAA4C;AAa5C,SAAS,aAAa,OAAyB;AAC9C,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,YAAY;AACvD,MAAI,SAAS,OAAO,UAAU,UAAU;AACvC,UAAM,MAAM;AACZ,UAAM,SAAkC,CAAC;AACzC,eAAW,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK,GAAG;AAC1C,aAAO,GAAG,IAAI,aAAa,IAAI,GAAG,CAAC;AAAA,IACpC;AACA,WAAO;AAAA,EACR;AACA,SAAO;AACR;AAQO,SAAS,mBACf,MACA,QACM;AACN,QAAM,YAAY,KAAK,aAAa,MAAM,MAAM;AAChD,aAAO,mBAAM,KAAK,UAAU,aAAa,SAAS,CAAC,CAAC;AACrD;AAYO,SAAS,mBACf,MACA,SACI;AACJ,QAAM,OAAO,IAAI,YAAY,SAAS,EAAE,OAAO,KAAK,CAAC,EAAE,WAAO,wBAAW,OAAO,CAAC;AACjF,SAAO,KAAK,aAAa,MAAM,KAAK,MAAM,IAAI,CAAC;AAChD;;;AC+CO,SAAS,cACf,MACA,SACa;AACb,QAAM,aAAa,KAAK,YAAY,OAAO;AAC3C,MAAI,CAAC,YAAY;AAChB,UAAM,YAAY,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AACrE,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,+BAA+B,OAAO,gBAAgB,SAAS;AAAA,MAChF,KAAK;AAAA,MACL;AAAA,MACA,OAAO,KAAK,KAAK,WAAW;AAAA,IAC7B;AAAA,EACD;AACA,SAAO;AACR;AAQO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAEhD,YACC,SACS,QACA,SACA,mBACR;AACD,UAAM,OAAO;AAJJ;AACA;AACA;AAAA,EAGV;AAAA,EALU;AAAA,EACA;AAAA,EACA;AAAA,EALQ,OAAO;AAS1B;;;AC3EO,SAAS,WAAW,QAAgB,cAA+B;AACzE,SAAO,KAAK,UAAU,EAAE,CAAC,MAAM,GAAG,aAAa,CAAC;AACjD;","names":[]}

package/dist/index.d.cts

@@ -39,6 +39,29 @@ interface Deployment {
     readonly notes?: string;
 }
 
+/**
+ * Encode a pack's params for on-chain storage. Validates against the pack's
+ * `paramsSchema` so a curator typo throws here rather than silently writing
+ * AVS-rejecting bytes. Returns `Hex` so it drops directly into a viem
+ * `setPolicy(bytes)` call.
+ */
+declare function encodePolicyParams<T>(pack: {
+    readonly paramsSchema: z.ZodType<T>;
+}, params: T): Hex;
+/**
+ * Decode `policyParams` bytes read from `getPolicyConfig().policyParams` back
+ * into the pack's typed params shape. Revalidates against `paramsSchema` so a
+ * stale or corrupted on-chain blob throws at the SDK boundary rather than
+ * yielding a partially-valid object that crashes deeper in the call.
+ *
+ * `fatal: true` matches AVS-side `String::from_utf8` behavior — invalid UTF-8
+ * throws here rather than silently becoming U+FFFD and diverging from a path
+ * the AVS would reject.
+ */
+declare function decodePolicyParams<T>(pack: {
+    readonly paramsSchema: z.ZodType<T>;
+}, encoded: Hex): T;
+
 /**
  * Inputs that a pack's `prepareQuery` reads at intent-build time.
  *
@@ -84,10 +107,16 @@ interface PrepareQueryResult<TWasmArgs> {
  *                       intent and forwards `wasmArgs` to the gateway.
  * - `secretsSchema`  — zod schema enforced at upload-time. Validates the
  *                       shape of the secrets the operator stores in the AVS.
- * - `encodeParams` / `decodeParams` — ABI round-trip for the on-chain
- *                       `policyParams` bytes. Must round-trip cleanly so the
- *                       SDK can read the on-chain value back and confirm it
- *                       matches the curator's intended config.
+ *
+ * Encoding is *not* a per-pack concern. The on-chain `policyParams` byte
+ * format is a Newton-protocol invariant — UTF-8 JSON, sorted keys —
+ * implemented once in this package as `encodePolicyParams` /
+ * `decodePolicyParams`. See `./encoding.ts`. Earlier shapes of this
+ * interface required each pack to ship its own `encodeParams` /
+ * `decodeParams`; that structurally invited drift (vaultsfyi@0.2.0 shipped
+ * ABI bytes against an AVS that reads `serde_json::from_str`, breaking
+ * every call). The interface now leaves byte-format to the protocol.
+ *
  * - `prepareQuery`   — optional. When present, the SDK invokes it on every
  *                       call to gather chain-state freshness inputs. Packs
  *                       that don't need this (e.g. KYC-only packs) omit it.
@@ -112,8 +141,6 @@ interface PolicyPack<TParams, TWasmArgs, TSecrets> {
     readonly paramsSchema: z.ZodType<TParams>;
     readonly wasmArgsSchema: z.ZodType<TWasmArgs>;
     readonly secretsSchema: z.ZodType<TSecrets>;
-    encodeParams(params: TParams): Hex;
-    decodeParams(encoded: Hex): TParams;
     prepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;
     readonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;
     readonly metadata: {
@@ -146,4 +173,67 @@ declare class UnsupportedChainError extends Error {
     constructor(message: string, packId: string, chainId: ChainId, supportedChainIds: ReadonlyArray<ChainId>);
 }
 
-export { type ChainId, type Deployment, type PolicyPack, type PrepareQueryArgs, type PrepareQueryResult, UnsupportedChainError, getDeployment };
+/**
+ * Wrap a pack's WASM oracle output under its top-level `PACK_ID` key. Every
+ * `policy.js` MUST call this on every return path (success AND error) so the
+ * AVS-side `merge_jsons` (`newton-prover-avs/crates/operator/src/simulation.rs:296`)
+ * composes cleanly across packs without top-level key collisions.
+ *
+ * The merge is shallow + last-wins: pre-namespacing, vaultsfyi's
+ * `risk_score: number` would silently clobber chainalysis's `risk_score: string`
+ * under composition. After namespacing, every pack's output sits under its
+ * unique `PACK_ID` key and merges into a single `data.wasm` blob that
+ * composite Rego can reference unambiguously as `data.wasm.<pack-id>.<field>`.
+ *
+ * The contract this helper locks:
+ * - **Output is JSON-stringified** so `policy.js` can `return wrapOutput(...)`
+ *   directly. The AVS host parses every PolicyData WASM's stdout as UTF-8
+ *   JSON before merging.
+ * - **Top-level keys are exactly `[packId]`** — assertable in
+ *   `<pack>/wrapping_test.rego` with a fixture `data.wasm.<pack-id>` shape.
+ *   To be enforced at PR time by an AST-lint CI guard (Phase 0 § Stream C,
+ *   shipped in a separate PR) that flags any raw `return JSON.stringify(...)`
+ *   callsite in `<pack>/policy.js` not routed through this helper.
+ * - **`undefined` and other JSON-nonrepresentable payloads** (functions,
+ *   symbols) cause `JSON.stringify` to omit the key, returning `'{}'` rather
+ *   than `{ [packId]: undefined }`. The AVS contract doesn't admit such
+ *   payloads — every `policy.js` returns either a structured success object
+ *   or `{ error: "..." }` — so this is documented as out-of-contract input
+ *   rather than guarded at runtime. The Stream C AST-lint catches the
+ *   shape upstream.
+ * - **Both success and error paths route through here.** Returning
+ *   `{"error": "..."}` directly from `policy.js` would collide across packs in
+ *   `merge_jsons` (every pack's error key would land at the top level and
+ *   the last one wins). Wrapping the error under `[packId]` keeps per-pack
+ *   error semantics (composite Rego can selectively deny on
+ *   `data.wasm.<pack-id>.error`).
+ *
+ * @param packId The pack's stable id, matching the `<name>OracleModule.id`
+ *               that ships in Phase 1 and the `KNOWN_PACK_IDS` registry in
+ *               Phase 2. Convention: lowercase single-word, matches the
+ *               pack's folder name (e.g. `"vaultsfyi"`, `"chainalysis"`).
+ * @param valueOrError The pack's output payload — `{ score, risk_score, ... }`
+ *                     for success, `{ error: "..." }` for failure paths.
+ *                     Untyped at this layer because each pack's WASM emits
+ *                     its own shape and the `PolicyPack` /  `OracleModule`
+ *                     interfaces today carry input schemas (`paramsSchema`,
+ *                     `wasmArgsSchema`, `secretsSchema`) but no on-chain
+ *                     output schema — composite Rego references fields by
+ *                     name (`data.wasm.<pack-id>.<field>`) and trusts the
+ *                     pack-specific WASM bindings paired to each
+ *                     `wasm_cid` in the manifest (Phase 1.5).
+ * @returns JSON-stringified `{ [packId]: valueOrError }` ready to drop into
+ *          a `policy.js` `return` statement.
+ *
+ * @example
+ *   // vaultsfyi/policy.js (success path)
+ *   return wrapOutput("vaultsfyi", { score: 80, risk_score: 75, timestamp });
+ *   // → '{"vaultsfyi":{"score":80,"risk_score":75,"timestamp":...}}'
+ *
+ *   // vaultsfyi/policy.js (error path)
+ *   return wrapOutput("vaultsfyi", { error: String(e) });
+ *   // → '{"vaultsfyi":{"error":"..."}}'  — namespaced, won't collide
+ */
+declare function wrapOutput(packId: string, valueOrError: unknown): string;
+
+export { type ChainId, type Deployment, type PolicyPack, type PrepareQueryArgs, type PrepareQueryResult, UnsupportedChainError, decodePolicyParams, encodePolicyParams, getDeployment, wrapOutput };

package/dist/index.d.ts

@@ -39,6 +39,29 @@ interface Deployment {
     readonly notes?: string;
 }
 
+/**
+ * Encode a pack's params for on-chain storage. Validates against the pack's
+ * `paramsSchema` so a curator typo throws here rather than silently writing
+ * AVS-rejecting bytes. Returns `Hex` so it drops directly into a viem
+ * `setPolicy(bytes)` call.
+ */
+declare function encodePolicyParams<T>(pack: {
+    readonly paramsSchema: z.ZodType<T>;
+}, params: T): Hex;
+/**
+ * Decode `policyParams` bytes read from `getPolicyConfig().policyParams` back
+ * into the pack's typed params shape. Revalidates against `paramsSchema` so a
+ * stale or corrupted on-chain blob throws at the SDK boundary rather than
+ * yielding a partially-valid object that crashes deeper in the call.
+ *
+ * `fatal: true` matches AVS-side `String::from_utf8` behavior — invalid UTF-8
+ * throws here rather than silently becoming U+FFFD and diverging from a path
+ * the AVS would reject.
+ */
+declare function decodePolicyParams<T>(pack: {
+    readonly paramsSchema: z.ZodType<T>;
+}, encoded: Hex): T;
+
 /**
  * Inputs that a pack's `prepareQuery` reads at intent-build time.
  *
@@ -84,10 +107,16 @@ interface PrepareQueryResult<TWasmArgs> {
  *                       intent and forwards `wasmArgs` to the gateway.
  * - `secretsSchema`  — zod schema enforced at upload-time. Validates the
  *                       shape of the secrets the operator stores in the AVS.
- * - `encodeParams` / `decodeParams` — ABI round-trip for the on-chain
- *                       `policyParams` bytes. Must round-trip cleanly so the
- *                       SDK can read the on-chain value back and confirm it
- *                       matches the curator's intended config.
+ *
+ * Encoding is *not* a per-pack concern. The on-chain `policyParams` byte
+ * format is a Newton-protocol invariant — UTF-8 JSON, sorted keys —
+ * implemented once in this package as `encodePolicyParams` /
+ * `decodePolicyParams`. See `./encoding.ts`. Earlier shapes of this
+ * interface required each pack to ship its own `encodeParams` /
+ * `decodeParams`; that structurally invited drift (vaultsfyi@0.2.0 shipped
+ * ABI bytes against an AVS that reads `serde_json::from_str`, breaking
+ * every call). The interface now leaves byte-format to the protocol.
+ *
  * - `prepareQuery`   — optional. When present, the SDK invokes it on every
  *                       call to gather chain-state freshness inputs. Packs
  *                       that don't need this (e.g. KYC-only packs) omit it.
@@ -112,8 +141,6 @@ interface PolicyPack<TParams, TWasmArgs, TSecrets> {
     readonly paramsSchema: z.ZodType<TParams>;
     readonly wasmArgsSchema: z.ZodType<TWasmArgs>;
     readonly secretsSchema: z.ZodType<TSecrets>;
-    encodeParams(params: TParams): Hex;
-    decodeParams(encoded: Hex): TParams;
     prepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;
     readonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;
     readonly metadata: {
@@ -146,4 +173,67 @@ declare class UnsupportedChainError extends Error {
     constructor(message: string, packId: string, chainId: ChainId, supportedChainIds: ReadonlyArray<ChainId>);
 }
 
-export { type ChainId, type Deployment, type PolicyPack, type PrepareQueryArgs, type PrepareQueryResult, UnsupportedChainError, getDeployment };
+/**
+ * Wrap a pack's WASM oracle output under its top-level `PACK_ID` key. Every
+ * `policy.js` MUST call this on every return path (success AND error) so the
+ * AVS-side `merge_jsons` (`newton-prover-avs/crates/operator/src/simulation.rs:296`)
+ * composes cleanly across packs without top-level key collisions.
+ *
+ * The merge is shallow + last-wins: pre-namespacing, vaultsfyi's
+ * `risk_score: number` would silently clobber chainalysis's `risk_score: string`
+ * under composition. After namespacing, every pack's output sits under its
+ * unique `PACK_ID` key and merges into a single `data.wasm` blob that
+ * composite Rego can reference unambiguously as `data.wasm.<pack-id>.<field>`.
+ *
+ * The contract this helper locks:
+ * - **Output is JSON-stringified** so `policy.js` can `return wrapOutput(...)`
+ *   directly. The AVS host parses every PolicyData WASM's stdout as UTF-8
+ *   JSON before merging.
+ * - **Top-level keys are exactly `[packId]`** — assertable in
+ *   `<pack>/wrapping_test.rego` with a fixture `data.wasm.<pack-id>` shape.
+ *   To be enforced at PR time by an AST-lint CI guard (Phase 0 § Stream C,
+ *   shipped in a separate PR) that flags any raw `return JSON.stringify(...)`
+ *   callsite in `<pack>/policy.js` not routed through this helper.
+ * - **`undefined` and other JSON-nonrepresentable payloads** (functions,
+ *   symbols) cause `JSON.stringify` to omit the key, returning `'{}'` rather
+ *   than `{ [packId]: undefined }`. The AVS contract doesn't admit such
+ *   payloads — every `policy.js` returns either a structured success object
+ *   or `{ error: "..." }` — so this is documented as out-of-contract input
+ *   rather than guarded at runtime. The Stream C AST-lint catches the
+ *   shape upstream.
+ * - **Both success and error paths route through here.** Returning
+ *   `{"error": "..."}` directly from `policy.js` would collide across packs in
+ *   `merge_jsons` (every pack's error key would land at the top level and
+ *   the last one wins). Wrapping the error under `[packId]` keeps per-pack
+ *   error semantics (composite Rego can selectively deny on
+ *   `data.wasm.<pack-id>.error`).
+ *
+ * @param packId The pack's stable id, matching the `<name>OracleModule.id`
+ *               that ships in Phase 1 and the `KNOWN_PACK_IDS` registry in
+ *               Phase 2. Convention: lowercase single-word, matches the
+ *               pack's folder name (e.g. `"vaultsfyi"`, `"chainalysis"`).
+ * @param valueOrError The pack's output payload — `{ score, risk_score, ... }`
+ *                     for success, `{ error: "..." }` for failure paths.
+ *                     Untyped at this layer because each pack's WASM emits
+ *                     its own shape and the `PolicyPack` /  `OracleModule`
+ *                     interfaces today carry input schemas (`paramsSchema`,
+ *                     `wasmArgsSchema`, `secretsSchema`) but no on-chain
+ *                     output schema — composite Rego references fields by
+ *                     name (`data.wasm.<pack-id>.<field>`) and trusts the
+ *                     pack-specific WASM bindings paired to each
+ *                     `wasm_cid` in the manifest (Phase 1.5).
+ * @returns JSON-stringified `{ [packId]: valueOrError }` ready to drop into
+ *          a `policy.js` `return` statement.
+ *
+ * @example
+ *   // vaultsfyi/policy.js (success path)
+ *   return wrapOutput("vaultsfyi", { score: 80, risk_score: 75, timestamp });
+ *   // → '{"vaultsfyi":{"score":80,"risk_score":75,"timestamp":...}}'
+ *
+ *   // vaultsfyi/policy.js (error path)
+ *   return wrapOutput("vaultsfyi", { error: String(e) });
+ *   // → '{"vaultsfyi":{"error":"..."}}'  — namespaced, won't collide
+ */
+declare function wrapOutput(packId: string, valueOrError: unknown): string;
+
+export { type ChainId, type Deployment, type PolicyPack, type PrepareQueryArgs, type PrepareQueryResult, UnsupportedChainError, decodePolicyParams, encodePolicyParams, getDeployment, wrapOutput };

package/dist/index.js

@@ -1,3 +1,26 @@
+// src/encoding.ts
+import { hexToBytes, toHex } from "viem";
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value && typeof value === "object") {
+    const obj = value;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = sortKeysDeep(obj[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+function encodePolicyParams(pack, params) {
+  const validated = pack.paramsSchema.parse(params);
+  return toHex(JSON.stringify(sortKeysDeep(validated)));
+}
+function decodePolicyParams(pack, encoded) {
+  const json = new TextDecoder("utf-8", { fatal: true }).decode(hexToBytes(encoded));
+  return pack.paramsSchema.parse(JSON.parse(json));
+}
+
 // src/pack.ts
 function getDeployment(pack, chainId) {
   const deployment = pack.deployments[chainId];
@@ -24,8 +47,16 @@ var UnsupportedChainError = class extends Error {
   supportedChainIds;
   name = "UnsupportedChainError";
 };
+
+// src/wrap.ts
+function wrapOutput(packId, valueOrError) {
+  return JSON.stringify({ [packId]: valueOrError });
+}
 export {
   UnsupportedChainError,
-  getDeployment
+  decodePolicyParams,
+  encodePolicyParams,
+  getDeployment,
+  wrapOutput
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/pack.ts"],"sourcesContent":["import type { Address, Hex, PublicClient } from \"viem\";\nimport type { z } from \"zod\";\nimport type { ChainId, Deployment } from \"./deployment\";\n\n/**\n * Inputs that a pack's `prepareQuery` reads at intent-build time.\n *\n * The Shield SDK passes a viem `PublicClient` (so the pack can read on-chain\n * state) and the vault address the curator is acting on. Packs that don't\n * need on-chain state can ignore both — `prepareQuery` is optional.\n */\nexport interface PrepareQueryArgs {\n\treadonly publicClient: PublicClient;\n\treadonly vault: Address;\n}\n\n/**\n * `wasmArgs` payload (untyped at this layer; each pack narrows it via its own\n * `WasmArgsSchema`) plus an optional pre-image hash for binding the AVS-side\n * evaluation to a specific on-chain state. VaultsFYI uses this to bind the\n * evaluation to a `keccak(supplyQueue)` snapshot so the policy can reject\n * attestations whose underlying allocation has shifted between intent build\n * and on-chain submission.\n */\nexport interface PrepareQueryResult<TWasmArgs> {\n\treadonly wasmArgs: TWasmArgs;\n\treadonly freshnessHash?: Hex;\n}\n\n/**\n * Canonical typed contract every published `@newton-xyz/policy-pack-<name>`\n * package implements. `@newton-xyz/newton-shield-sdk`'s `createShield(...)`\n * accepts `PolicyPack<P, W, S>` as the curator's pack argument.\n *\n * Type parameters:\n * - `TParams`   — the shape stored on-chain in `NewtonPolicyData.policyParams`\n *                  (e.g. risk envelope thresholds for VaultsFYI).\n * - `TWasmArgs` — the shape passed to the policy's WASM oracle at evaluation\n *                  time (e.g. `{ vault, network, lastKnownAllocationHash }`).\n * - `TSecrets`  — required API credentials uploaded before any run/sim.\n *\n * The fields:\n * - `id`             — stable identifier of the form `<pack>/<purpose>/<version>`,\n *                       e.g. `vaultsfyi/risk-envelope/v1`. Used for telemetry\n *                       and for cross-referencing the `policy_metadata.json`.\n * - `paramsSchema`   — zod schema enforced at curator setup time when the\n *                       pack is bound to a `NewtonPolicyData`.\n * - `wasmArgsSchema` — zod schema enforced per call when the SDK builds the\n *                       intent and forwards `wasmArgs` to the gateway.\n * - `secretsSchema`  — zod schema enforced at upload-time. Validates the\n *                       shape of the secrets the operator stores in the AVS.\n * - `encodeParams` / `decodeParams` — ABI round-trip for the on-chain\n *                       `policyParams` bytes. Must round-trip cleanly so the\n *                       SDK can read the on-chain value back and confirm it\n *                       matches the curator's intended config.\n * - `prepareQuery`   — optional. When present, the SDK invokes it on every\n *                       call to gather chain-state freshness inputs. Packs\n *                       that don't need this (e.g. KYC-only packs) omit it.\n *                       The optional second `options` argument is a\n *                       pack-typed escape hatch for per-call overrides —\n *                       e.g. VaultsFYI's `previousAllocationHash` for\n *                       freshness binding. Each concrete pack narrows it\n *                       via its own `prepareQuery` signature; the shared\n *                       interface keeps it `unknown` so the SDK can\n *                       forward it verbatim.\n * - `deployments`    — `chainId → Deployment` map sliced from the upstream\n *                       `deployments.json` for this pack only. Typed as\n *                       `Partial<Record<ChainId, Deployment>>` so callers\n *                       must handle `undefined` for unsupported chains\n *                       rather than silently reading `.policy` off nothing.\n *                       Use `getDeployment(pack, chainId)` from this package\n *                       for the safe lookup.\n * - `metadata`       — static identity from the pack's `policy_metadata.json`.\n */\nexport interface PolicyPack<TParams, TWasmArgs, TSecrets> {\n\treadonly id: string;\n\treadonly paramsSchema: z.ZodType<TParams>;\n\treadonly wasmArgsSchema: z.ZodType<TWasmArgs>;\n\treadonly secretsSchema: z.ZodType<TSecrets>;\n\tencodeParams(params: TParams): Hex;\n\tdecodeParams(encoded: Hex): TParams;\n\tprepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;\n\treadonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;\n\treadonly metadata: {\n\t\treadonly name: string;\n\t\treadonly version: string;\n\t\treadonly description: string;\n\t\treadonly author?: string;\n\t\treadonly link?: string;\n\t};\n}\n\n/**\n * Safe lookup helper. Returns the `Deployment` for `chainId` if the pack is\n * deployed on that chain, or throws `UnsupportedChainError` with the list of\n * chain ids the pack is known to support. Use this at every SDK callsite that\n * reads `pack.deployments[chainId]` so unsupported-chain failures surface\n * immediately rather than as `undefined.policy` further down.\n */\nexport function getDeployment<TParams, TWasmArgs, TSecrets>(\n\tpack: PolicyPack<TParams, TWasmArgs, TSecrets>,\n\tchainId: ChainId,\n): Deployment {\n\tconst deployment = pack.deployments[chainId];\n\tif (!deployment) {\n\t\tconst supported = Object.keys(pack.deployments).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedChainError(\n\t\t\t`Pack \\`${pack.id}\\` is not deployed on chain ${chainId}. Supported: ${supported}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tObject.keys(pack.deployments),\n\t\t);\n\t}\n\treturn deployment;\n}\n\n/**\n * Thrown by `getDeployment` when a pack is asked for a chain it isn't\n * deployed on. SDK consumers can catch this specifically to surface a\n * curator-friendly error rather than a `TypeError: Cannot read property\n * 'policy' of undefined`.\n */\nexport class UnsupportedChainError extends Error {\n\toverride readonly name = \"UnsupportedChainError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly supportedChainIds: ReadonlyArray<ChainId>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n"],"mappings":";AAmGO,SAAS,cACf,MACA,SACa;AACb,QAAM,aAAa,KAAK,YAAY,OAAO;AAC3C,MAAI,CAAC,YAAY;AAChB,UAAM,YAAY,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AACrE,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,+BAA+B,OAAO,gBAAgB,SAAS;AAAA,MAChF,KAAK;AAAA,MACL;AAAA,MACA,OAAO,KAAK,KAAK,WAAW;AAAA,IAC7B;AAAA,EACD;AACA,SAAO;AACR;AAQO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAEhD,YACC,SACS,QACA,SACA,mBACR;AACD,UAAM,OAAO;AAJJ;AACA;AACA;AAAA,EAGV;AAAA,EALU;AAAA,EACA;AAAA,EACA;AAAA,EALQ,OAAO;AAS1B;","names":[]}
+{"version":3,"sources":["../src/encoding.ts","../src/pack.ts","../src/wrap.ts"],"sourcesContent":["import { type Hex, hexToBytes, toHex } from \"viem\";\nimport type { z } from \"zod\";\n\n/**\n * The on-chain `policyParams` byte format is a Newton-protocol invariant. The\n * AVS host reads it as `String::from_utf8 → serde_json::from_str` (see\n * `newton-prover-avs/crates/core/src/common/task.rs:402-408`); the SDK must\n * therefore write **UTF-8 JSON**. Keys are sorted recursively so two\n * semantically-equal params objects always produce byte-identical output —\n * the SDK's `verifyPolicyBinding` does a byte-equality check against\n * `getPolicyConfig().policyParams`, which would otherwise depend on JS\n * `JSON.stringify` insertion order.\n */\nfunction sortKeysDeep(value: unknown): unknown {\n\tif (Array.isArray(value)) return value.map(sortKeysDeep);\n\tif (value && typeof value === \"object\") {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tconst sorted: Record<string, unknown> = {};\n\t\tfor (const key of Object.keys(obj).sort()) {\n\t\t\tsorted[key] = sortKeysDeep(obj[key]);\n\t\t}\n\t\treturn sorted;\n\t}\n\treturn value;\n}\n\n/**\n * Encode a pack's params for on-chain storage. Validates against the pack's\n * `paramsSchema` so a curator typo throws here rather than silently writing\n * AVS-rejecting bytes. Returns `Hex` so it drops directly into a viem\n * `setPolicy(bytes)` call.\n */\nexport function encodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tparams: T,\n): Hex {\n\tconst validated = pack.paramsSchema.parse(params);\n\treturn toHex(JSON.stringify(sortKeysDeep(validated)));\n}\n\n/**\n * Decode `policyParams` bytes read from `getPolicyConfig().policyParams` back\n * into the pack's typed params shape. Revalidates against `paramsSchema` so a\n * stale or corrupted on-chain blob throws at the SDK boundary rather than\n * yielding a partially-valid object that crashes deeper in the call.\n *\n * `fatal: true` matches AVS-side `String::from_utf8` behavior — invalid UTF-8\n * throws here rather than silently becoming U+FFFD and diverging from a path\n * the AVS would reject.\n */\nexport function decodePolicyParams<T>(\n\tpack: { readonly paramsSchema: z.ZodType<T> },\n\tencoded: Hex,\n): T {\n\tconst json = new TextDecoder(\"utf-8\", { fatal: true }).decode(hexToBytes(encoded));\n\treturn pack.paramsSchema.parse(JSON.parse(json));\n}\n","import type { Address, Hex, PublicClient } from \"viem\";\nimport type { z } from \"zod\";\nimport type { ChainId, Deployment } from \"./deployment\";\n\n/**\n * Inputs that a pack's `prepareQuery` reads at intent-build time.\n *\n * The Shield SDK passes a viem `PublicClient` (so the pack can read on-chain\n * state) and the vault address the curator is acting on. Packs that don't\n * need on-chain state can ignore both — `prepareQuery` is optional.\n */\nexport interface PrepareQueryArgs {\n\treadonly publicClient: PublicClient;\n\treadonly vault: Address;\n}\n\n/**\n * `wasmArgs` payload (untyped at this layer; each pack narrows it via its own\n * `WasmArgsSchema`) plus an optional pre-image hash for binding the AVS-side\n * evaluation to a specific on-chain state. VaultsFYI uses this to bind the\n * evaluation to a `keccak(supplyQueue)` snapshot so the policy can reject\n * attestations whose underlying allocation has shifted between intent build\n * and on-chain submission.\n */\nexport interface PrepareQueryResult<TWasmArgs> {\n\treadonly wasmArgs: TWasmArgs;\n\treadonly freshnessHash?: Hex;\n}\n\n/**\n * Canonical typed contract every published `@newton-xyz/policy-pack-<name>`\n * package implements. `@newton-xyz/newton-shield-sdk`'s `createShield(...)`\n * accepts `PolicyPack<P, W, S>` as the curator's pack argument.\n *\n * Type parameters:\n * - `TParams`   — the shape stored on-chain in `NewtonPolicyData.policyParams`\n *                  (e.g. risk envelope thresholds for VaultsFYI).\n * - `TWasmArgs` — the shape passed to the policy's WASM oracle at evaluation\n *                  time (e.g. `{ vault, network, lastKnownAllocationHash }`).\n * - `TSecrets`  — required API credentials uploaded before any run/sim.\n *\n * The fields:\n * - `id`             — stable identifier of the form `<pack>/<purpose>/<version>`,\n *                       e.g. `vaultsfyi/risk-envelope/v1`. Used for telemetry\n *                       and for cross-referencing the `policy_metadata.json`.\n * - `paramsSchema`   — zod schema enforced at curator setup time when the\n *                       pack is bound to a `NewtonPolicyData`.\n * - `wasmArgsSchema` — zod schema enforced per call when the SDK builds the\n *                       intent and forwards `wasmArgs` to the gateway.\n * - `secretsSchema`  — zod schema enforced at upload-time. Validates the\n *                       shape of the secrets the operator stores in the AVS.\n *\n * Encoding is *not* a per-pack concern. The on-chain `policyParams` byte\n * format is a Newton-protocol invariant — UTF-8 JSON, sorted keys —\n * implemented once in this package as `encodePolicyParams` /\n * `decodePolicyParams`. See `./encoding.ts`. Earlier shapes of this\n * interface required each pack to ship its own `encodeParams` /\n * `decodeParams`; that structurally invited drift (vaultsfyi@0.2.0 shipped\n * ABI bytes against an AVS that reads `serde_json::from_str`, breaking\n * every call). The interface now leaves byte-format to the protocol.\n *\n * - `prepareQuery`   — optional. When present, the SDK invokes it on every\n *                       call to gather chain-state freshness inputs. Packs\n *                       that don't need this (e.g. KYC-only packs) omit it.\n *                       The optional second `options` argument is a\n *                       pack-typed escape hatch for per-call overrides —\n *                       e.g. VaultsFYI's `previousAllocationHash` for\n *                       freshness binding. Each concrete pack narrows it\n *                       via its own `prepareQuery` signature; the shared\n *                       interface keeps it `unknown` so the SDK can\n *                       forward it verbatim.\n * - `deployments`    — `chainId → Deployment` map sliced from the upstream\n *                       `deployments.json` for this pack only. Typed as\n *                       `Partial<Record<ChainId, Deployment>>` so callers\n *                       must handle `undefined` for unsupported chains\n *                       rather than silently reading `.policy` off nothing.\n *                       Use `getDeployment(pack, chainId)` from this package\n *                       for the safe lookup.\n * - `metadata`       — static identity from the pack's `policy_metadata.json`.\n */\nexport interface PolicyPack<TParams, TWasmArgs, TSecrets> {\n\treadonly id: string;\n\treadonly paramsSchema: z.ZodType<TParams>;\n\treadonly wasmArgsSchema: z.ZodType<TWasmArgs>;\n\treadonly secretsSchema: z.ZodType<TSecrets>;\n\tprepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;\n\treadonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;\n\treadonly metadata: {\n\t\treadonly name: string;\n\t\treadonly version: string;\n\t\treadonly description: string;\n\t\treadonly author?: string;\n\t\treadonly link?: string;\n\t};\n}\n\n/**\n * Safe lookup helper. Returns the `Deployment` for `chainId` if the pack is\n * deployed on that chain, or throws `UnsupportedChainError` with the list of\n * chain ids the pack is known to support. Use this at every SDK callsite that\n * reads `pack.deployments[chainId]` so unsupported-chain failures surface\n * immediately rather than as `undefined.policy` further down.\n */\nexport function getDeployment<TParams, TWasmArgs, TSecrets>(\n\tpack: PolicyPack<TParams, TWasmArgs, TSecrets>,\n\tchainId: ChainId,\n): Deployment {\n\tconst deployment = pack.deployments[chainId];\n\tif (!deployment) {\n\t\tconst supported = Object.keys(pack.deployments).sort().join(\", \") || \"(none)\";\n\t\tthrow new UnsupportedChainError(\n\t\t\t`Pack \\`${pack.id}\\` is not deployed on chain ${chainId}. Supported: ${supported}.`,\n\t\t\tpack.id,\n\t\t\tchainId,\n\t\t\tObject.keys(pack.deployments),\n\t\t);\n\t}\n\treturn deployment;\n}\n\n/**\n * Thrown by `getDeployment` when a pack is asked for a chain it isn't\n * deployed on. SDK consumers can catch this specifically to surface a\n * curator-friendly error rather than a `TypeError: Cannot read property\n * 'policy' of undefined`.\n */\nexport class UnsupportedChainError extends Error {\n\toverride readonly name = \"UnsupportedChainError\";\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly packId: string,\n\t\treadonly chainId: ChainId,\n\t\treadonly supportedChainIds: ReadonlyArray<ChainId>,\n\t) {\n\t\tsuper(message);\n\t}\n}\n","/**\n * Wrap a pack's WASM oracle output under its top-level `PACK_ID` key. Every\n * `policy.js` MUST call this on every return path (success AND error) so the\n * AVS-side `merge_jsons` (`newton-prover-avs/crates/operator/src/simulation.rs:296`)\n * composes cleanly across packs without top-level key collisions.\n *\n * The merge is shallow + last-wins: pre-namespacing, vaultsfyi's\n * `risk_score: number` would silently clobber chainalysis's `risk_score: string`\n * under composition. After namespacing, every pack's output sits under its\n * unique `PACK_ID` key and merges into a single `data.wasm` blob that\n * composite Rego can reference unambiguously as `data.wasm.<pack-id>.<field>`.\n *\n * The contract this helper locks:\n * - **Output is JSON-stringified** so `policy.js` can `return wrapOutput(...)`\n *   directly. The AVS host parses every PolicyData WASM's stdout as UTF-8\n *   JSON before merging.\n * - **Top-level keys are exactly `[packId]`** — assertable in\n *   `<pack>/wrapping_test.rego` with a fixture `data.wasm.<pack-id>` shape.\n *   To be enforced at PR time by an AST-lint CI guard (Phase 0 § Stream C,\n *   shipped in a separate PR) that flags any raw `return JSON.stringify(...)`\n *   callsite in `<pack>/policy.js` not routed through this helper.\n * - **`undefined` and other JSON-nonrepresentable payloads** (functions,\n *   symbols) cause `JSON.stringify` to omit the key, returning `'{}'` rather\n *   than `{ [packId]: undefined }`. The AVS contract doesn't admit such\n *   payloads — every `policy.js` returns either a structured success object\n *   or `{ error: \"...\" }` — so this is documented as out-of-contract input\n *   rather than guarded at runtime. The Stream C AST-lint catches the\n *   shape upstream.\n * - **Both success and error paths route through here.** Returning\n *   `{\"error\": \"...\"}` directly from `policy.js` would collide across packs in\n *   `merge_jsons` (every pack's error key would land at the top level and\n *   the last one wins). Wrapping the error under `[packId]` keeps per-pack\n *   error semantics (composite Rego can selectively deny on\n *   `data.wasm.<pack-id>.error`).\n *\n * @param packId The pack's stable id, matching the `<name>OracleModule.id`\n *               that ships in Phase 1 and the `KNOWN_PACK_IDS` registry in\n *               Phase 2. Convention: lowercase single-word, matches the\n *               pack's folder name (e.g. `\"vaultsfyi\"`, `\"chainalysis\"`).\n * @param valueOrError The pack's output payload — `{ score, risk_score, ... }`\n *                     for success, `{ error: \"...\" }` for failure paths.\n *                     Untyped at this layer because each pack's WASM emits\n *                     its own shape and the `PolicyPack` /  `OracleModule`\n *                     interfaces today carry input schemas (`paramsSchema`,\n *                     `wasmArgsSchema`, `secretsSchema`) but no on-chain\n *                     output schema — composite Rego references fields by\n *                     name (`data.wasm.<pack-id>.<field>`) and trusts the\n *                     pack-specific WASM bindings paired to each\n *                     `wasm_cid` in the manifest (Phase 1.5).\n * @returns JSON-stringified `{ [packId]: valueOrError }` ready to drop into\n *          a `policy.js` `return` statement.\n *\n * @example\n *   // vaultsfyi/policy.js (success path)\n *   return wrapOutput(\"vaultsfyi\", { score: 80, risk_score: 75, timestamp });\n *   // → '{\"vaultsfyi\":{\"score\":80,\"risk_score\":75,\"timestamp\":...}}'\n *\n *   // vaultsfyi/policy.js (error path)\n *   return wrapOutput(\"vaultsfyi\", { error: String(e) });\n *   // → '{\"vaultsfyi\":{\"error\":\"...\"}}'  — namespaced, won't collide\n */\nexport function wrapOutput(packId: string, valueOrError: unknown): string {\n\treturn JSON.stringify({ [packId]: valueOrError });\n}\n"],"mappings":";AAAA,SAAmB,YAAY,aAAa;AAa5C,SAAS,aAAa,OAAyB;AAC9C,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,YAAY;AACvD,MAAI,SAAS,OAAO,UAAU,UAAU;AACvC,UAAM,MAAM;AACZ,UAAM,SAAkC,CAAC;AACzC,eAAW,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK,GAAG;AAC1C,aAAO,GAAG,IAAI,aAAa,IAAI,GAAG,CAAC;AAAA,IACpC;AACA,WAAO;AAAA,EACR;AACA,SAAO;AACR;AAQO,SAAS,mBACf,MACA,QACM;AACN,QAAM,YAAY,KAAK,aAAa,MAAM,MAAM;AAChD,SAAO,MAAM,KAAK,UAAU,aAAa,SAAS,CAAC,CAAC;AACrD;AAYO,SAAS,mBACf,MACA,SACI;AACJ,QAAM,OAAO,IAAI,YAAY,SAAS,EAAE,OAAO,KAAK,CAAC,EAAE,OAAO,WAAW,OAAO,CAAC;AACjF,SAAO,KAAK,aAAa,MAAM,KAAK,MAAM,IAAI,CAAC;AAChD;;;AC+CO,SAAS,cACf,MACA,SACa;AACb,QAAM,aAAa,KAAK,YAAY,OAAO;AAC3C,MAAI,CAAC,YAAY;AAChB,UAAM,YAAY,OAAO,KAAK,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,IAAI,KAAK;AACrE,UAAM,IAAI;AAAA,MACT,UAAU,KAAK,EAAE,+BAA+B,OAAO,gBAAgB,SAAS;AAAA,MAChF,KAAK;AAAA,MACL;AAAA,MACA,OAAO,KAAK,KAAK,WAAW;AAAA,IAC7B;AAAA,EACD;AACA,SAAO;AACR;AAQO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAEhD,YACC,SACS,QACA,SACA,mBACR;AACD,UAAM,OAAO;AAJJ;AACA;AACA;AAAA,EAGV;AAAA,EALU;AAAA,EACA;AAAA,EACA;AAAA,EALQ,OAAO;AAS1B;;;AC3EO,SAAS,WAAW,QAAgB,cAA+B;AACzE,SAAO,KAAK,UAAU,EAAE,CAAC,MAAM,GAAG,aAAa,CAAC;AACjD;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newton-xyz/policy-pack-shared",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Shared TypeScript contract for Newton policy packs. Defines the PolicyPack<Params, WasmArgs, Secrets> interface that @newton-xyz/newton-shield-sdk consumes.",
   "license": "Apache-2.0",
   "author": "Newton Protocol <https://x.com/newton_xyz> (https://newton.xyz)",
@@ -47,6 +47,7 @@
   },
   "devDependencies": {
     "tsup": "^8.5.1",
+    "tsx": "^4.19.0",
     "typescript": "^5.5.0",
     "viem": "^2.0.0",
     "zod": "^3.23.0"
@@ -55,6 +56,6 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test": "echo 'no tests yet'"
+    "test": "node --import tsx --test src/*.test.ts"
   }
 }