@keelcodes/manifest 0.1.0

package/dist/trust.d.ts

@@ -0,0 +1,58 @@
+import { type Hex } from 'viem';
+import type { Pim } from './types.js';
+export type TrustLevel = 0 | 1 | 2 | 3;
+export type TrustLevelName = 'Unverified' | 'Community' | 'Protocol Signed' | 'Wallet Verified';
+/** The four levels, verbatim from the draft's "Trust level assignment" table. */
+export interface TrustLevelDefinition {
+    level: TrustLevel;
+    name: TrustLevelName;
+    criteria: string;
+}
+export declare const TRUST_LEVELS: readonly TrustLevelDefinition[];
+/** Which signature payload interpretation recovered the signer. */
+export type SignatureRecovery = 'digest' | 'personal';
+/** Whether to try raw-digest, EIP-191, or both interpretations. Default `auto`. */
+export type SignatureScheme = SignatureRecovery | 'auto';
+export interface TrustOptions {
+    /** Addresses recognised as a known community publisher → Level 1. */
+    knownCommunitySigners?: readonly string[];
+    /** Addresses recognised as protocol-controlled (website/ENS/ECP) → Level 2. */
+    protocolSigners?: readonly string[];
+    /** Addresses reviewed and pinned by the wallet team → Level 3. */
+    walletVerifiedSigners?: readonly string[];
+    /** Payload interpretation; defaults to trying both. */
+    scheme?: SignatureScheme;
+}
+export interface TrustInfo {
+    level: TrustLevel;
+    name: TrustLevelName;
+    /** True only when a signature recovered to the declared `signer`. */
+    verified: boolean;
+    signer?: Hex;
+    signerLabel?: string;
+    /** How the recovered signature was interpreted (only when `verified`). */
+    scheme?: SignatureRecovery;
+    /** Human-readable explanation, always present. */
+    reason: string;
+}
+/**
+ * The canonical byte content a signature commits to: the PIM with the
+ * `signatures` section removed, serialised with no whitespace.
+ *
+ * `JSON.stringify` preserves object key order, which is how the document was
+ * parsed — consistent with "remove spacing/newlines" and no key reordering
+ * being specified.
+ */
+export declare function canonicalPimJson(pim: Pim): string;
+/** keccak256 of the canonical PIM content (the message the spec says is signed). */
+export declare function pimDigest(pim: Pim): Hex;
+/**
+ * Assign a trust level to a PIM.
+ *
+ * This is a *verifier*, not an oracle: without registry options a verifiable
+ * signature still grades Level 0 (unknown signer), matching the standard.
+ *
+ * Async because viem's signer-recovery is async; the rest of the function is pure.
+ */
+export declare function trustLevelOf(pim: Pim, options?: TrustOptions): Promise<TrustInfo>;
+//# sourceMappingURL=trust.d.ts.map

package/dist/trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../src/trust.ts"],"names":[],"mappings":"AAqBA,OAAO,EAA6D,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAC3F,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACvC,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEhG,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,YAAY,EAAE,SAAS,oBAAoB,EAqBvD,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEtD,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,+EAA+E;IAC/E,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kEAAkE;IAClE,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,uDAAuD;IACvD,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,cAAc,CAAC;IACrB,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAIjD;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CA0D3F"}

package/dist/trust.js

@@ -0,0 +1,153 @@
+// ============================================================================
+// ERC-8313 trust grading.
+//
+// The standard defines four trust levels and, crucially, *how a signature is
+// computed*: "The signature MUST be of the keccak256 hash of the entire PIM
+// excluding the signatures section. Any spacing, new lines or hidden characters
+// added for human-readability MUST be removed before the hash is generated."
+//
+// What the draft does NOT define is whether that hash is signed directly
+// (`eth_sign`-style raw digest) or wrapped in EIP-191 (`personal_sign`). Both
+// are seen in the wild, so we try both and say which one matched — a signature
+// is only reported as verified when it *actually* recovers to the declared
+// signer under one of the two interpretations. We never fake a pass.
+//
+// Level assignment beyond the cryptographic check needs out-of-band knowledge
+// (is this address on the protocol's website? is it the wallet's pinned
+// signer?). That is caller-supplied via {@link TrustOptions}; an address we can
+// cryptographically verify but cannot place in any registry is *still* Level 0
+// ("signer address is unknown") per the standard's own criteria.
+// ============================================================================
+import { keccak256, recoverAddress, recoverMessageAddress, toBytes } from 'viem';
+export const TRUST_LEVELS = [
+    {
+        level: 0,
+        name: 'Unverified',
+        criteria: 'No signature included or signer address is unknown.',
+    },
+    {
+        level: 1,
+        name: 'Community',
+        criteria: 'Signature from a known community publisher. Hash verified. Signer not the protocol team.',
+    },
+    {
+        level: 2,
+        name: 'Protocol Signed',
+        criteria: "Signature from an address on a protocol's website, or registered with an ENS domain, or broadcast using ECP.",
+    },
+    {
+        level: 3,
+        name: 'Wallet Verified',
+        criteria: 'Internally reviewed and pinned by the wallet team. MAY be bundled with the wallet.',
+    },
+];
+/**
+ * The canonical byte content a signature commits to: the PIM with the
+ * `signatures` section removed, serialised with no whitespace.
+ *
+ * `JSON.stringify` preserves object key order, which is how the document was
+ * parsed — consistent with "remove spacing/newlines" and no key reordering
+ * being specified.
+ */
+export function canonicalPimJson(pim) {
+    const { signatures: _signatures, ...rest } = pim;
+    void _signatures;
+    return JSON.stringify(rest);
+}
+/** keccak256 of the canonical PIM content (the message the spec says is signed). */
+export function pimDigest(pim) {
+    return keccak256(toBytes(canonicalPimJson(pim)));
+}
+/**
+ * Assign a trust level to a PIM.
+ *
+ * This is a *verifier*, not an oracle: without registry options a verifiable
+ * signature still grades Level 0 (unknown signer), matching the standard.
+ *
+ * Async because viem's signer-recovery is async; the rest of the function is pure.
+ */
+export async function trustLevelOf(pim, options = {}) {
+    const signatures = Array.isArray(pim.signatures) ? pim.signatures : [];
+    if (signatures.length === 0) {
+        return {
+            level: 0,
+            name: 'Unverified',
+            verified: false,
+            reason: 'no signatures present',
+        };
+    }
+    const community = lowerSet(options.knownCommunitySigners);
+    const protocol = lowerSet(options.protocolSigners);
+    const wallet = lowerSet(options.walletVerifiedSigners);
+    const scheme = options.scheme ?? 'auto';
+    let sawEcdsa = false;
+    for (const signature of signatures) {
+        if (signature.type !== 'ecdsa')
+            continue;
+        if (typeof signature.signer !== 'string' || typeof signature.signature !== 'string')
+            continue;
+        sawEcdsa = true;
+        const recovered = await recoverSigners(pim, signature.signature, scheme);
+        const declared = signature.signer.toLowerCase();
+        const matched = recovered.get(declared);
+        if (matched === undefined)
+            continue;
+        const level = wallet.has(declared)
+            ? 3
+            : protocol.has(declared)
+                ? 2
+                : community.has(declared)
+                    ? 1
+                    : 0;
+        const info = {
+            level,
+            name: trustName(level),
+            verified: true,
+            signer: signature.signer,
+            scheme: matched,
+            reason: level === 0
+                ? 'signature verified, but the signer is not in any known trust registry (unknown signer → Unverified)'
+                : `signature verified; signer is a known ${trustName(level).toLowerCase()} publisher`,
+        };
+        if (signature.signerLabel !== undefined)
+            info.signerLabel = signature.signerLabel;
+        return info;
+    }
+    return {
+        level: 0,
+        name: 'Unverified',
+        verified: false,
+        reason: sawEcdsa
+            ? 'signature present but it did not recover to the declared signer (payload/canonicalisation mismatch)'
+            : 'no supported (ecdsa) signature present',
+    };
+}
+async function recoverSigners(pim, signature, scheme) {
+    const recovered = new Map();
+    const canonical = canonicalPimJson(pim);
+    if (scheme === 'digest' || scheme === 'auto') {
+        try {
+            const hash = keccak256(toBytes(canonical));
+            recovered.set((await recoverAddress({ hash, signature })).toLowerCase(), 'digest');
+        }
+        catch {
+            // Not a valid signature under this interpretation; try the next.
+        }
+    }
+    if (scheme === 'personal' || scheme === 'auto') {
+        try {
+            recovered.set((await recoverMessageAddress({ message: canonical, signature })).toLowerCase(), 'personal');
+        }
+        catch {
+            // Not a valid signature under this interpretation.
+        }
+    }
+    return recovered;
+}
+function trustName(level) {
+    return TRUST_LEVELS[level]?.name ?? 'Unverified';
+}
+function lowerSet(values) {
+    return new Set((values ?? []).map((value) => value.toLowerCase()));
+}
+//# sourceMappingURL=trust.js.map

package/dist/trust.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,207 @@
+/** Ethereum address in lowercase or EIP-55 checksummed `0x` hex. */
+export type HexAddress = `0x${string}`;
+/** `0x`-prefixed hex string (any even byte length). */
+export type Hex = `0x${string}`;
+/** Protocol category, closed set per the `metadata.category` enum. */
+export type PimCategory = 'dex' | 'lending' | 'staking' | 'bridge' | 'vault' | 'nft' | 'governance' | 'other';
+/** Functional role of a contract, closed set per the `contracts.*.role` enum. */
+export type ContractRole = 'router' | 'factory' | 'pool' | 'quoter' | 'registry' | 'gateway' | 'oracle' | 'vault' | 'token' | 'other';
+/** Shape of a named `types` entry, per the "Tuple kinds" table. */
+export type TypeKind = 'tuple' | 'array' | 'primitive';
+/** `lookups.*.select` — reduction applied to a filtered result set. */
+export type SelectMode = 'all' | 'max' | 'min';
+/** Operators allowed inside `lookups.*.filter`. */
+export type FilterOperator = 'notEqual' | 'greaterThan' | 'lessThan' | 'equals';
+/** Operators allowed inside a `lookups.*.validate` assertion. */
+export type ValidateOperator = 'notEqual' | 'equals' | 'greaterThan' | 'lessThan';
+/** Numeric kind of a `calculations.*` result. */
+export type CalculationPrecision = 'float' | 'integer';
+/** The three step actions an intent can declare. */
+export type StepAction = 'lookup' | 'calculate' | 'buildTransaction';
+/** Signature schemes the standard names today ("ecdsa"; fips-204/205 are future). */
+export type SignatureType = string;
+/**
+ * `metadata` — protocol identity, chain scope and validity window.
+ *
+ * `validFrom`, `validUntil` and `notes` are OPTIONAL at the schema level (the
+ * standard RECOMMENDs the two timestamps); every other field is REQUIRED.
+ */
+export interface PimMetadata {
+    protocol: string;
+    description: string;
+    category: PimCategory;
+    website: string;
+    author: string;
+    chainId: number[];
+    pimVersion: string;
+    validFrom?: number;
+    validUntil?: number;
+    notes?: string;
+}
+/**
+ * One entry in `contracts`.
+ *
+ * Exactly one of `address` / `lookup` MUST be present (the standard forbids
+ * having both). `role` and `description` are REQUIRED.
+ */
+export interface PimContract {
+    address?: HexAddress;
+    /** Logical name of a `lookups` entry that resolves the contract address. */
+    lookup?: string;
+    role: ContractRole;
+    description: string;
+}
+/** A field inside a named `types` entry. */
+export interface PimField {
+    type: string;
+    description?: string;
+    unit?: string;
+}
+/** One entry in `types` — a Solidity-struct-shaped tuple or array. */
+export interface PimType {
+    kind: TypeKind;
+    description?: string;
+    fields: Record<string, PimField>;
+}
+/**
+ * One field-level assertion inside `lookups.*.validate`.
+ *
+ * By convention at least one operator MUST be present; operator values MUST be
+ * strings.
+ */
+export interface PimValidateAssertion {
+    field: string;
+    notEqual?: string;
+    equals?: string;
+    greaterThan?: string;
+    lessThan?: string;
+}
+/** One entry in `lookups` — a named on-chain read (or simulated write). */
+export interface PimLookup {
+    description: string;
+    /** Logical contract name; MUST match a key in `contracts`. */
+    contract: string;
+    function: string;
+    /** Literal values, `{{template}}` references, or iterate values. */
+    args: unknown;
+    /** Named type (from `types`) or Solidity base unit type. */
+    returns: string;
+    iterate?: Record<string, unknown>;
+    filter?: Partial<Record<FilterOperator, string>>;
+    select?: SelectMode;
+    selectCriterion?: string;
+    validate?: PimValidateAssertion[];
+}
+/** One entry in `calculations` — a named off-chain computation. */
+export interface PimCalculation {
+    description: string;
+    /** Instruction object chain; MUST contain a `set` instruction. */
+    formula: Record<string, unknown>;
+    inputs?: string[];
+    outputUnit?: string;
+    precision?: CalculationPrecision;
+}
+/**
+ * One step inside an intent's ordering.
+ *
+ * Fields are shared by all actions except the `buildTransaction`-only ones
+ * (`contract`, `function`, `args`, `value`), which are optional on the type and
+ * validated contextually.
+ */
+export interface PimStep {
+    /** Unique within the intent; MUST start at 1 and not skip. */
+    id: number;
+    action: StepAction;
+    description?: string;
+    condition?: string;
+    skipIf?: string;
+    storeAs?: string;
+    /** `buildTransaction` only — logical contract name from `contracts`. */
+    contract?: string;
+    /** `buildTransaction` only. */
+    function?: string;
+    /** `buildTransaction` only — map of parameter name to value/template. */
+    args?: Record<string, unknown>;
+    /** `buildTransaction` only — wei sent with the call. */
+    value?: string;
+    /**
+     * `lookup` only — the named lookup this step runs.
+     *
+     * NOTE (unverified): the draft says lookups "are referenced by name in intent
+     * steps" but its all-step-types field table does not name the field. We use
+     * `lookup` to mirror the action; the validator only warns on a dangling name,
+     * it never rejects for it. See the README's "Unverified fields".
+     */
+    lookup?: string;
+}
+/** One entry in `intents` — a named, executable workflow. */
+export interface PimIntent {
+    description: string;
+    requiredInputs: string[];
+    optionalInputs?: string[];
+    notes?: string;
+    steps: PimStep[];
+}
+/**
+ * `ui` — display strings for wallets and agent interfaces.
+ *
+ * `intentDescriptions` is REQUIRED and MUST cover every named intent; `labels`
+ * and `iterateLabels` are RECOMMENDED/OPTIONAL.
+ */
+export interface PimUi {
+    labels?: Record<string, string>;
+    intentDescriptions: Record<string, string>;
+    iterateLabels?: Record<string, unknown>;
+}
+/** One entry in `signatures`. */
+export interface PimSignature {
+    /** Ethereum address that produced the signature; MUST be present for ecdsa. */
+    signer?: HexAddress;
+    /** keccak256 of the public key, for schemes with large keys (future). */
+    signerHashed?: Hex;
+    type: SignatureType;
+    signature: Hex;
+    signerLabel?: string;
+}
+/**
+ * One diagnostic emitted by {@link validatePim}. `path` is a dotted/bracketed
+ * locator into the document (empty for the root). An `error` MUST block
+ * execution; a `warning` MUST be surfaced but does not.
+ */
+export interface PimIssue {
+    path: string;
+    message: string;
+    severity: 'error' | 'warning';
+}
+/** A complete ERC-8313 Protocol Interaction Manifest. */
+export interface Pim {
+    schemaVersion: string;
+    metadata: PimMetadata;
+    contracts: Record<string, PimContract>;
+    types: Record<string, PimType>;
+    lookups: Record<string, PimLookup>;
+    calculations: Record<string, PimCalculation>;
+    intents: Record<string, PimIntent>;
+    ui: PimUi;
+    signatures: PimSignature[];
+}
+/** The nine mandatory top-level sections, in the standard's own order. */
+export declare const PIM_SECTIONS: readonly ["schemaVersion", "metadata", "contracts", "types", "lookups", "calculations", "intents", "ui", "signatures"];
+export type PimSection = (typeof PIM_SECTIONS)[number];
+/** Allowed values for `metadata.category`. */
+export declare const PIM_CATEGORIES: readonly PimCategory[];
+/** Allowed values for `contracts.*.role`. */
+export declare const CONTRACT_ROLES: readonly ContractRole[];
+/** Allowed values for `types.*.kind`. */
+export declare const TYPE_KINDS: readonly TypeKind[];
+/** Allowed values for `lookups.*.select`. */
+export declare const SELECT_MODES: readonly SelectMode[];
+/** Allowed operators for `lookups.*.filter`. */
+export declare const FILTER_OPERATORS: readonly FilterOperator[];
+/** Allowed operators for a `lookups.*.validate` assertion. */
+export declare const VALIDATE_OPERATORS: readonly ValidateOperator[];
+/** Allowed values for `calculations.*.precision`. */
+export declare const CALCULATION_PRECISIONS: readonly CalculationPrecision[];
+/** Allowed values for a step's `action`. */
+export declare const STEP_ACTIONS: readonly StepAction[];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,72 @@
+// ============================================================================
+// ERC-8313 Protocol Interaction Manifest (PIM) — TypeScript model.
+//
+// A PIM is a machine-readable JSON document describing *how* to interact with a
+// smart-contract protocol: not just its ABI, but the ordered workflow that
+// fulfils a user intent. This module mirrors the nine mandatory top-level
+// objects one-to-one, using the field names of the standard verbatim so a
+// serialised `Pim` is valid by construction.
+//
+// Aligned with the draft of 2026-06-19 (author Paul Angus Bark, PR #1836).
+// Field-level citations live next to each interface; where the draft is silent
+// or contradictory the comment says so explicitly rather than guessing.
+// ============================================================================
+/** The nine mandatory top-level sections, in the standard's own order. */
+export const PIM_SECTIONS = [
+    'schemaVersion',
+    'metadata',
+    'contracts',
+    'types',
+    'lookups',
+    'calculations',
+    'intents',
+    'ui',
+    'signatures',
+];
+/** Allowed values for `metadata.category`. */
+export const PIM_CATEGORIES = [
+    'dex',
+    'lending',
+    'staking',
+    'bridge',
+    'vault',
+    'nft',
+    'governance',
+    'other',
+];
+/** Allowed values for `contracts.*.role`. */
+export const CONTRACT_ROLES = [
+    'router',
+    'factory',
+    'pool',
+    'quoter',
+    'registry',
+    'gateway',
+    'oracle',
+    'vault',
+    'token',
+    'other',
+];
+/** Allowed values for `types.*.kind`. */
+export const TYPE_KINDS = ['tuple', 'array', 'primitive'];
+/** Allowed values for `lookups.*.select`. */
+export const SELECT_MODES = ['all', 'max', 'min'];
+/** Allowed operators for `lookups.*.filter`. */
+export const FILTER_OPERATORS = [
+    'notEqual',
+    'greaterThan',
+    'lessThan',
+    'equals',
+];
+/** Allowed operators for a `lookups.*.validate` assertion. */
+export const VALIDATE_OPERATORS = [
+    'notEqual',
+    'equals',
+    'greaterThan',
+    'lessThan',
+];
+/** Allowed values for `calculations.*.precision`. */
+export const CALCULATION_PRECISIONS = ['float', 'integer'];
+/** Allowed values for a step's `action`. */
+export const STEP_ACTIONS = ['lookup', 'calculate', 'buildTransaction'];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,EAAE;AACF,gFAAgF;AAChF,2EAA2E;AAC3E,0EAA0E;AAC1E,0EAA0E;AAC1E,6CAA6C;AAC7C,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,wEAAwE;AACxE,+EAA+E;AAuO/E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,eAAe;IACf,UAAU;IACV,WAAW;IACX,OAAO;IACP,SAAS;IACT,cAAc;IACd,SAAS;IACT,IAAI;IACJ,YAAY;CACJ,CAAC;AAIX,8CAA8C;AAC9C,MAAM,CAAC,MAAM,cAAc,GAA2B;IACpD,KAAK;IACL,SAAS;IACT,SAAS;IACT,QAAQ;IACR,OAAO;IACP,KAAK;IACL,YAAY;IACZ,OAAO;CACR,CAAC;AAEF,6CAA6C;AAC7C,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD,QAAQ;IACR,SAAS;IACT,MAAM;IACN,QAAQ;IACR,UAAU;IACV,SAAS;IACT,QAAQ;IACR,OAAO;IACP,OAAO;IACP,OAAO;CACR,CAAC;AAEF,yCAAyC;AACzC,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;AAE/E,6CAA6C;AAC7C,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEzE,gDAAgD;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD,UAAU;IACV,aAAa;IACb,UAAU;IACV,QAAQ;CACT,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAgC;IAC7D,UAAU;IACV,QAAQ;IACR,aAAa;IACb,UAAU;CACX,CAAC;AAEF,qDAAqD;AACrD,MAAM,CAAC,MAAM,sBAAsB,GAAoC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AAE5F,4CAA4C;AAC5C,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,QAAQ,EAAE,WAAW,EAAE,kBAAkB,CAAC,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,32 @@
+import { type PimIssue } from './types.js';
+export type { PimIssue } from './types.js';
+/** The spec revision this validator was written against. */
+export declare const PIM_DRAFT = "2026-06-19";
+export interface PimValidationOptions {
+    /**
+     * Current unix time (seconds). When provided, an expired `validUntil` or a
+     * not-yet-reached `validFrom` is an error — the standard says execution
+     * engines MUST reject such manifests.
+     */
+    now?: number;
+    /**
+     * The network the execution engine is on. When provided and absent from
+     * `metadata.chainId`, it is an error (chain mismatch).
+     */
+    chainId?: number;
+}
+export interface PimValidationResult {
+    valid: boolean;
+    /** Issues that MUST block execution. */
+    errors: PimIssue[];
+    /** Issues that do not block execution but should be surfaced. */
+    warnings: PimIssue[];
+}
+/**
+ * Validate an untrusted value as an ERC-8313 PIM.
+ *
+ * @param input - parsed JSON (or any value) to check.
+ * @param options - optional execution context (clock, chain).
+ */
+export declare function validatePim(input: unknown, options?: PimValidationOptions): PimValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAeA,OAAO,EAUL,KAAK,QAAQ,EACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,4DAA4D;AAC5D,eAAO,MAAM,SAAS,eAAe,CAAC;AAEtC,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,iEAAiE;IACjE,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACtB;AAeD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CAgCnG"}