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

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 * - `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): 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;;;AC4FO,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/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":[]}

package/dist/index.d.cts

@@ -91,6 +91,13 @@ interface PrepareQueryResult<TWasmArgs> {
  * - `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.
+ *                       The optional second `options` argument is a
+ *                       pack-typed escape hatch for per-call overrides —
+ *                       e.g. VaultsFYI's `previousAllocationHash` for
+ *                       freshness binding. Each concrete pack narrows it
+ *                       via its own `prepareQuery` signature; the shared
+ *                       interface keeps it `unknown` so the SDK can
+ *                       forward it verbatim.
  * - `deployments`    — `chainId → Deployment` map sliced from the upstream
  *                       `deployments.json` for this pack only. Typed as
  *                       `Partial<Record<ChainId, Deployment>>` so callers
@@ -107,7 +114,7 @@ interface PolicyPack<TParams, TWasmArgs, TSecrets> {
     readonly secretsSchema: z.ZodType<TSecrets>;
     encodeParams(params: TParams): Hex;
     decodeParams(encoded: Hex): TParams;
-    prepareQuery?(args: PrepareQueryArgs): Promise<PrepareQueryResult<TWasmArgs>>;
+    prepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;
     readonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;
     readonly metadata: {
         readonly name: string;

package/dist/index.d.ts

@@ -91,6 +91,13 @@ interface PrepareQueryResult<TWasmArgs> {
  * - `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.
+ *                       The optional second `options` argument is a
+ *                       pack-typed escape hatch for per-call overrides —
+ *                       e.g. VaultsFYI's `previousAllocationHash` for
+ *                       freshness binding. Each concrete pack narrows it
+ *                       via its own `prepareQuery` signature; the shared
+ *                       interface keeps it `unknown` so the SDK can
+ *                       forward it verbatim.
  * - `deployments`    — `chainId → Deployment` map sliced from the upstream
  *                       `deployments.json` for this pack only. Typed as
  *                       `Partial<Record<ChainId, Deployment>>` so callers
@@ -107,7 +114,7 @@ interface PolicyPack<TParams, TWasmArgs, TSecrets> {
     readonly secretsSchema: z.ZodType<TSecrets>;
     encodeParams(params: TParams): Hex;
     decodeParams(encoded: Hex): TParams;
-    prepareQuery?(args: PrepareQueryArgs): Promise<PrepareQueryResult<TWasmArgs>>;
+    prepareQuery?(args: PrepareQueryArgs, options?: unknown): Promise<PrepareQueryResult<TWasmArgs>>;
     readonly deployments: Readonly<Partial<Record<ChainId, Deployment>>>;
     readonly metadata: {
         readonly name: string;

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 * - `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): 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":";AA4FO,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/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":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newton-xyz/policy-pack-shared",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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)",