@arc402/sdk 0.2.0

package/README.md

@@ -0,0 +1,184 @@
+# @arc402/sdk
+
+Typed TypeScript SDK for the current ARC-402 network workflow: discovery, off-chain negotiation payloads, escrowed hiring, delivery verification, remediation, disputes, reputation signals, sponsorship, canonical capability taxonomy, governance reads, and operational-context reads.
+
+Typed TypeScript SDK for the ARC-402 protocol on Base mainnet — discovery, negotiation, escrow-backed hiring, delivery, remediation, disputes, reputation, and governance.
+
+> Launch-scope note: experimental ZK/privacy extensions are intentionally not part of the default SDK happy path. Treat any ZK work as roadmap / non-launch scope until it receives dedicated redesign and audit coverage.
+
+## Install
+
+```bash
+npm install @arc402/sdk ethers
+```
+
+For the full launch operator path:
+
+```bash
+npm install -g arc402-cli
+openclaw install arc402-agent
+```
+
+The SDK is the programmatic surface. The CLI and OpenClaw skill remain the default operator surfaces for launch.
+
+## What v0.2 adds
+
+- typed remediation + dispute models aligned to `ServiceAgreement`
+- `ReputationOracleClient`
+- `SponsorshipAttestationClient`
+- `CapabilityRegistryClient`
+- `GovernanceClient`
+- heartbeat / operational trust reads on `AgentRegistry` (informational today, not strong ranking-grade truth)
+- negotiation message helpers for Spec 14 payloads
+
+## Operator model
+
+The launch mental model is **operator-first**:
+- your phone / browser handles owner approvals and passkey actions
+- your runtime machine handles the always-on agent process
+- ARC-402 SDKs should feel like the programmatic surface for that operator, not a low-level bag of unrelated contracts
+
+If you want that naming directly in code, the package now exports `ARC402OperatorClient` as an alias of `ARC402WalletClient`.
+
+## Quick start
+
+```ts
+import { ethers } from "ethers";
+import {
+  AgentRegistryClient,
+  ServiceAgreementClient,
+  CapabilityRegistryClient,
+  ReputationOracleClient,
+  createNegotiationProposal,
+  AgreementStatus,
+  ProviderResponseType,
+  EvidenceType,
+} from "@arc402/sdk";
+
+const provider = new ethers.JsonRpcProvider("https://mainnet.base.org");
+const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+
+const registry = new AgentRegistryClient(process.env.AGENT_REGISTRY!, provider);
+const agreement = new ServiceAgreementClient(process.env.SERVICE_AGREEMENT!, signer);
+const capability = new CapabilityRegistryClient(process.env.CAPABILITY_REGISTRY!, provider);
+const reputation = new ReputationOracleClient(process.env.REPUTATION_ORACLE!, provider);
+
+const agents = await registry.listAgents(20);
+const enrichedAgents = await Promise.all(agents.map(async (agent) => ({
+  ...agent,
+  canonicalCapabilities: await capability.getCapabilities(agent.wallet),
+})));
+const legalAgents = enrichedAgents.filter((agent) =>
+  agent.canonicalCapabilities.includes("legal.patent-analysis.us.v1")
+);
+
+const negotiation = createNegotiationProposal({
+  from: await signer.getAddress(),
+  to: legalAgents[0].wallet,
+  serviceType: "legal.patent-analysis.us.v1",
+  price: ethers.parseEther("0.05").toString(),
+  token: ethers.ZeroAddress,
+  deadline: new Date(Date.now() + 4 * 60 * 60 * 1000).toISOString(),
+  spec: "Analyze novelty risk against prior art set A",
+  specHash: ethers.id("Analyze novelty risk against prior art set A"),
+});
+
+console.log(JSON.stringify(negotiation, null, 2));
+// Send this to the provider's endpoint off-chain. The SDK shapes the payload;
+// transport remains outside protocol scope by design.
+
+const tx = await agreement.propose({
+  provider: legalAgents[0].wallet,
+  serviceType: negotiation.serviceType,
+  description: negotiation.spec,
+  price: BigInt(negotiation.price),
+  token: negotiation.token,
+  deadline: Math.floor(new Date(negotiation.deadline).getTime() / 1000),
+  deliverablesHash: negotiation.specHash,
+});
+
+const info = await agreement.getAgreement(tx.agreementId);
+if (info.status === AgreementStatus.PROPOSED) {
+  console.log("Awaiting provider acceptance");
+}
+
+const roots = await capability.listRoots();
+const providerRep = await reputation.getReputation(legalAgents[0].wallet);
+console.log({ roots, providerRep });
+```
+
+## Delivery, remediation, and disputes
+
+```ts
+import { ethers } from "ethers";
+import {
+  ServiceAgreementClient,
+  ProviderResponseType,
+  EvidenceType,
+} from "@arc402/sdk";
+
+const agreement = new ServiceAgreementClient(process.env.SERVICE_AGREEMENT!, signer);
+const agreementId = 7n;
+
+await agreement.commitDeliverable(agreementId, ethers.id("delivery bundle hash"));
+await agreement.verifyDeliverable(agreementId);
+
+await agreement.requestRevision(
+  agreementId,
+  ethers.id("Need missing appendix and structured citations"),
+  "ipfs://feedback-json",
+);
+
+await agreement.respondToRevision(
+  agreementId,
+  ProviderResponseType.REVISE,
+  ethers.id("Revised package uploaded"),
+  "ipfs://provider-response-json",
+);
+
+await agreement.submitDisputeEvidence(
+  agreementId,
+  EvidenceType.DELIVERABLE,
+  ethers.id("delivery bundle hash"),
+  "ipfs://delivery-bundle",
+);
+
+const remediation = await agreement.getRemediationCase(agreementId);
+const dispute = await agreement.getDisputeCase(agreementId);
+console.log({ remediation, dispute });
+```
+
+## Sponsorship + governance + operational context
+
+```ts
+import {
+  SponsorshipAttestationClient,
+  GovernanceClient,
+  AgentRegistryClient,
+} from "@arc402/sdk";
+
+const sponsorship = new SponsorshipAttestationClient(process.env.SPONSORSHIP_ATTESTATION!, provider);
+const governance = new GovernanceClient(process.env.GOVERNANCE!, provider);
+const registry = new AgentRegistryClient(process.env.AGENT_REGISTRY!, provider);
+
+const highestTier = await sponsorship.getHighestTier("0xAgent");
+const metrics = await registry.getOperationalMetrics("0xAgent");
+const tx0 = await governance.getTransaction(0n);
+
+console.log({ highestTier, metrics, tx0 });
+```
+
+## Notes
+
+- The default settlement flow is propose -> accept -> commitDeliverable -> verifyDeliverable/autoRelease, with remediation required before dispute in normal cases. Direct dispute is reserved for explicit hard-fail cases: no delivery, hard deadline breach, clearly invalid/fraudulent deliverables, or safety-critical violations.
+- `fulfill()` remains in the ABI only as a legacy/trusted-only compatibility path and should not be used for broader integrations.
+- Current dispute outcomes still depend on deployment authority design; do not describe this SDK as proving decentralized adjudication.
+- Negotiation helpers only shape Spec 14 messages. They do **not** send them.
+- Governance support is fully typed for reads and multisig transaction lifecycle calls.
+- Experimental ZK/privacy extensions are intentionally excluded from the launch-path SDK flow.
+- Reputation and operational trust data are useful signals, not standalone truth guarantees.
+- Contract address availability depends on network deployment. Some newer modules may still be undeployed on a given network.
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,29 @@
+import { ContractRunner } from "ethers";
+import { AgentInfo, OperationalMetrics } from "./types";
+export interface AgentRegistrationInput {
+    name: string;
+    capabilities: string[];
+    serviceType: string;
+    endpoint: string;
+    metadataURI?: string;
+}
+export declare class AgentRegistryClient {
+    private contract;
+    constructor(address: string, runner: ContractRunner);
+    register(input: AgentRegistrationInput): Promise<any>;
+    update(input: AgentRegistrationInput): Promise<any>;
+    deactivate(): Promise<any>;
+    reactivate(): Promise<any>;
+    submitHeartbeat(latencyMs: number): Promise<any>;
+    setHeartbeatPolicy(intervalSeconds: number, gracePeriodSeconds: number): Promise<any>;
+    getAgent(wallet: string): Promise<AgentInfo>;
+    getOperationalMetrics(wallet: string): Promise<OperationalMetrics>;
+    listAgents(limit?: number): Promise<AgentInfo[]>;
+    findByCapability(capability: string, limit?: number): Promise<AgentInfo[]>;
+    searchByCapability(capability: string): Promise<AgentInfo[]>;
+    searchByServiceType(serviceType: string): Promise<AgentInfo[]>;
+    searchByName(query: string): Promise<AgentInfo[]>;
+    getTopByTrust(limit?: number): Promise<AgentInfo[]>;
+    getActive(limit?: number): Promise<AgentInfo[]>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAGxC,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc;IAI7C,QAAQ,CAAC,KAAK,EAAE,sBAAsB;IAKtC,MAAM,CAAC,KAAK,EAAE,sBAAsB;IAKpC,UAAU;IACV,UAAU;IACV,eAAe,CAAC,SAAS,EAAE,MAAM;IACjC,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM;IAKtE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAiB5C,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAclE,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAOhD,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAK1E,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAO5D,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQ9D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQjD,aAAa,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAY/C,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAKtD"}

package/dist/agent.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRegistryClient = void 0;
+const contracts_1 = require("./contracts");
+const ethers_1 = require("ethers");
+class AgentRegistryClient {
+    constructor(address, runner) {
+        this.contract = new ethers_1.ethers.Contract(address, contracts_1.AGENT_REGISTRY_ABI, runner);
+    }
+    async register(input) {
+        const tx = await this.contract.register(input.name, input.capabilities, input.serviceType, input.endpoint, input.metadataURI ?? "");
+        return tx.wait();
+    }
+    async update(input) {
+        const tx = await this.contract.update(input.name, input.capabilities, input.serviceType, input.endpoint, input.metadataURI ?? "");
+        return tx.wait();
+    }
+    async deactivate() { const tx = await this.contract.deactivate(); return tx.wait(); }
+    async reactivate() { const tx = await this.contract.reactivate(); return tx.wait(); }
+    async submitHeartbeat(latencyMs) { const tx = await this.contract.submitHeartbeat(latencyMs); return tx.wait(); }
+    async setHeartbeatPolicy(intervalSeconds, gracePeriodSeconds) {
+        const tx = await this.contract.setHeartbeatPolicy(intervalSeconds, gracePeriodSeconds);
+        return tx.wait();
+    }
+    async getAgent(wallet) {
+        const [raw, trustScore] = await Promise.all([this.contract.getAgent(wallet), this.contract.getTrustScore(wallet)]);
+        return {
+            wallet: raw.wallet,
+            name: raw.name,
+            capabilities: [...raw.capabilities],
+            serviceType: raw.serviceType,
+            endpoint: raw.endpoint,
+            metadataURI: raw.metadataURI,
+            active: raw.active,
+            registeredAt: BigInt(raw.registeredAt),
+            endpointChangedAt: BigInt(raw.endpointChangedAt),
+            endpointChangeCount: BigInt(raw.endpointChangeCount),
+            trustScore: BigInt(trustScore),
+        };
+    }
+    async getOperationalMetrics(wallet) {
+        const raw = await this.contract.getOperationalMetrics(wallet);
+        return {
+            heartbeatInterval: BigInt(raw.heartbeatInterval),
+            heartbeatGracePeriod: BigInt(raw.heartbeatGracePeriod),
+            lastHeartbeatAt: BigInt(raw.lastHeartbeatAt),
+            rollingLatency: BigInt(raw.rollingLatency),
+            heartbeatCount: BigInt(raw.heartbeatCount),
+            missedHeartbeatCount: BigInt(raw.missedHeartbeatCount),
+            uptimeScore: BigInt(raw.uptimeScore),
+            responseScore: BigInt(raw.responseScore),
+        };
+    }
+    async listAgents(limit) {
+        const count = Number(await this.contract.agentCount());
+        const end = limit ? Math.min(limit, count) : count;
+        const addresses = await Promise.all(Array.from({ length: end }, (_, i) => this.contract.getAgentAtIndex(i)));
+        return Promise.all(addresses.map((address) => this.getAgent(address)));
+    }
+    async findByCapability(capability, limit) {
+        const agents = await this.listAgents(limit);
+        return agents.filter((agent) => agent.capabilities.includes(capability));
+    }
+    async searchByCapability(capability) {
+        const agents = await this.listAgents();
+        return agents.filter((agent) => agent.active && agent.capabilities.some((c) => c === capability || c.startsWith(capability + ".")));
+    }
+    async searchByServiceType(serviceType) {
+        const agents = await this.listAgents();
+        const query = serviceType.toLowerCase();
+        return agents.filter((agent) => agent.active && agent.serviceType.toLowerCase().includes(query));
+    }
+    async searchByName(query) {
+        const agents = await this.listAgents();
+        const lower = query.toLowerCase();
+        return agents.filter((agent) => agent.active && agent.name.toLowerCase().includes(lower));
+    }
+    async getTopByTrust(limit = 20) {
+        const agents = await this.listAgents();
+        return agents
+            .filter((agent) => agent.active)
+            .sort((a, b) => {
+            const aScore = BigInt(a.trustScore ?? 0n);
+            const bScore = BigInt(b.trustScore ?? 0n);
+            return bScore > aScore ? 1 : bScore < aScore ? -1 : 0;
+        })
+            .slice(0, limit);
+    }
+    async getActive(limit) {
+        const agents = await this.listAgents();
+        const active = agents.filter((agent) => agent.active);
+        return limit ? active.slice(0, limit) : active;
+    }
+}
+exports.AgentRegistryClient = AgentRegistryClient;

package/dist/agreement.d.ts

@@ -0,0 +1,57 @@
+import { ContractRunner, ethers } from "ethers";
+import { Agreement, ArbitrationCase, ArbitrationVote, DisputeCase, DisputeClass, DisputeEvidence, DisputeMode, DisputeOutcome, DirectDisputeReason, EvidenceType, ProposeParams, ProviderResponseType, RemediationCase, RemediationFeedback, RemediationResponse } from "./types";
+export declare class ServiceAgreementClient {
+    private contract;
+    constructor(address: string, runner: ContractRunner);
+    propose(params: ProposeParams): Promise<{
+        agreementId: bigint;
+        receipt: ethers.TransactionReceipt;
+    }>;
+    accept(id: bigint): Promise<any>;
+    /** @deprecated Legacy/trusted-only immediate release path. Prefer commitDeliverable() + verifyDeliverable()/autoRelease(). */
+    fulfill(id: bigint, hash: string): Promise<any>;
+    fulfillLegacyTrustedOnly(id: bigint, hash: string): Promise<any>;
+    commitDeliverable(id: bigint, hash: string): Promise<any>;
+    verifyDeliverable(id: bigint): Promise<any>;
+    autoRelease(id: bigint): Promise<any>;
+    dispute(id: bigint, reason: string, feeEth?: bigint): Promise<any>;
+    directDispute(id: bigint, directReason: DirectDisputeReason, reason: string, feeEth?: bigint): Promise<any>;
+    escalateToDispute(id: bigint, reason: string, feeEth?: bigint): Promise<any>;
+    /** Open a dispute with explicit mode and class. For ETH agreements, pass fee as feeEth. */
+    openDisputeWithMode(id: bigint, mode: DisputeMode, disputeClass: DisputeClass, reason: string, feeEth?: bigint): Promise<ethers.TransactionReceipt>;
+    /** Shorthand: UNILATERAL dispute with specified class. */
+    openUnilateralDispute(id: bigint, disputeClass: DisputeClass, reason: string, feeEth?: bigint): Promise<ethers.TransactionReceipt>;
+    /** Shorthand: MUTUAL dispute — opener pays half. Respondent calls DisputeArbitrationClient.joinMutualDispute(). */
+    openMutualDispute(id: bigint, disputeClass: DisputeClass, reason: string, halfFeeEth?: bigint): Promise<ethers.TransactionReceipt>;
+    canDirectDispute(id: bigint, directReason: DirectDisputeReason): Promise<boolean>;
+    cancel(id: bigint): Promise<any>;
+    expiredCancel(id: bigint): Promise<any>;
+    resolveDisputeDetailed(id: bigint, outcome: DisputeOutcome, providerAward: bigint, clientAward: bigint): Promise<any>;
+    /** Owner-only: resolve a dispute directly in favor of provider or client. Requires DISPUTED or ESCALATED_TO_HUMAN status. */
+    ownerResolveDispute(agreementId: bigint, favorProvider: boolean): Promise<ethers.TransactionReceipt>;
+    /**
+     * Called by the DisputeArbitration contract to resolve a dispute with split amounts.
+     * @param agreementId Agreement to resolve
+     * @param recipient  Address of the winning party
+     * @param providerAmount Provider payout in token units
+     * @param clientAmount   Client refund in token units
+     */
+    resolveFromArbitration(agreementId: bigint, recipient: string, providerAmount: bigint, clientAmount: bigint): Promise<ethers.TransactionReceipt>;
+    requestRevision(agreementId: bigint, feedbackHash: string, feedbackURI?: string, previousTranscriptHash?: string): Promise<any>;
+    respondToRevision(agreementId: bigint, responseType: ProviderResponseType, responseHash: string, responseURI?: string, previousTranscriptHash?: string, proposedProviderPayout?: bigint): Promise<any>;
+    submitDisputeEvidence(agreementId: bigint, evidenceType: EvidenceType, evidenceHash: string, evidenceURI?: string): Promise<any>;
+    nominateArbitrator(agreementId: bigint, arbitrator: string): Promise<any>;
+    castArbitrationVote(agreementId: bigint, vote: ArbitrationVote, providerAward: bigint, clientAward: bigint): Promise<any>;
+    requestHumanEscalation(agreementId: bigint, reason: string): Promise<any>;
+    getAgreement(id: bigint): Promise<Agreement>;
+    getRemediationCase(id: bigint): Promise<RemediationCase>;
+    getRemediationFeedback(id: bigint, index: bigint): Promise<RemediationFeedback>;
+    getRemediationResponse(id: bigint, index: bigint): Promise<RemediationResponse>;
+    getDisputeCase(id: bigint): Promise<DisputeCase>;
+    getDisputeEvidence(id: bigint, index: bigint): Promise<DisputeEvidence>;
+    getArbitrationCase(id: bigint): Promise<ArbitrationCase>;
+    getDisputeEvidenceAll(id: bigint): Promise<DisputeEvidence[]>;
+    getClientAgreements(client: string): Promise<Agreement[]>;
+    getProviderAgreements(provider: string): Promise<Agreement[]>;
+}
+//# sourceMappingURL=agreement.d.ts.map

package/dist/agreement.d.ts.map

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

package/dist/agreement.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceAgreementClient = void 0;
+const ethers_1 = require("ethers");
+const contracts_1 = require("./contracts");
+const types_1 = require("./types");
+class ServiceAgreementClient {
+    constructor(address, runner) {
+        this.contract = new ethers_1.ethers.Contract(address, contracts_1.SERVICE_AGREEMENT_ABI, runner);
+    }
+    async propose(params) {
+        const isEth = params.token === ethers_1.ethers.ZeroAddress;
+        const tx = await this.contract.propose(params.provider, params.serviceType, params.description, params.price, params.token, params.deadline, params.deliverablesHash, { value: isEth ? params.price : 0n });
+        const receipt = await tx.wait();
+        const iface = new ethers_1.ethers.Interface(contracts_1.SERVICE_AGREEMENT_ABI);
+        for (const log of receipt.logs) {
+            try {
+                const parsed = iface.parseLog(log);
+                if (parsed?.name === "AgreementProposed")
+                    return { agreementId: BigInt(parsed.args.id), receipt };
+            }
+            catch { }
+        }
+        throw new Error("Could not parse AgreementProposed event");
+    }
+    async accept(id) { const tx = await this.contract.accept(id); return tx.wait(); }
+    /** @deprecated Legacy/trusted-only immediate release path. Prefer commitDeliverable() + verifyDeliverable()/autoRelease(). */
+    async fulfill(id, hash) { const tx = await this.contract.fulfill(id, hash); return tx.wait(); }
+    async fulfillLegacyTrustedOnly(id, hash) { return this.fulfill(id, hash); }
+    async commitDeliverable(id, hash) { const tx = await this.contract.commitDeliverable(id, hash); return tx.wait(); }
+    async verifyDeliverable(id) { const tx = await this.contract.verifyDeliverable(id); return tx.wait(); }
+    async autoRelease(id) { const tx = await this.contract.autoRelease(id); return tx.wait(); }
+    async dispute(id, reason, feeEth = 0n) { const tx = await this.contract.dispute(id, reason, { value: feeEth }); return tx.wait(); }
+    async directDispute(id, directReason, reason, feeEth = 0n) { const tx = await this.contract.directDispute(id, directReason, reason, { value: feeEth }); return tx.wait(); }
+    async escalateToDispute(id, reason, feeEth = 0n) { const tx = await this.contract.escalateToDispute(id, reason, { value: feeEth }); return tx.wait(); }
+    /** Open a dispute with explicit mode and class. For ETH agreements, pass fee as feeEth. */
+    async openDisputeWithMode(id, mode, disputeClass, reason, feeEth = 0n) {
+        const tx = await this.contract.openDisputeWithMode(id, mode, disputeClass, reason, { value: feeEth });
+        return tx.wait();
+    }
+    /** Shorthand: UNILATERAL dispute with specified class. */
+    async openUnilateralDispute(id, disputeClass, reason, feeEth = 0n) {
+        return this.openDisputeWithMode(id, types_1.DisputeMode.UNILATERAL, disputeClass, reason, feeEth);
+    }
+    /** Shorthand: MUTUAL dispute — opener pays half. Respondent calls DisputeArbitrationClient.joinMutualDispute(). */
+    async openMutualDispute(id, disputeClass, reason, halfFeeEth = 0n) {
+        return this.openDisputeWithMode(id, types_1.DisputeMode.MUTUAL, disputeClass, reason, halfFeeEth);
+    }
+    async canDirectDispute(id, directReason) { return this.contract.canDirectDispute(id, directReason); }
+    async cancel(id) { const tx = await this.contract.cancel(id); return tx.wait(); }
+    async expiredCancel(id) { const tx = await this.contract.expiredCancel(id); return tx.wait(); }
+    async resolveDisputeDetailed(id, outcome, providerAward, clientAward) {
+        const tx = await this.contract.resolveDisputeDetailed(id, outcome, providerAward, clientAward);
+        return tx.wait();
+    }
+    /** Owner-only: resolve a dispute directly in favor of provider or client. Requires DISPUTED or ESCALATED_TO_HUMAN status. */
+    async ownerResolveDispute(agreementId, favorProvider) {
+        const tx = await this.contract.ownerResolveDispute(agreementId, favorProvider);
+        return tx.wait();
+    }
+    /**
+     * Called by the DisputeArbitration contract to resolve a dispute with split amounts.
+     * @param agreementId Agreement to resolve
+     * @param recipient  Address of the winning party
+     * @param providerAmount Provider payout in token units
+     * @param clientAmount   Client refund in token units
+     */
+    async resolveFromArbitration(agreementId, recipient, providerAmount, clientAmount) {
+        const tx = await this.contract.resolveFromArbitration(agreementId, recipient, providerAmount, clientAmount);
+        return tx.wait();
+    }
+    async requestRevision(agreementId, feedbackHash, feedbackURI = "", previousTranscriptHash = ethers_1.ethers.ZeroHash) {
+        const tx = await this.contract.requestRevision(agreementId, feedbackHash, feedbackURI, previousTranscriptHash);
+        return tx.wait();
+    }
+    async respondToRevision(agreementId, responseType, responseHash, responseURI = "", previousTranscriptHash = ethers_1.ethers.ZeroHash, proposedProviderPayout = 0n) {
+        const tx = await this.contract.respondToRevision(agreementId, responseType, proposedProviderPayout, responseHash, responseURI, previousTranscriptHash);
+        return tx.wait();
+    }
+    async submitDisputeEvidence(agreementId, evidenceType, evidenceHash, evidenceURI = "") {
+        const tx = await this.contract.submitDisputeEvidence(agreementId, evidenceType, evidenceHash, evidenceURI);
+        return tx.wait();
+    }
+    async nominateArbitrator(agreementId, arbitrator) {
+        const tx = await this.contract.nominateArbitrator(agreementId, arbitrator);
+        return tx.wait();
+    }
+    async castArbitrationVote(agreementId, vote, providerAward, clientAward) {
+        const tx = await this.contract.castArbitrationVote(agreementId, vote, providerAward, clientAward);
+        return tx.wait();
+    }
+    async requestHumanEscalation(agreementId, reason) {
+        const tx = await this.contract.requestHumanEscalation(agreementId, reason);
+        return tx.wait();
+    }
+    async getAgreement(id) {
+        const raw = await this.contract.getAgreement(id);
+        return {
+            id: BigInt(raw.id), client: raw.client, provider: raw.provider, serviceType: raw.serviceType,
+            description: raw.description, price: BigInt(raw.price), token: raw.token, deadline: BigInt(raw.deadline),
+            deliverablesHash: raw.deliverablesHash, status: Number(raw.status),
+            createdAt: BigInt(raw.createdAt), resolvedAt: BigInt(raw.resolvedAt), verifyWindowEnd: BigInt(raw.verifyWindowEnd), committedHash: raw.committedHash,
+        };
+    }
+    async getRemediationCase(id) {
+        const raw = await this.contract.getRemediationCase(id);
+        return { cycleCount: Number(raw.cycleCount), openedAt: BigInt(raw.openedAt), deadlineAt: BigInt(raw.deadlineAt), lastActionAt: BigInt(raw.lastActionAt), latestTranscriptHash: raw.latestTranscriptHash, active: raw.active };
+    }
+    async getRemediationFeedback(id, index) {
+        const raw = await this.contract.getRemediationFeedback(id, index);
+        return { cycle: Number(raw.cycle), author: raw.author, feedbackHash: raw.feedbackHash, feedbackURI: raw.feedbackURI, previousTranscriptHash: raw.previousTranscriptHash, transcriptHash: raw.transcriptHash, timestamp: BigInt(raw.timestamp) };
+    }
+    async getRemediationResponse(id, index) {
+        const raw = await this.contract.getRemediationResponse(id, index);
+        return { cycle: Number(raw.cycle), author: raw.author, responseType: Number(raw.responseType), proposedProviderPayout: BigInt(raw.proposedProviderPayout), responseHash: raw.responseHash, responseURI: raw.responseURI, previousTranscriptHash: raw.previousTranscriptHash, transcriptHash: raw.transcriptHash, timestamp: BigInt(raw.timestamp) };
+    }
+    async getDisputeCase(id) {
+        const raw = await this.contract.getDisputeCase(id);
+        return { agreementId: BigInt(raw.agreementId), openedAt: BigInt(raw.openedAt), responseDeadlineAt: BigInt(raw.responseDeadlineAt), outcome: Number(raw.outcome), providerAward: BigInt(raw.providerAward), clientAward: BigInt(raw.clientAward), humanReviewRequested: raw.humanReviewRequested, evidenceCount: BigInt(raw.evidenceCount) };
+    }
+    async getDisputeEvidence(id, index) {
+        const raw = await this.contract.getDisputeEvidence(id, index);
+        return { submitter: raw.submitter, evidenceType: Number(raw.evidenceType), evidenceHash: raw.evidenceHash, evidenceURI: raw.evidenceURI, timestamp: BigInt(raw.timestamp) };
+    }
+    async getArbitrationCase(id) {
+        const raw = await this.contract.getArbitrationCase(id);
+        return {
+            agreementId: BigInt(raw.agreementId),
+            arbitrators: [...raw.arbitrators],
+            arbitratorCount: Number(raw.arbitratorCount),
+            providerVotes: Number(raw.providerVotes),
+            clientVotes: Number(raw.clientVotes),
+            splitVotes: Number(raw.splitVotes),
+            humanVotes: Number(raw.humanVotes),
+            selectionDeadlineAt: BigInt(raw.selectionDeadlineAt),
+            decisionDeadlineAt: BigInt(raw.decisionDeadlineAt),
+            splitProviderAward: BigInt(raw.splitProviderAward),
+            splitClientAward: BigInt(raw.splitClientAward),
+            finalized: raw.finalized,
+            humanBackstopUsed: raw.humanBackstopUsed,
+        };
+    }
+    async getDisputeEvidenceAll(id) {
+        const dispute = await this.getDisputeCase(id);
+        return Promise.all(Array.from({ length: Number(dispute.evidenceCount) }, (_, i) => this.getDisputeEvidence(id, BigInt(i))));
+    }
+    async getClientAgreements(client) {
+        const ids = await this.contract.getAgreementsByClient(client);
+        return Promise.all(ids.map((id) => this.getAgreement(BigInt(id))));
+    }
+    async getProviderAgreements(provider) {
+        const ids = await this.contract.getAgreementsByProvider(provider);
+        return Promise.all(ids.map((id) => this.getAgreement(BigInt(id))));
+    }
+}
+exports.ServiceAgreementClient = ServiceAgreementClient;

package/dist/capability.d.ts

@@ -0,0 +1,17 @@
+import { ContractRunner } from "ethers";
+import { CapabilityRoot } from "./types";
+export declare class CapabilityRegistryClient {
+    private contract;
+    constructor(address: string, runner: ContractRunner);
+    registerRoot(root: string): Promise<any>;
+    setRootStatus(root: string, active: boolean): Promise<any>;
+    claim(capability: string): Promise<any>;
+    revoke(capability: string): Promise<any>;
+    isRootActive(root: string): Promise<any>;
+    getRoot(root: string): Promise<CapabilityRoot>;
+    listRoots(): Promise<CapabilityRoot[]>;
+    getCapabilities(agent: string): Promise<string[]>;
+    capabilityCount(agent: string): Promise<bigint>;
+    isCapabilityClaimed(agent: string, capability: string): Promise<any>;
+}
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAU,MAAM,QAAQ,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAkB;gBACtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc;IAC7C,YAAY,CAAC,IAAI,EAAE,MAAM;IACzB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAC3C,KAAK,CAAC,UAAU,EAAE,MAAM;IACxB,MAAM,CAAC,UAAU,EAAE,MAAM;IAC/B,YAAY,CAAC,IAAI,EAAE,MAAM;IACnB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAC9C,SAAS,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAC5C,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IACjD,eAAe,CAAC,KAAK,EAAE,MAAM;IAC7B,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CACtD"}

package/dist/capability.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapabilityRegistryClient = void 0;
+const ethers_1 = require("ethers");
+const contracts_1 = require("./contracts");
+class CapabilityRegistryClient {
+    constructor(address, runner) { this.contract = new ethers_1.ethers.Contract(address, contracts_1.CAPABILITY_REGISTRY_ABI, runner); }
+    async registerRoot(root) { const tx = await this.contract.registerRoot(root); return tx.wait(); }
+    async setRootStatus(root, active) { const tx = await this.contract.setRootStatus(root, active); return tx.wait(); }
+    async claim(capability) { const tx = await this.contract.claim(capability); return tx.wait(); }
+    async revoke(capability) { const tx = await this.contract.revoke(capability); return tx.wait(); }
+    isRootActive(root) { return this.contract.isRootActive(root); }
+    async getRoot(root) { const raw = await this.contract.getRoot(root); return { root: raw.root, rootId: raw.rootId, active: raw.active }; }
+    async listRoots() { const count = Number(await this.contract.rootCount()); return Promise.all(Array.from({ length: count }, async (_, i) => { const raw = await this.contract.getRootAt(i); return { root: raw.root, rootId: raw.rootId, active: raw.active }; })); }
+    getCapabilities(agent) { return this.contract.getCapabilities(agent); }
+    capabilityCount(agent) { return this.contract.capabilityCount(agent).then(BigInt); }
+    isCapabilityClaimed(agent, capability) { return this.contract.isCapabilityClaimed(agent, capability); }
+}
+exports.CapabilityRegistryClient = CapabilityRegistryClient;

package/dist/channel.d.ts

@@ -0,0 +1,39 @@
+import { ContractRunner } from "ethers";
+import { Channel, ChannelState } from "./types";
+export declare class ChannelClient {
+    private contract;
+    private signer;
+    constructor(address: string, runner: ContractRunner);
+    openSessionChannel(provider: string, token: string, maxAmount: bigint, ratePerCall: bigint, deadline: number): Promise<{
+        channelId: string;
+        txHash: string;
+    }>;
+    /**
+     * Compute the EIP-712 domain separator for a deployed SessionChannels contract.
+     * Must match SessionChannels._domainSeparator() on-chain.
+     */
+    static domainSeparator(chainId: bigint, contractAddress: string): string;
+    /**
+     * Compute the EIP-712 typed-data digest for a ChannelState.
+     * Must match SessionChannels._verifyChannelStateSigs() digest on-chain.
+     */
+    static channelStateDigest(state: Omit<ChannelState, "clientSig" | "providerSig">, chainId: bigint, contractAddress: string): Uint8Array;
+    signStateUpdate(channelId: string, sequenceNumber: number, callCount: number, cumulativePayment: bigint, token: string, chainId: bigint, contractAddress: string): Promise<ChannelState>;
+    verifyStateUpdate(state: ChannelState, channel: Channel, chainId: bigint, contractAddress: string): Promise<boolean>;
+    encodeChannelState(state: ChannelState): string;
+    closeChannel(channelId: string, finalState: ChannelState): Promise<{
+        txHash: string;
+    }>;
+    challengeChannel(channelId: string, latestState: ChannelState): Promise<{
+        txHash: string;
+    }>;
+    finaliseChallenge(channelId: string): Promise<{
+        txHash: string;
+    }>;
+    reclaimExpiredChannel(channelId: string): Promise<{
+        txHash: string;
+    }>;
+    getChannelStatus(channelId: string): Promise<Channel>;
+    getOpenChannels(wallet: string): Promise<Channel[]>;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,cAAc,EAAU,MAAM,QAAQ,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAiB,MAAM,SAAS,CAAC;AAe/D,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,MAAM,CAAuB;gBAEzB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc;IAK7C,kBAAkB,CACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBjD;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM;IAUxE;;;OAGG;IACH,MAAM,CAAC,kBAAkB,CACvB,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,aAAa,CAAC,EACtD,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,GACtB,UAAU;IAcP,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,EACzB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,YAAY,CAAC;IAalB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyB1H,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM;IAgBzC,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAOtF,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAO3F,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAMjE,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAMrE,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBrD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAS1D"}