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

package/dist/solvernets/registry-client-erc8004.js

@@ -0,0 +1,382 @@
+/**
+ * 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 { canonicalJson } from '../harnesses/engine/canonical-json.js';
+import { canonicalManifestJson, manifestHash, } from './manifest.js';
+import { resolveMostRecentWins, } from './most-recent-wins.js';
+import { validateSolverNetManifest, } from '../vendor/@jinn-network/sdk/dist/solvernets/index.js';
+// ── Constants ────────────────────────────────────────────────────────────────
+/**
+ * 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 const SOLVERNET_MANIFEST_KEY_PREFIX = 'solvernet-manifest:';
+/**
+ * Schema version embedded in every lifecycle payload. Keep in sync with
+ * spec §6.3.
+ */
+export const LIFECYCLE_PAYLOAD_SCHEMA_VERSION = 'solvernet.lifecycle.v1';
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * 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 function encodeLifecyclePayload(payload) {
+    return new TextEncoder().encode(canonicalJson(payload));
+}
+// ── Implementation ──────────────────────────────────────────────────────────
+export class IdentityRegistryBackedSolverNetRegistryClient {
+    ipfs;
+    publisher;
+    subgraph;
+    network;
+    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.
+     */
+    manifestCache = new Map();
+    /**
+     * 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).
+     */
+    verifiedCids = new Set();
+    constructor(config) {
+        this.ipfs = config.ipfs;
+        this.publisher = config.publisher;
+        this.subgraph = config.subgraph;
+        this.network = config.network;
+        this.now = config.now ?? (() => new Date());
+    }
+    // ── Publish ───────────────────────────────────────────────────────────────
+    async publishManifest(args) {
+        const { manifest, signer } = args;
+        if (signer.agentId !== manifest.launcher.agentId) {
+            throw new Error(`signer.agentId (${signer.agentId}) does not match manifest.launcher.agentId (${manifest.launcher.agentId})`);
+        }
+        // Pin the canonical body (signature included — that IS the launched
+        // document). IPFS is content-addressed; the same body yields the same
+        // cid regardless of how many times we re-pin.
+        const manifestCid = await this.ipfs.upload(manifest);
+        // Cache the manifest so listLaunched can populate row fields without an
+        // IPFS round-trip. We're the publisher here, so the body is canonical
+        // by construction — mark the cid as verified so subsequent getManifest
+        // calls skip the subgraph re-verification round-trip.
+        this.manifestCache.set(manifestCid, manifest);
+        this.verifiedCids.add(manifestCid);
+        const lifecycle = {
+            schemaVersion: LIFECYCLE_PAYLOAD_SCHEMA_VERSION,
+            status: 'launched',
+            at: this.now().toISOString(),
+            hash: manifestHash(manifest),
+        };
+        const result = await this.publisher.setMetadata({
+            signer,
+            agentId: signer.agentId,
+            key: `${SOLVERNET_MANIFEST_KEY_PREFIX}${manifestCid}`,
+            value: encodeLifecyclePayload(lifecycle),
+        });
+        return {
+            manifestCid,
+            metadataTxHash: result.txHash,
+            metadataBlockNumber: result.blockNumber,
+        };
+    }
+    async publishLifecycleTransition(args) {
+        const { manifestCid, launcherAgentId, target, signer } = args;
+        if (signer.agentId !== launcherAgentId) {
+            throw new Error(`signer.agentId (${signer.agentId}) does not match launcherAgentId (${launcherAgentId})`);
+        }
+        // Look up the original manifest hash if we have it cached so the
+        // lifecycle payload re-asserts the canonical hash. If we don't have it
+        // (stateless re-launch from another process), recover by fetching IPFS
+        // and canonicalizing — fetchAndValidateManifest also verifies against
+        // the on-chain advertised hash so we don't sign over a tampered body.
+        //
+        // The cache-hit path skips both the subgraph round-trip and the IPFS
+        // fetch: the cached manifest was either published by us (canonical by
+        // construction) or already verified on a prior read (recorded in
+        // `verifiedCids`). Hashing the cached body locally is sufficient to
+        // populate the lifecycle payload.
+        const cached = this.manifestCache.get(manifestCid);
+        let hash;
+        if (cached !== undefined) {
+            hash = manifestHash(cached);
+        }
+        else {
+            const fetched = await this.fetchAndValidateManifest(manifestCid);
+            hash = manifestHash(fetched);
+        }
+        const lifecycle = {
+            schemaVersion: LIFECYCLE_PAYLOAD_SCHEMA_VERSION,
+            status: target,
+            at: this.now().toISOString(),
+            hash,
+        };
+        const result = await this.publisher.setMetadata({
+            signer,
+            agentId: launcherAgentId,
+            key: `${SOLVERNET_MANIFEST_KEY_PREFIX}${manifestCid}`,
+            value: encodeLifecyclePayload(lifecycle),
+        });
+        return {
+            metadataTxHash: result.txHash,
+            metadataBlockNumber: result.blockNumber,
+        };
+    }
+    // ── Read ──────────────────────────────────────────────────────────────────
+    async listLaunched(args) {
+        const events = await this.subgraph.fetchSetMetadataEvents({
+            keyPrefix: SOLVERNET_MANIFEST_KEY_PREFIX,
+            ...(args.sinceBlock !== undefined ? { sinceBlock: args.sinceBlock } : {}),
+        });
+        const resolved = resolveMostRecentWins(events);
+        const filterByStatus = args.statusFilter;
+        const out = [];
+        for (const row of resolved) {
+            if (filterByStatus !== undefined && !filterByStatus.includes(row.status)) {
+                continue;
+            }
+            // Fetch the manifest body so we can populate the catalog-row fields.
+            // Cache hit avoids the IPFS round-trip for rows we've published or
+            // read in this process.
+            let manifest;
+            try {
+                manifest = await this.fetchAndValidateManifest(row.manifestCid, row.manifestHash);
+            }
+            catch {
+                // Skip rows whose IPFS body can't be fetched/validated. Operators
+                // see "missing/tampered manifest" rows nowhere, which is
+                // intentional — the catalog should not surface broken entries.
+                continue;
+            }
+            // Per-network filter — the registry is global; the catalog is
+            // chain-scoped. `args.network` is what the operator asked for; the
+            // constructor's `this.network` is the chain this client serves and
+            // is informational only.
+            if (manifest.network !== args.network)
+                continue;
+            out.push({
+                manifestCid: row.manifestCid,
+                solverNetId: manifest.solverNetId,
+                name: manifest.name,
+                network: manifest.network,
+                launcherAgentId: row.launcherAgentId,
+                launcherSafeAddress: manifest.launcher.safeAddress,
+                status: row.status,
+                statusUpdatedAt: row.statusUpdatedAt,
+                contractId: manifest.contract.id,
+                contractVersion: manifest.contract.version,
+                solutionPriceWei: manifest.solutionPriceWei,
+                verdictPriceWei: manifest.verdictPriceWei,
+                openRoles: manifest.openRoles,
+                anchorBlock: row.anchorBlock,
+            });
+        }
+        return out;
+    }
+    async getManifest(args) {
+        const cached = this.manifestCache.get(args.manifestCid);
+        // Fast path: cid was verified in this process — either we published it
+        // (canonical by construction) or we previously verified its hash
+        // against the on-chain advertised hash. Trust the cached body without
+        // hitting the subgraph. Skipping this re-verification is what keeps
+        // catalog refresh ticks from doubling subgraph load.
+        if (cached !== undefined && this.verifiedCids.has(args.manifestCid)) {
+            return cached;
+        }
+        if (cached !== undefined) {
+            // Cached but not yet marked verified (shouldn't happen with the
+            // current cache-population paths, which always mark verified, but
+            // we keep this branch defensive). Verify hash against on-chain
+            // advertised hash if any setMetadata events exist for this cid.
+            const events = await this.subgraph.fetchSetMetadataEventsForCid({
+                manifestCid: args.manifestCid,
+            });
+            if (events.length > 0) {
+                const advertised = this.latestAdvertisedHash(events);
+                const actual = manifestHash(cached);
+                if (advertised !== null && advertised.toLowerCase() !== actual.toLowerCase()) {
+                    throw new Error(`manifest hash mismatch for cid ${args.manifestCid}: ipfs=${actual} chain=${advertised}`);
+                }
+            }
+            this.verifiedCids.add(args.manifestCid);
+            return cached;
+        }
+        return this.fetchAndValidateManifest(args.manifestCid);
+    }
+    async getManifestFromCache(args) {
+        // Cache-only: never falls through to IPFS. Used by hot-path callers
+        // (e.g. the daemon's `/v1/solvernets/launched` list endpoint) that
+        // would otherwise hit IPFS once per row. The cache is populated when
+        // we publish a manifest or successfully read one through `getManifest`,
+        // so for SolverNets the daemon launched itself the cache is always
+        // warm. For records observed only via subgraph (other launchers),
+        // callers see `null` here and fall back to whatever degraded surface
+        // they prefer — for the launched-list endpoint, omitting `summary`
+        // entirely.
+        const cached = this.manifestCache.get(args.manifestCid);
+        return cached ?? null;
+    }
+    async getLifecycleStatus(args) {
+        const events = await this.subgraph.fetchSetMetadataEventsForCid({
+            manifestCid: args.manifestCid,
+        });
+        if (events.length === 0) {
+            throw new Error(`no setMetadata events for manifestCid ${args.manifestCid}`);
+        }
+        const resolved = resolveMostRecentWins(events);
+        if (resolved.length === 0) {
+            throw new Error(`no setMetadata events with solvernet-manifest: prefix for cid ${args.manifestCid}`);
+        }
+        // For a single cid, all resolved rows share the cid. If multiple
+        // launchers wrote under the same cid (unusual but legal), pick the
+        // most recent across all of them by (anchorBlock, anchorTransactionIndex)
+        // lexicographic order — without the secondary key, same-block ties
+        // would resolve in Map insertion order (non-deterministic).
+        const latest = resolved.reduce((acc, cur) => {
+            if (cur.anchorBlock !== acc.anchorBlock) {
+                return cur.anchorBlock > acc.anchorBlock ? cur : acc;
+            }
+            return cur.anchorTransactionIndex > acc.anchorTransactionIndex ? cur : acc;
+        });
+        return {
+            status: latest.status,
+            statusUpdatedAt: latest.statusUpdatedAt,
+            sourceBlock: latest.anchorBlock,
+        };
+    }
+    // ── Internals ─────────────────────────────────────────────────────────────
+    /**
+     * 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`.
+     */
+    async fetchAndValidateManifest(manifestCid, expectedHash) {
+        const raw = await this.ipfs.fetch(manifestCid);
+        const validation = validateSolverNetManifest(raw);
+        if (!validation.ok) {
+            const issueSummary = validation.issues
+                .slice(0, 3)
+                .map((i) => `${i.path}: ${i.message}`)
+                .join('; ');
+            throw new Error(`IPFS body for cid ${manifestCid} is not a valid SolverNetManifestV1 (${issueSummary})`);
+        }
+        const manifest = validation.value;
+        let hash = expectedHash ?? null;
+        if (hash === null) {
+            const events = await this.subgraph.fetchSetMetadataEventsForCid({
+                manifestCid,
+            });
+            if (events.length > 0) {
+                hash = this.latestAdvertisedHash(events);
+            }
+        }
+        if (hash !== null) {
+            const actual = manifestHash(manifest);
+            if (actual.toLowerCase() !== hash.toLowerCase()) {
+                throw new Error(`manifest hash mismatch for cid ${manifestCid}: ipfs=${actual} chain=${hash}`);
+            }
+        }
+        // Sanity: re-canonicalizing the parsed manifest should equal what the
+        // hash check just verified. This is implied by the hash match above,
+        // but the call also exercises the canonical-JSON path on read so a
+        // canonicalization regression surfaces here, not later.
+        void canonicalManifestJson(manifest);
+        this.manifestCache.set(manifestCid, manifest);
+        // Mark the cid verified iff we cross-checked the canonical hash
+        // against an on-chain advertised hash. Without an on-chain reference
+        // (no events for this cid yet) we still cache for performance, but
+        // refrain from short-circuiting future hash checks.
+        if (hash !== null) {
+            this.verifiedCids.add(manifestCid);
+        }
+        return manifest;
+    }
+    /**
+     * 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`.
+     */
+    latestAdvertisedHash(events) {
+        const resolved = resolveMostRecentWins(events);
+        if (resolved.length === 0)
+            return null;
+        const latest = resolved.reduce((acc, cur) => {
+            if (cur.anchorBlock !== acc.anchorBlock) {
+                return cur.anchorBlock > acc.anchorBlock ? cur : acc;
+            }
+            return cur.anchorTransactionIndex > acc.anchorTransactionIndex ? cur : acc;
+        });
+        return latest.manifestHash;
+    }
+}
+//# sourceMappingURL=registry-client-erc8004.js.map

package/dist/solvernets/registry-client-erc8004.js.map

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

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

@@ -0,0 +1,121 @@
+/**
+ * SolverNet registry client interface.
+ *
+ * Abstract surface for publishing and reading SolverNet launched-instance
+ * authority documents (manifests) and their lifecycle status. Per
+ * `spec/2026-05-05-solvernet-creation-and-launch.md` §13: the operator app
+ * depends on this interface so the day-1 IdentityRegistry+subgraph backing can
+ * be replaced later (alternative IPFS gateway, future on-chain SolverNet
+ * registry contract, etc.) without touching the manifest schema or operator
+ * flow.
+ *
+ * INTERFACE ONLY. The day-1 concrete implementation
+ * (`IdentityRegistryBackedSolverNetRegistryClient`) lands in Task 4 and wires:
+ *   - publishManifest / publishLifecycleTransition → IdentityRegistry.setMetadata
+ *   - listLaunched / getLifecycleStatus            → subgraph (most-recent-wins)
+ *   - getManifest                                  → IPFS via `client/src/adapters/mech/ipfs.ts`
+ */
+import type { SolverNetManifestV1 } from '../vendor/@jinn-network/sdk/dist/solvernets/index.js';
+/**
+ * Minimal "ready to sign" handle for the launcher's agent EOA. Held by the
+ * registry client implementation to (a) sign manifests via `signManifest` and
+ * (b) send the on-chain `setMetadata` tx that anchors the manifest CID.
+ *
+ * Kept data-only on purpose: no viem `Account`, no signer abstraction. This
+ * makes test doubles trivial and avoids leaking viem types into the interface.
+ * The Task 4 implementation derives the viem account from `agentEoaPrivateKey`
+ * at the call site.
+ *
+ * `agentId` is included for convenience so the implementation does not have to
+ * round-trip the IdentityRegistry to look it up before publishing.
+ */
+export interface SignerWithAgentEoa {
+    agentEoaAddress: `0x${string}`;
+    agentEoaPrivateKey: `0x${string}`;
+    agentId: string;
+}
+/**
+ * Catalog-row projection of a launched SolverNet — the minimum useful shape
+ * for the operator catalog UI and join flow. `listLaunched` returns these;
+ * the full manifest is fetched on demand via `getManifest`.
+ *
+ * `status` and `statusUpdatedAt` reflect the most-recent-wins resolution of
+ * the launcher's lifecycle transitions (§13 day-1 implementation note).
+ *
+ * Lives next to the interface (not in the SDK) until a second consumer
+ * appears; promotable later without breaking callers.
+ */
+export interface SolverNetManifestSummary {
+    manifestCid: string;
+    solverNetId: string;
+    name: string;
+    network: string;
+    launcherAgentId: string;
+    launcherSafeAddress: `0x${string}`;
+    status: 'launched' | 'paused' | 'retired';
+    statusUpdatedAt: string;
+    contractId: string;
+    contractVersion: string;
+    solutionPriceWei: string;
+    verdictPriceWei: string;
+    openRoles: Array<'solver' | 'evaluator'>;
+    anchorBlock: number;
+}
+/**
+ * Abstract registry client. Five methods, mirroring spec §13 exactly.
+ *
+ * Publish-side (`publishManifest`, `publishLifecycleTransition`) require a
+ * `SignerWithAgentEoa` — they sign and broadcast on the launcher's behalf.
+ * Read-side (`listLaunched`, `getManifest`, `getLifecycleStatus`) are
+ * permissionless lookups that do not need a signer.
+ */
+export interface SolverNetRegistryClient {
+    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>;
+    /**
+     * Cache-only manifest lookup. Returns the cached manifest body if the
+     * client has previously seen this cid (via publish or read), or `null`
+     * otherwise. Never falls through to IPFS — the goal is server-side hot-
+     * path enrichment (e.g. embedding manifest summaries in list responses)
+     * where an IPFS round-trip per row would be unacceptable. Callers that
+     * need the full IPFS-validated body should use `getManifest`.
+     *
+     * Synchronous in spirit (the day-1 implementation reads a Map), but typed
+     * as `Promise` to keep the interface symmetric with the rest of the API
+     * and to allow future implementations to back the cache with async
+     * storage (e.g. SQLite) without a breaking change.
+     */
+    getManifestFromCache(args: {
+        manifestCid: string;
+    }): Promise<SolverNetManifestV1 | null>;
+    getLifecycleStatus(args: {
+        manifestCid: string;
+    }): Promise<{
+        status: 'launched' | 'paused' | 'retired';
+        statusUpdatedAt: string;
+        sourceBlock: number;
+    }>;
+}

package/dist/solvernets/registry-client.js

@@ -0,0 +1,19 @@
+/**
+ * SolverNet registry client interface.
+ *
+ * Abstract surface for publishing and reading SolverNet launched-instance
+ * authority documents (manifests) and their lifecycle status. Per
+ * `spec/2026-05-05-solvernet-creation-and-launch.md` §13: the operator app
+ * depends on this interface so the day-1 IdentityRegistry+subgraph backing can
+ * be replaced later (alternative IPFS gateway, future on-chain SolverNet
+ * registry contract, etc.) without touching the manifest schema or operator
+ * flow.
+ *
+ * INTERFACE ONLY. The day-1 concrete implementation
+ * (`IdentityRegistryBackedSolverNetRegistryClient`) lands in Task 4 and wires:
+ *   - publishManifest / publishLifecycleTransition → IdentityRegistry.setMetadata
+ *   - listLaunched / getLifecycleStatus            → subgraph (most-recent-wins)
+ *   - getManifest                                  → IPFS via `client/src/adapters/mech/ipfs.ts`
+ */
+export {};
+//# sourceMappingURL=registry-client.js.map

package/dist/solvernets/registry-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-client.js","sourceRoot":"","sources":["../../src/solvernets/registry-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}