@jinn-network/client 0.1.2 → 0.1.3-canary.12cf8b76

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"}

package/dist/solvernets/registry-client-erc8004.d.ts

@@ -0,0 +1,239 @@
+/**
+ * IdentityRegistry-backed `SolverNetRegistryClient` implementation.
+ *
+ * Day-1 wiring of the abstract interface from `registry-client.ts`:
+ *
+ *   - publishManifest                → IPFS pin (canonical JCS) + IdentityRegistry.setMetadata
+ *   - publishLifecycleTransition     → IdentityRegistry.setMetadata (same key, updated payload)
+ *   - listLaunched                   → SubgraphClient.fetchSetMetadataEvents + most-recent-wins
+ *   - getManifest                    → IPFS fetch + canonical-hash verification + schema validation
+ *   - getLifecycleStatus             → SubgraphClient.fetchSetMetadataEventsForCid + most-recent-wins
+ *
+ * Design choices, per `spec/2026-05-05-solvernet-creation-and-launch.md` §6:
+ *
+ * - **Payload encoding** is JCS-canonical UTF-8 JSON bytes — *not* the
+ *   ABI-encoded execution-payload tuple used by `IdentityPublisher`. The two
+ *   surfaces use the same `setMetadata(agentId, key, bytes)` ABI but carry
+ *   different payload schemas; `solvernet.lifecycle.v1` is plain JSON because
+ *   the document is human-readable lifecycle metadata, not a tight on-chain
+ *   tuple. JCS-encoding keeps reproducibility across implementations.
+ *
+ * - **Key shape** is `solvernet-manifest:<cid>` — the same `<kind>:<cid>`
+ *   pattern as execution envelopes (`envelope:<cid>`), one prefix per kind.
+ *
+ * - **Idempotency**: re-publishing the same canonical content yields the
+ *   same cid (IPFS is content-addressed); re-firing `setMetadata` with the
+ *   same args produces another event but is harmless — the most-recent-wins
+ *   resolver still picks the latest.
+ *
+ * - **Network filtering**: the registry is global (no agentId filter), but
+ *   the manifest itself records its target network. `listLaunched` filters
+ *   summaries by the constructor's `network` so operators only see manifests
+ *   for their chain. (The chain identity already lives in the manifest body
+ *   per §7.)
+ *
+ * - **Hash verification on read**: `getManifest` always cross-checks the
+ *   canonical hash of the fetched IPFS content against the on-chain
+ *   advertised hash from the latest setMetadata event. A tampered IPFS
+ *   pinner cannot make us return a manifest whose content disagrees with
+ *   what the launcher anchored on-chain.
+ *
+ * Construction takes a deps bag (IPFS / publisher / subgraph) so tests can
+ * inject mocks. The interfaces here are deliberately small — a future
+ * replacement (alternative gateway, on-chain SolverNet registry contract)
+ * can swap implementations without touching the operator flow per
+ * spec §13.
+ *
+ * `most-recent-wins.ts` is reused for both `listLaunched` and
+ * `getLifecycleStatus`.
+ */
+import { type SetMetadataEvent, type SetMetadataLifecyclePayload } from './most-recent-wins.js';
+import { type SolverNetManifestV1 } from '../vendor/@jinn-network/sdk/dist/solvernets/index.js';
+import type { SolverNetRegistryClient, SolverNetManifestSummary, SignerWithAgentEoa } from './registry-client.js';
+/**
+ * Metadata-key prefix for SolverNet manifest anchors. The full key is
+ * `solvernet-manifest:<cid>`; the prefix alone is what we hand to the
+ * subgraph for `LIKE 'solvernet-manifest:%'` filtering.
+ */
+export declare const SOLVERNET_MANIFEST_KEY_PREFIX = "solvernet-manifest:";
+/**
+ * Schema version embedded in every lifecycle payload. Keep in sync with
+ * spec §6.3.
+ */
+export declare const LIFECYCLE_PAYLOAD_SCHEMA_VERSION = "solvernet.lifecycle.v1";
+/**
+ * IPFS surface used by the registry client. Two methods, content-addressed.
+ *
+ * `upload` accepts an arbitrary serializable object (typically the manifest
+ * itself). Implementations are expected to canonicalize via JCS (RFC 8785) so
+ * that re-uploading the same logical content yields the same CID — the
+ * existing `client/src/adapters/mech/ipfs.ts#uploadToIpfs` already does this.
+ *
+ * `fetch` returns the parsed JSON body (the helper in `mech/ipfs.ts` returns
+ * `unknown`; callers narrow the type at the call site).
+ */
+export interface IpfsClient {
+    upload(data: unknown): Promise<string>;
+    fetch(cid: string): Promise<unknown>;
+}
+/**
+ * Result of a single `setMetadata` write — what the publisher returns and
+ * what `publishManifest` / `publishLifecycleTransition` propagate.
+ */
+export interface SetMetadataPublishResult {
+    txHash: `0x${string}`;
+    blockNumber: number;
+}
+/**
+ * Abstract handle for publishing `IdentityRegistry.setMetadata` writes.
+ *
+ * The existing `IdentityPublisher` (`client/src/erc8004/identity.ts`) is
+ * specialised to the ABI-encoded execution payload tuple; SolverNet
+ * lifecycle payloads are a different schema (JCS-canonical JSON bytes), so
+ * we abstract via a small interface that takes raw `value` bytes. The Task
+ * 5+ wiring will provide a viem-backed implementation; tests mock this.
+ *
+ * `signer` is plumbed through for implementations that need it (e.g. to
+ * derive the agent-EOA private key for the wallet client). The mock test
+ * publisher ignores it.
+ */
+export interface MetadataPublisher {
+    setMetadata(args: {
+        signer: SignerWithAgentEoa;
+        agentId: string;
+        key: string;
+        value: Uint8Array;
+    }): Promise<SetMetadataPublishResult>;
+}
+/**
+ * Subgraph surface used by the registry client. Two queries:
+ *
+ *   - `fetchSetMetadataEvents` — broad scan by key prefix, used by
+ *     `listLaunched`. Optional `sinceBlock` for incremental sync.
+ *   - `fetchSetMetadataEventsForCid` — narrow lookup by full key (cid),
+ *     used by `getLifecycleStatus`.
+ *
+ * The Jinn subgraph already indexes `IdentityRegistry.setMetadata` events
+ * with `(agentId, key, value, blockNumber, transactionIndex)` rows; this
+ * interface narrows that to what the registry client needs.
+ *
+ * NOTE: at time of writing the subgraph has *not* surfaced this query
+ * shape. A follow-up task (Phase 7 / subgraph extension) wires the real
+ * GraphQL — see DONE_WITH_CONCERNS in the task report.
+ */
+export interface SubgraphClient {
+    fetchSetMetadataEvents(args: {
+        keyPrefix: string;
+        sinceBlock?: number;
+    }): Promise<SetMetadataEvent[]>;
+    fetchSetMetadataEventsForCid(args: {
+        manifestCid: string;
+    }): Promise<SetMetadataEvent[]>;
+}
+export interface IdentityRegistryBackedSolverNetRegistryClientConfig {
+    ipfs: IpfsClient;
+    publisher: MetadataPublisher;
+    subgraph: SubgraphClient;
+    /**
+     * Network for which this client serves operator catalog rows. Used to
+     * filter `listLaunched` summaries — manifests record their target network
+     * in `manifest.network` per spec §7.
+     */
+    network: 'base-sepolia' | 'base';
+    /**
+     * Override `Date.now()` for ISO timestamps in published lifecycle
+     * payloads. Mainly for deterministic tests.
+     */
+    now?: () => Date;
+}
+/**
+ * Encode a lifecycle payload into JCS-canonical UTF-8 JSON bytes — the on-wire
+ * format passed to `IdentityRegistry.setMetadata` for `solvernet.lifecycle.v1`.
+ *
+ * Exported so the launch state machine (`launch-state-machine.ts`) can encode
+ * the same payload shape without duplicating the JCS canonicalization.
+ */
+export declare function encodeLifecyclePayload(payload: SetMetadataLifecyclePayload): Uint8Array;
+export declare class IdentityRegistryBackedSolverNetRegistryClient implements SolverNetRegistryClient {
+    private readonly ipfs;
+    private readonly publisher;
+    private readonly subgraph;
+    private readonly network;
+    private readonly now;
+    /**
+     * In-process cache of manifests we've published or read. Used so
+     * `listLaunched` can populate per-row catalog fields (name, contract,
+     * prices, openRoles) without forcing a synchronous IPFS fetch for every
+     * row. The catalog UI gets a coarse view from the subgraph + cache, and
+     * the full manifest is fetched on demand via `getManifest`.
+     *
+     * For rows whose manifest has not been seen yet (other launchers), the
+     * cache miss falls through to a real IPFS fetch — which lets the catalog
+     * stay accurate at the cost of some latency. The Task 6 daemon-side
+     * SolverNetCatalog will likely add a persistent cache.
+     */
+    private readonly manifestCache;
+    /**
+     * Set of cids whose cached manifest body has been verified against the
+     * on-chain advertised hash (or where we ourselves were the publisher and
+     * therefore know the body is canonical). Once a cid lands here,
+     * `getManifest` short-circuits the subgraph round-trip on subsequent
+     * cache hits — without this set, every cache hit re-verified by hitting
+     * the subgraph, silently doubling subgraph load in catalog refresh ticks
+     * (daemon polling scenarios).
+     */
+    private readonly verifiedCids;
+    constructor(config: IdentityRegistryBackedSolverNetRegistryClientConfig);
+    publishManifest(args: {
+        manifest: SolverNetManifestV1;
+        signer: SignerWithAgentEoa;
+    }): Promise<{
+        manifestCid: string;
+        metadataTxHash: `0x${string}`;
+        metadataBlockNumber: number;
+    }>;
+    publishLifecycleTransition(args: {
+        manifestCid: string;
+        launcherAgentId: string;
+        target: 'launched' | 'paused' | 'retired';
+        signer: SignerWithAgentEoa;
+    }): Promise<{
+        metadataTxHash: `0x${string}`;
+        metadataBlockNumber: number;
+    }>;
+    listLaunched(args: {
+        network: string;
+        statusFilter?: Array<'launched' | 'paused' | 'retired'>;
+        sinceBlock?: number;
+    }): Promise<SolverNetManifestSummary[]>;
+    getManifest(args: {
+        manifestCid: string;
+    }): Promise<SolverNetManifestV1>;
+    getManifestFromCache(args: {
+        manifestCid: string;
+    }): Promise<SolverNetManifestV1 | null>;
+    getLifecycleStatus(args: {
+        manifestCid: string;
+    }): Promise<{
+        status: 'launched' | 'paused' | 'retired';
+        statusUpdatedAt: string;
+        sourceBlock: number;
+    }>;
+    /**
+     * Fetch a manifest from IPFS, validate the schema, and (when available)
+     * cross-check the canonical hash against the on-chain advertised hash.
+     *
+     * `expectedHash`, when provided by the caller (e.g. `listLaunched` already
+     * has it from the resolved row), short-circuits the per-cid subgraph
+     * round-trip in `getManifest`.
+     */
+    private fetchAndValidateManifest;
+    /**
+     * Pick the manifest hash advertised by the most recent setMetadata event
+     * for a cid. Returns null if no events match.
+     *
+     * Cross-launcher ties on the same block are broken by the higher
+     * `anchorTransactionIndex` — same lexicographic rule as `getLifecycleStatus`.
+     */
+    private latestAdvertisedHash;
+}