@jinn-network/client 0.1.2 → 0.1.3-canary.24b69ea4

package/dist/solvernets/manifest.d.ts

@@ -0,0 +1,120 @@
+/**
+ * SolverNet manifest cryptography — canonicalize, hash, sign, verify.
+ *
+ * Implements the wire-format primitives for a `SolverNetManifestV1` per
+ * `spec/2026-05-05-solvernet-creation-and-launch.md` §6.3 and §7:
+ *
+ *   canonical = canonicalJson(manifest_without_signature)   // RFC 8785 JCS
+ *   hash      = sha256(canonical)                            // bytes32
+ *   signature = eip-191 personal_sign(hash) by launcher agent EOA
+ *
+ * Verification recovers the signer from the signature + canonical hash and,
+ * optionally, asserts the recovered signer agrees with the on-chain ERC-8004
+ * IdentityRegistry binding for `manifest.launcher.{agentId, safeAddress}`.
+ *
+ * The chain-binding check takes an `IdentityRegistryReader` interface so this
+ * module remains free of viem `PublicClient` plumbing and easy to mock. Task 4
+ * (`IdentityRegistryBackedSolverNetRegistryClient`) wires the real reader.
+ */
+import { type SolverNetManifestV1 } from '../vendor/@jinn-network/sdk/dist/solvernets/index.js';
+/**
+ * The manifest body sans `signature`. Used as the input shape to `signManifest`
+ * — callers assemble every field except the signature, then this module signs
+ * and returns the complete `SolverNetManifestV1`.
+ */
+export type UnsignedSolverNetManifestV1 = Omit<SolverNetManifestV1, 'signature'>;
+/**
+ * Read-side surface for the ERC-8004 IdentityRegistry, narrowed to the two
+ * lookups needed to verify a manifest's chain binding. The on-chain client is
+ * wired in Task 4; tests pass a fake here.
+ *
+ * Both methods accept an optional `atBlock` — the spec wants chain-binding
+ * verification to be reproducible at the exact block the manifest references,
+ * so callers can pin reads to a known head.
+ */
+export interface IdentityRegistryReader {
+    /**
+     * Resolve the agentId currently bound to `wallet`, or null when the registry
+     * has no record. `wallet` is the agent EOA that signed the manifest.
+     */
+    getAgentByWallet(wallet: `0x${string}`, atBlock?: bigint): Promise<{
+        agentId: string;
+    } | null>;
+    /**
+     * Resolve the master Safe address bound to `agentId`, or null when the
+     * registry has no record.
+     */
+    getSafeForAgent(agentId: string, atBlock?: bigint): Promise<`0x${string}` | null>;
+}
+/**
+ * Discriminated union: when `valid` is true, `signer` is guaranteed
+ * present; when false, `reason` is guaranteed present and `signer` is
+ * optional (set when recovery succeeded but mismatched the claim).
+ */
+export type VerifyManifestSignatureResult = {
+    valid: true;
+    signer: `0x${string}`;
+} | {
+    valid: false;
+    signer?: `0x${string}`;
+    reason: string;
+};
+export interface VerifyManifestAgainstChainResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Canonical JSON of a manifest with `signature` stripped. RFC 8785 JCS via
+ * the shared `canonicalJson` helper. Two independent verifiers that share a
+ * conforming JCS implementation reproduce this byte-for-byte.
+ */
+export declare function canonicalManifestJson(manifest: SolverNetManifestV1 | UnsignedSolverNetManifestV1): string;
+/**
+ * sha256 of the canonical manifest bytes — the bytes32 the launcher signs and
+ * the chain anchors via the launched-record (§6.2). Independent of the
+ * `signature` field.
+ */
+export declare function manifestHash(manifest: SolverNetManifestV1 | UnsignedSolverNetManifestV1): `0x${string}`;
+/**
+ * Sign an unsigned manifest with the launcher's agent EOA private key.
+ *
+ * Precondition: the address derived from `agentEoaPrivateKey` MUST equal
+ * `unsigned.launcher.agentEoa` (case-insensitive). If it does not, this
+ * throws immediately — failing here gives a clear "wrong key for the declared
+ * agent EOA" error rather than producing a manifest that fails downstream
+ * verification with a confusing recovered-vs-claimed signer mismatch.
+ *
+ * Steps (per §6.3 + §7):
+ *   1. canonicalManifestJson(unsigned)     // RFC 8785 JCS, signature stripped
+ *   2. sha256(canonical)                    // bytes32 hash
+ *   3. EIP-191 personal_sign(hash bytes)    // 65-byte signature
+ *
+ * Returns a complete `SolverNetManifestV1` with `signature` populated.
+ */
+export declare function signManifest(unsigned: UnsignedSolverNetManifestV1, agentEoaPrivateKey: `0x${string}`): Promise<SolverNetManifestV1>;
+/**
+ * Recover the signer from the manifest's signature and check it agrees with
+ * the manifest's `signature.signer` claim. Independent of any chain state.
+ *
+ * Returns `{ valid: false, reason }` for any failure mode (wrong alg, malformed
+ * signature, recovery mismatch). Never throws on input shape — the
+ * `SolverNetManifestV1Schema` validator handles top-level shape elsewhere; this
+ * helper only enforces the cryptographic invariant.
+ */
+export declare function verifyManifestSignature(manifest: SolverNetManifestV1): Promise<VerifyManifestSignatureResult>;
+/**
+ * Verify a manifest end-to-end against the ERC-8004 IdentityRegistry:
+ *
+ *   1. The cryptographic signature is valid and the recovered signer matches
+ *      `manifest.signature.signer`.
+ *   2. The recovered signer is bound on-chain to an agentId that equals
+ *      `manifest.launcher.agentId`.
+ *   3. That agentId is bound on-chain to a master Safe that equals
+ *      `manifest.launcher.safeAddress`.
+ *
+ * Failing the signature check short-circuits — the registry is not queried,
+ * so a tampered manifest costs no on-chain reads.
+ *
+ * Returns `{ valid: true }` on success, `{ valid: false, reason }` otherwise.
+ */
+export declare function verifyManifestAgainstChain(manifest: SolverNetManifestV1, registry: IdentityRegistryReader, atBlock?: bigint): Promise<VerifyManifestAgainstChainResult>;

package/dist/solvernets/manifest.js

@@ -0,0 +1,166 @@
+/**
+ * SolverNet manifest cryptography — canonicalize, hash, sign, verify.
+ *
+ * Implements the wire-format primitives for a `SolverNetManifestV1` per
+ * `spec/2026-05-05-solvernet-creation-and-launch.md` §6.3 and §7:
+ *
+ *   canonical = canonicalJson(manifest_without_signature)   // RFC 8785 JCS
+ *   hash      = sha256(canonical)                            // bytes32
+ *   signature = eip-191 personal_sign(hash) by launcher agent EOA
+ *
+ * Verification recovers the signer from the signature + canonical hash and,
+ * optionally, asserts the recovered signer agrees with the on-chain ERC-8004
+ * IdentityRegistry binding for `manifest.launcher.{agentId, safeAddress}`.
+ *
+ * The chain-binding check takes an `IdentityRegistryReader` interface so this
+ * module remains free of viem `PublicClient` plumbing and easy to mock. Task 4
+ * (`IdentityRegistryBackedSolverNetRegistryClient`) wires the real reader.
+ */
+import { sha256, recoverMessageAddress } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { canonicalJson } from '../harnesses/engine/canonical-json.js';
+// ── Canonical form ───────────────────────────────────────────────────────────
+/**
+ * Canonical JSON of a manifest with `signature` stripped. RFC 8785 JCS via
+ * the shared `canonicalJson` helper. Two independent verifiers that share a
+ * conforming JCS implementation reproduce this byte-for-byte.
+ */
+export function canonicalManifestJson(manifest) {
+    const { signature: _omit, ...body } = manifest;
+    return canonicalJson(body);
+}
+/**
+ * sha256 of the canonical manifest bytes — the bytes32 the launcher signs and
+ * the chain anchors via the launched-record (§6.2). Independent of the
+ * `signature` field.
+ */
+export function manifestHash(manifest) {
+    const canonical = canonicalManifestJson(manifest);
+    const bytes = new TextEncoder().encode(canonical);
+    // viem's `sha256` returns a lowercase 0x-prefixed 32-byte hex string when
+    // given a Uint8Array — exactly the bytes32 wire format we want.
+    return sha256(bytes);
+}
+// ── Sign / verify ────────────────────────────────────────────────────────────
+/**
+ * Sign an unsigned manifest with the launcher's agent EOA private key.
+ *
+ * Precondition: the address derived from `agentEoaPrivateKey` MUST equal
+ * `unsigned.launcher.agentEoa` (case-insensitive). If it does not, this
+ * throws immediately — failing here gives a clear "wrong key for the declared
+ * agent EOA" error rather than producing a manifest that fails downstream
+ * verification with a confusing recovered-vs-claimed signer mismatch.
+ *
+ * Steps (per §6.3 + §7):
+ *   1. canonicalManifestJson(unsigned)     // RFC 8785 JCS, signature stripped
+ *   2. sha256(canonical)                    // bytes32 hash
+ *   3. EIP-191 personal_sign(hash bytes)    // 65-byte signature
+ *
+ * Returns a complete `SolverNetManifestV1` with `signature` populated.
+ */
+export async function signManifest(unsigned, agentEoaPrivateKey) {
+    const account = privateKeyToAccount(agentEoaPrivateKey);
+    if (account.address.toLowerCase() !== unsigned.launcher.agentEoa.toLowerCase()) {
+        throw new Error(`agentEoaPrivateKey derives address ${account.address} but manifest.launcher.agentEoa is ${unsigned.launcher.agentEoa}`);
+    }
+    const hash = manifestHash(unsigned);
+    // EIP-191 personal_sign over the raw 32-byte hash. viem prepends the
+    // "\x19Ethereum Signed Message:\n32" prefix automatically when `message` is
+    // `{ raw: Hex }`.
+    const value = (await account.signMessage({ message: { raw: hash } }));
+    return {
+        ...unsigned,
+        signature: {
+            alg: 'eip-191',
+            signer: account.address,
+            value,
+        },
+    };
+}
+/**
+ * Recover the signer from the manifest's signature and check it agrees with
+ * the manifest's `signature.signer` claim. Independent of any chain state.
+ *
+ * Returns `{ valid: false, reason }` for any failure mode (wrong alg, malformed
+ * signature, recovery mismatch). Never throws on input shape — the
+ * `SolverNetManifestV1Schema` validator handles top-level shape elsewhere; this
+ * helper only enforces the cryptographic invariant.
+ */
+export async function verifyManifestSignature(manifest) {
+    if (manifest.signature.alg !== 'eip-191') {
+        return { valid: false, reason: `unsupported signature alg: ${manifest.signature.alg}` };
+    }
+    const hash = manifestHash(manifest);
+    let recovered;
+    try {
+        recovered = (await recoverMessageAddress({
+            message: { raw: hash },
+            signature: manifest.signature.value,
+        }));
+    }
+    catch (err) {
+        return {
+            valid: false,
+            reason: `recoverMessageAddress failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (recovered.toLowerCase() !== manifest.signature.signer.toLowerCase()) {
+        return {
+            valid: false,
+            signer: recovered,
+            reason: `recovered signer ${recovered} does not match signature.signer ${manifest.signature.signer}`,
+        };
+    }
+    return { valid: true, signer: recovered };
+}
+// ── Chain-binding verification ───────────────────────────────────────────────
+/**
+ * Verify a manifest end-to-end against the ERC-8004 IdentityRegistry:
+ *
+ *   1. The cryptographic signature is valid and the recovered signer matches
+ *      `manifest.signature.signer`.
+ *   2. The recovered signer is bound on-chain to an agentId that equals
+ *      `manifest.launcher.agentId`.
+ *   3. That agentId is bound on-chain to a master Safe that equals
+ *      `manifest.launcher.safeAddress`.
+ *
+ * Failing the signature check short-circuits — the registry is not queried,
+ * so a tampered manifest costs no on-chain reads.
+ *
+ * Returns `{ valid: true }` on success, `{ valid: false, reason }` otherwise.
+ */
+export async function verifyManifestAgainstChain(manifest, registry, atBlock) {
+    const sigResult = await verifyManifestSignature(manifest);
+    if (!sigResult.valid) {
+        return { valid: false, reason: sigResult.reason };
+    }
+    const signer = sigResult.signer;
+    const agentRecord = await registry.getAgentByWallet(signer, atBlock);
+    if (!agentRecord) {
+        return {
+            valid: false,
+            reason: `IdentityRegistry has no agent bound to signer wallet ${signer}`,
+        };
+    }
+    if (agentRecord.agentId !== manifest.launcher.agentId) {
+        return {
+            valid: false,
+            reason: `chain agentId (${agentRecord.agentId}) does not match manifest.launcher.agentId (${manifest.launcher.agentId})`,
+        };
+    }
+    const chainSafe = await registry.getSafeForAgent(agentRecord.agentId, atBlock);
+    if (!chainSafe) {
+        return {
+            valid: false,
+            reason: `IdentityRegistry has no Safe bound to agentId ${agentRecord.agentId}`,
+        };
+    }
+    if (chainSafe.toLowerCase() !== manifest.launcher.safeAddress.toLowerCase()) {
+        return {
+            valid: false,
+            reason: `chain Safe (${chainSafe}) does not match manifest.launcher.safeAddress (${manifest.launcher.safeAddress})`,
+        };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/solvernets/manifest.js.map

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

package/dist/solvernets/most-recent-wins.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Most-recent-wins resolver for SolverNet lifecycle events.
+ *
+ * Folds a stream of `IdentityRegistry.setMetadata` events with the
+ * `solvernet-manifest:<cid>` key prefix into the current lifecycle status of
+ * each unique (launcherAgentId, manifestCid) tuple.
+ *
+ * Per `spec/2026-05-05-solvernet-creation-and-launch.md` §6.3:
+ *
+ * > The most-recent-wins resolver picks the latest event per (agentId, cid)
+ * > tuple. Lifecycle authenticity flows from `msg.sender == launcher's agent
+ * > wallet` (enforced on-chain by IdentityRegistry's access control on
+ * > `setMetadata`).
+ *
+ * Tiebreak rule: when two events share `blockNumber`, the one with the higher
+ * `transactionIndex` wins (later in the block).
+ *
+ * Defensive: the resolver ignores any event whose `key` does not start with
+ * `solvernet-manifest:`. The subgraph fetcher should already filter, but the
+ * resolver does not trust upstream blindly.
+ *
+ * NOTE: this helper lives at `client/src/solvernets/most-recent-wins.ts` for
+ * now. Spec §6.3 references `client/src/network-trust/most-recent-wins.ts`,
+ * but `client/src/network-trust/` does not exist on this branch (it ships on
+ * `opus/network-trust-v0`). When that branch merges, consolidate.
+ */
+/**
+ * Decoded payload of a single `IdentityRegistry.setMetadata` event whose key
+ * is `solvernet-manifest:<cid>`. The shape mirrors §6.3 of the spec.
+ */
+export interface SetMetadataLifecyclePayload {
+    schemaVersion: string;
+    status: 'launched' | 'paused' | 'retired';
+    at: string;
+    hash: `0x${string}`;
+}
+/**
+ * Single setMetadata event row as supplied by the subgraph client.
+ *
+ * `key` is the full `solvernet-manifest:<cid>` string; `agentId` is the
+ * `launcherAgentId`; `payload` is the already-decoded lifecycle payload (the
+ * subgraph or registry client is responsible for JCS-decoding the bytes
+ * before handing them to the resolver).
+ */
+export interface SetMetadataEvent {
+    agentId: string;
+    key: string;
+    payload: SetMetadataLifecyclePayload;
+    blockNumber: number;
+    transactionIndex: number;
+}
+/**
+ * One row of resolved current-state-per-(agentId, cid).
+ *
+ * `anchorTransactionIndex` is the in-block transaction index of the winning
+ * setMetadata event — required as a secondary sort key when callers compare
+ * across multiple resolved rows (e.g. cross-launcher tiebreaks for the same
+ * cid, where two launchers wrote in the same block). Without it, the
+ * cross-row comparison would be non-deterministic (Map insertion order).
+ */
+export interface ResolvedLifecycle {
+    manifestCid: string;
+    launcherAgentId: string;
+    status: 'launched' | 'paused' | 'retired';
+    statusUpdatedAt: string;
+    manifestHash: `0x${string}`;
+    anchorBlock: number;
+    anchorTransactionIndex: number;
+}
+/**
+ * Fold a stream of setMetadata events into the current lifecycle status per
+ * (launcherAgentId, manifestCid) tuple. See file header for semantics.
+ *
+ * Order of returned rows is not specified — callers that need a stable order
+ * should sort by `manifestCid` (or another field) explicitly.
+ */
+export declare function resolveMostRecentWins(events: SetMetadataEvent[]): ResolvedLifecycle[];

package/dist/solvernets/most-recent-wins.js

@@ -0,0 +1,82 @@
+/**
+ * Most-recent-wins resolver for SolverNet lifecycle events.
+ *
+ * Folds a stream of `IdentityRegistry.setMetadata` events with the
+ * `solvernet-manifest:<cid>` key prefix into the current lifecycle status of
+ * each unique (launcherAgentId, manifestCid) tuple.
+ *
+ * Per `spec/2026-05-05-solvernet-creation-and-launch.md` §6.3:
+ *
+ * > The most-recent-wins resolver picks the latest event per (agentId, cid)
+ * > tuple. Lifecycle authenticity flows from `msg.sender == launcher's agent
+ * > wallet` (enforced on-chain by IdentityRegistry's access control on
+ * > `setMetadata`).
+ *
+ * Tiebreak rule: when two events share `blockNumber`, the one with the higher
+ * `transactionIndex` wins (later in the block).
+ *
+ * Defensive: the resolver ignores any event whose `key` does not start with
+ * `solvernet-manifest:`. The subgraph fetcher should already filter, but the
+ * resolver does not trust upstream blindly.
+ *
+ * NOTE: this helper lives at `client/src/solvernets/most-recent-wins.ts` for
+ * now. Spec §6.3 references `client/src/network-trust/most-recent-wins.ts`,
+ * but `client/src/network-trust/` does not exist on this branch (it ships on
+ * `opus/network-trust-v0`). When that branch merges, consolidate.
+ */
+const KEY_PREFIX = 'solvernet-manifest:';
+/**
+ * Extract the `<cid>` portion of a `solvernet-manifest:<cid>` key. Returns
+ * null if the key does not start with the expected prefix.
+ */
+function parseCid(key) {
+    if (!key.startsWith(KEY_PREFIX))
+        return null;
+    const cid = key.slice(KEY_PREFIX.length);
+    return cid.length > 0 ? cid : null;
+}
+/**
+ * Compare two events by recency. Returns true if `a` is more recent than
+ * `b`. Higher `blockNumber` wins; ties broken by higher `transactionIndex`.
+ */
+function isMoreRecent(a, b) {
+    if (a.blockNumber !== b.blockNumber)
+        return a.blockNumber > b.blockNumber;
+    return a.transactionIndex > b.transactionIndex;
+}
+/**
+ * Fold a stream of setMetadata events into the current lifecycle status per
+ * (launcherAgentId, manifestCid) tuple. See file header for semantics.
+ *
+ * Order of returned rows is not specified — callers that need a stable order
+ * should sort by `manifestCid` (or another field) explicitly.
+ */
+export function resolveMostRecentWins(events) {
+    // Map key: `${agentId}|${cid}` (cid is opaque base32/58, neither field
+    // contains `|`, so the join is unambiguous).
+    const latest = new Map();
+    for (const event of events) {
+        const cid = parseCid(event.key);
+        if (cid === null)
+            continue;
+        const tupleKey = `${event.agentId}|${cid}`;
+        const existing = latest.get(tupleKey);
+        if (existing === undefined || isMoreRecent(event, existing.event)) {
+            latest.set(tupleKey, { event, cid });
+        }
+    }
+    const out = [];
+    for (const { event, cid } of latest.values()) {
+        out.push({
+            manifestCid: cid,
+            launcherAgentId: event.agentId,
+            status: event.payload.status,
+            statusUpdatedAt: event.payload.at,
+            manifestHash: event.payload.hash,
+            anchorBlock: event.blockNumber,
+            anchorTransactionIndex: event.transactionIndex,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=most-recent-wins.js.map

package/dist/solvernets/most-recent-wins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"most-recent-wins.js","sourceRoot":"","sources":["../../src/solvernets/most-recent-wins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,UAAU,GAAG,qBAAqB,CAAC;AAgDzC;;;GAGG;AACH,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACzC,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,CAAmB,EAAE,CAAmB;IAC5D,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAAE,OAAO,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;IAC1E,OAAO,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,gBAAgB,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA0B;IAC9D,uEAAuE;IACvE,6CAA6C;IAC7C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoD,CAAC;IAE3E,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,GAAG,KAAK,IAAI;YAAE,SAAS;QAE3B,MAAM,QAAQ,GAAG,GAAG,KAAK,CAAC,OAAO,IAAI,GAAG,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,QAAQ,KAAK,SAAS,IAAI,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAClE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,KAAK,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QAC7C,GAAG,CAAC,IAAI,CAAC;YACP,WAAW,EAAE,GAAG;YAChB,eAAe,EAAE,KAAK,CAAC,OAAO;YAC9B,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM;YAC5B,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE;YACjC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI;YAChC,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,sBAAsB,EAAE,KAAK,CAAC,gBAAgB;SAC/C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}