@jinn-network/client 0.1.2 → 0.1.3-canary.2d6b2676

package/dist/erc8004/reputation.d.ts

@@ -0,0 +1,349 @@
+/**
+ * ERC-8004 ReputationRegistry surface.
+ *
+ * Wraps the deployed canonical ReputationRegistry (vanity 0x8004…) for
+ * Jinn's evaluator-delivery feedback flow.
+ *
+ * Per DR §4.3 (`docs/superpowers/specs/2026-04-27-erc-8004-entity-model-design.md`):
+ *
+ *   At evaluator-delivery settlement, the evaluator calls
+ *   `giveFeedback(harnessAgentId, ...)` with a body naming the specific
+ *   manifest CID / `evidenceHash` the verdict pertains to. Reputation
+ *   accrues to the operator's `agentId`; the body anchors which execution
+ *   the feedback is about.
+ *
+ * Canonical body convention (this module enforces it):
+ *
+ *   - `feedbackURI = "manifest:<cid>"`     — names the manifest being evaluated.
+ *   - `feedbackHash = manifestHash`        — bytes32 binds to a specific execution.
+ *
+ * The on-chain function signature uses `value: int128 / valueDecimals: uint8`
+ * (a signed fixed-point), not `score: uint8`. We expose a numeric-friendly
+ * `score` parameter on the higher-level surface and forward it as `value` here.
+ *
+ * Self-feedback guard: the contract reverts on self-feedback (caller cannot
+ * be the agent owner / approved / operator). For Jinn's typical deployment
+ * the evaluator is a different operator from the harness, so this is a no-op;
+ * but in single-operator dev/test setups the same Safe may evaluate its own
+ * restoration. Callers are expected to catch the revert and log gracefully —
+ * the evaluator's `claimDelivery` is the authoritative settlement, so a failed
+ * `giveFeedback` is non-fatal.
+ *
+ * Two layers live here:
+ *
+ *   1. `ReputationRegistryClient` — the typed wire-level wrapper.
+ *   2. `submitEvaluatorFeedback` + `mapVerdictToScore` — the engine-side
+ *      hook that maps an evaluator's verdict to a score and submits feedback.
+ *
+ * ── Harness-agentId resolution ─────────────────────────────────────────────
+ *
+ * Resolving the harness's `agentId` from the evaluator's perspective is
+ * deferred to `resolveAgentIdForManifest` in `./identity.js`. The hook here
+ * takes `harnessAgentId` as a direct input. The two natural resolution paths:
+ *
+ *   (b) subgraph query: `Operator { agentId } where executions_some: { manifestHash: <evidenceHash> }`
+ *   (c) on-chain scan of `IdentityRegistry.Registered` events for the
+ *       harness's Safe (`getAgentByWallet` is not exposed on-chain).
+ *
+ * Subgraph (b) is the cheapest and aligns with the rest of the discovery
+ * surface; (c) is the fallback when the subgraph is unavailable.
+ *
+ * ── Score-mapping policy ─────────────────────────────────────────────────────
+ *
+ * The portfolio.v0 evaluator emits a `verdict ∈ {PASS, FAIL, INDETERMINATE,
+ * REJECTED}` plus a numeric Calmar score (string). The reputation registry
+ * takes a signed fixed-point. The mapping policy below is intentionally
+ * conservative:
+ *
+ *   - PASS         → score = 100, scoreDecimals = 2 (= 1.00)  → submit feedback.
+ *   - FAIL         → score =   0, scoreDecimals = 2 (= 0.00)  → submit feedback.
+ *   - REJECTED     → no feedback. The harness was not eligible to attempt
+ *                    this task (e.g. minClosedTrades unmet); a 0-score
+ *                    feedback would unfairly tarnish their reputation for a
+ *                    structural mismatch, not a quality failure.
+ *   - INDETERMINATE → no feedback. The evaluator could not rederive
+ *                    (HL unreachable, post-snapshot funding accrual not
+ *                    settled). Not a verdict on the harness.
+ *
+ * If the impl emits a numeric score in `[0, 1]` separate from verdict, the
+ * caller should pre-multiply it by 100 and pass `scoreDecimals=2`.
+ *
+ * Address constants (cross-checked against `subgraph/networks.json` and
+ * `client/src/earning/contracts.ts` IdentityRegistry entries):
+ *
+ *   Base mainnet  0x8004BAa17C55a88189AE136b182e5fdA19dE9b63
+ *   Base Sepolia  0x8004B663056A597Dffe9eCcC1965A193B7388713
+ *   Ethereum      0x8004BAa17C55a88189AE136b182e5fdA19dE9b63
+ *   Sepolia       0x8004B663056A597Dffe9eCcC1965A193B7388713
+ */
+import { type Address, type Hex, type PublicClient, type WalletClient } from 'viem';
+import { REPUTATION_REGISTRY_ABI } from './abis.js';
+import { REPUTATION_REGISTRY_ADDRESSES, getReputationRegistryAddress } from './addresses.js';
+export { REPUTATION_REGISTRY_ABI, REPUTATION_REGISTRY_ADDRESSES, getReputationRegistryAddress, };
+/**
+ * Configuration for `ReputationRegistryClient`.
+ *
+ * `walletClient` is required for write paths (`giveFeedback`, `revokeFeedback`,
+ * `respondToFeedback`); read-only consumers may pass it as undefined.
+ *
+ * `safeAddress` (optional): when present, write transactions are routed
+ * through the Safe multisig via `executeSafeTransaction`, mirroring the rest
+ * of the client (claim/delivery flows already use Safe-routed sends so that
+ * the on-chain `msg.sender` matches the operator's canonical OLAS identity).
+ * When absent, writes are sent directly from `walletClient.account` (useful
+ * for tests and one-off operator scripts).
+ */
+export interface ReputationRegistryConfig {
+    reputationRegistryAddress: Address;
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+    /**
+     * Optional Safe multisig address. When set, write txs are routed through
+     * the Safe; when undefined, writes go directly from `walletClient.account`.
+     */
+    safeAddress?: Address;
+}
+/**
+ * One feedback entry as exposed by `readFeedback` / `readAllFeedback`.
+ *
+ * Fields map to the on-chain layout:
+ *   - `score` is the raw `int128 value` from storage (numerator).
+ *   - `scoreDecimals` is the decimal exponent (`value / 10^scoreDecimals`).
+ *   - `tag1`/`tag2`/`fileuri`/`filehash` mirror the `NewFeedback` event payload.
+ *     `fileuri` = `feedbackURI` on chain; `filehash` = `feedbackHash` on chain.
+ *     For Jinn evaluator feedback, `fileuri` is `"manifest:<cid>"` and
+ *     `filehash` is the manifest's `evidenceHash` (keccak256).
+ *
+ * `client`, `agentId`, and `feedbackIndex` together uniquely identify a row.
+ * Note: `readFeedback` does NOT return `fileuri` / `filehash` (those live only
+ * in the event log, not in storage); those fields are populated by
+ * `readAllFeedback` only when reconstructed from indexed events. The current
+ * client populates them from event-side data when available, otherwise they
+ * remain `undefined`.
+ */
+export interface FeedbackRecord {
+    agentId: bigint;
+    client: Address;
+    feedbackIndex: bigint;
+    /** Raw signed numerator from the contract (`int128`). */
+    score: bigint;
+    /** Decimal exponent (`score / 10^scoreDecimals`). */
+    scoreDecimals: number;
+    tag1?: string;
+    tag2?: string;
+    /** `feedbackURI` from the event payload (storage does not retain it). */
+    fileuri?: string;
+    /** `feedbackHash` from the event payload (storage does not retain it). */
+    filehash?: Hex;
+    revoked: boolean;
+}
+/** Identifies a specific feedback row for `respondToFeedback`. */
+export interface FeedbackId {
+    agentId: bigint;
+    client: Address;
+    feedbackIndex: bigint;
+}
+/** Shape returned by `getSummary` — reflects the on-chain tuple. */
+export interface FeedbackSummary {
+    count: bigint;
+    /** Mode-decimals normalised value (signed fixed-point numerator). */
+    summaryValue: bigint;
+    /** Decimal exponent for `summaryValue`. */
+    summaryValueDecimals: number;
+}
+export interface GiveFeedbackArgs {
+    /** ERC-8004 agentId of the harness being reviewed. */
+    harnessAgentId: bigint;
+    /** Numerator. e.g. 100 with `scoreDecimals=2` → 1.00. Range: int128. */
+    score: number | bigint;
+    /** Exponent: `score / 10^scoreDecimals`. Contract bounds: <= 18. */
+    scoreDecimals: number;
+    /**
+     * Canonical: `"manifest:<cid>"` or `"ipfs://<cid>"`. Names the specific
+     * manifest the verdict is about. Subgraph parses this to a `manifestRef`.
+     */
+    manifestRef: string;
+    /**
+     * 32-byte manifest hash (`evidenceHash` from `claimDelivery`). Binds the
+     * feedback to a specific execution.
+     */
+    manifestHash: Hex;
+    /**
+     * Optional tag (e.g. `"portfolio.v0"`). The first emitted `tag1` is also
+     * indexed on the event, which lets subgraphs filter by kind cheaply.
+     */
+    tag1?: string;
+    /** Optional tag — currently reserved for future use. */
+    tag2?: string;
+    /**
+     * Optional `endpoint` field — appears in the `NewFeedback` event but is
+     * not stored. Defaults to `""`. Reserved for future use; subgraph ignores.
+     */
+    endpoint?: string;
+}
+export interface RespondToFeedbackArgs {
+    feedbackId: FeedbackId;
+    responseURI: string;
+    responseHash: Hex;
+}
+export interface RevokeFeedbackArgs {
+    agentId: bigint;
+    feedbackIndex: bigint;
+}
+declare const ZERO_HASH: Hex;
+export declare class ReputationRegistryClient {
+    private readonly publicClient;
+    private readonly walletClient?;
+    private readonly contractAddress;
+    private readonly safeAddress?;
+    constructor(config: ReputationRegistryConfig);
+    /**
+     * Submit feedback on a harness's agent NFT. The body identifies the
+     * manifest being evaluated via `feedbackURI = "manifest:<cid>"` and
+     * `feedbackHash = manifestHash` (the evidenceHash committed in
+     * `claimDelivery`).
+     *
+     * Reverts (caught upstream and logged):
+     *   - "Self-feedback not allowed" — caller is owner/approved/operator of agentId.
+     *   - "ERC721NonexistentToken"   — agentId does not exist.
+     *   - "value too large"          — |score| > 1e38.
+     *   - "too many decimals"        — scoreDecimals > 18.
+     */
+    giveFeedback(args: GiveFeedbackArgs): Promise<Hex>;
+    /**
+     * Operator-facing: respond to a feedback on your own agent NFT.
+     * `msg.sender` becomes the responder; any address may call (the contract
+     * does not gate by ownership — multiple parties can append responses).
+     */
+    respondToFeedback(args: RespondToFeedbackArgs): Promise<Hex>;
+    /**
+     * Revoke previously-given feedback. The contract only allows the original
+     * caller (`msg.sender` on the original `giveFeedback`) to revoke; mirrored
+     * here by the routing decision in `sendWrite` (Safe vs EOA).
+     */
+    revokeFeedback(args: RevokeFeedbackArgs): Promise<Hex>;
+    readFeedback(args: {
+        agentId: bigint;
+        clientAddress: Address;
+        feedbackIndex: bigint;
+    }): Promise<FeedbackRecord | null>;
+    /**
+     * Read all feedback for an agentId. By default, queries every known client
+     * (the contract walks `_clients[agentId]` when `clientAddresses=[]` is
+     * passed — confirmed in the .sol, line ~268). Pass an explicit
+     * `clientAddresses` filter to narrow.
+     */
+    readAllFeedback(agentId: bigint, opts?: {
+        clientAddresses?: Address[];
+        tag1Filter?: string;
+        tag2Filter?: string;
+        includeRevoked?: boolean;
+    }): Promise<FeedbackRecord[]>;
+    /**
+     * Compute a summary across the supplied client addresses (or fail loudly —
+     * the on-chain `getSummary` reverts when called with an empty list, by
+     * design, to force callers to be explicit about which feedback sources
+     * they trust).
+     *
+     * Pass the result of `getClients(agentId)` to get a "summary across all
+     * known clients" — Jinn's typical surface.
+     */
+    getSummary(agentId: bigint, opts: {
+        clientAddresses: Address[];
+        tag1Filter?: string;
+        tag2Filter?: string;
+    }): Promise<FeedbackSummary>;
+    /** All addresses that have ever submitted feedback for this agentId. */
+    getClients(agentId: bigint): Promise<Address[]>;
+    /** Latest feedback index this client has submitted for `agentId`, or 0. */
+    getLastIndex(agentId: bigint, clientAddress: Address): Promise<bigint>;
+    /**
+     * Send a write tx, routing through the Safe when configured.
+     *
+     * Mirrors `ClaimRegistryClient` and `mech/contracts.ts`: production calls
+     * route through the Safe so `msg.sender` is the operator's canonical
+     * identity (matching the OLAS staking + 8004 IdentityRegistry agent NFT
+     * binding). Tests and one-off scripts can omit `safeAddress` and write
+     * directly from the EOA.
+     *
+     * `_unused` is reserved for value-bearing writes if any are added later;
+     * none of the Reputation surfaces are payable, so we always send 0.
+     */
+    private sendWrite;
+}
+export { ZERO_HASH };
+/** Harness-side outputs the hook needs to anchor the feedback on chain. */
+export interface HarnessExecutionRef {
+    /** ERC-8004 agentId of the harness being reviewed. */
+    harnessAgentId: bigint;
+    /** IPFS CID of the harness's manifest (NOT the evaluator's verdict). */
+    harnessManifestCid: string;
+    /** keccak256 of the harness's signed manifest = evidenceHash on JinnRouter. */
+    harnessEvidenceHash: Hex;
+}
+/** Verdict-side output of the evaluator. */
+export interface EvaluatorVerdict {
+    verdict: 'PASS' | 'FAIL' | 'INDETERMINATE' | 'REJECTED';
+    /**
+     * Optional solverType label (e.g. `"portfolio.v0"`). Emitted as `tag1` so
+     * downstream subgraphs can filter feedback by SolverType cheaply
+     * (`tag1` is indexed on the `NewFeedback` event).
+     */
+    solverType?: string;
+    /**
+     * Optional opaque tag2 — reserved for future use (e.g. evaluator software
+     * version). Default empty.
+     */
+    tag2?: string;
+}
+/** Mapped score input to `giveFeedback`. `null` means "do not submit". */
+export interface ScoreMapping {
+    score: number;
+    scoreDecimals: number;
+}
+/**
+ * Outcome of `submitEvaluatorFeedback`. The hook is fire-and-forget from the
+ * caller's perspective; this return type is for tests and observability.
+ */
+export type FeedbackHookOutcome = {
+    kind: 'submitted';
+    txHash: Hex;
+} | {
+    kind: 'skipped';
+    reason: 'verdict-not-eligible' | 'self-feedback' | 'agent-not-found';
+} | {
+    kind: 'failed';
+    error: string;
+};
+/**
+ * Pure function: map a verdict to (score, scoreDecimals). Returns `null` for
+ * verdicts that should not produce on-chain feedback (REJECTED, INDETERMINATE)
+ * — see policy comment at the top of the module.
+ *
+ * Exported so tests pin the policy directly.
+ */
+export declare function mapVerdictToScore(verdict: EvaluatorVerdict['verdict']): ScoreMapping | null;
+/**
+ * Submit feedback on the harness's agent NFT. The body is the canonical
+ * `manifest:<cid>` URI + `evidenceHash` — the subgraph parses these to
+ * synthesize an `Execution` row joined to the operator.
+ *
+ * Errors are caught and returned as `{ kind: 'failed', ... }` — callers
+ * (the engine's deliver path) should log the outcome but never let it
+ * propagate. The on-chain `claimDelivery` already settled.
+ *
+ * Self-feedback (caller is owner/approved/operator of `harnessAgentId`)
+ * reverts on chain with a known string; we surface that as a graceful
+ * `{ kind: 'skipped', reason: 'self-feedback' }`.
+ */
+export declare function submitEvaluatorFeedback(args: {
+    registry: ReputationRegistryClient;
+    ref: HarnessExecutionRef;
+    verdict: EvaluatorVerdict;
+    /** Optional logger; defaults to console.warn for failures. */
+    log?: (entry: {
+        level: 'info' | 'warn' | 'error';
+        msg: string;
+        data?: unknown;
+    }) => void;
+}): Promise<FeedbackHookOutcome>;