@arc402/sdk 0.2.0

package/src/watchtower.ts

@@ -0,0 +1,124 @@
+import { AbstractSigner, ContractRunner, ethers } from "ethers";
+import type { ChannelState } from "./types";
+import { ChannelClient } from "./channel";
+
+const WATCHTOWER_REGISTRY_ABI = [
+  "function register(string name, string description, string[] capabilities) external",
+  "function getWatchtower(address watchtower) external view returns (tuple(address addr, string name, string description, string[] capabilities, bool active, uint256 registeredAt))",
+  "function isRegistered(address watchtower) external view returns (bool)",
+  "event WatchtowerRegistered(address indexed watchtower, string name)",
+] as const;
+
+const SESSION_CHANNEL_WATCHTOWER_ABI = [
+  "function authorizeWatchtower(bytes32 channelId, address watchtower) external",
+  "function revokeWatchtower(bytes32 channelId, address watchtower) external",
+  "function submitWatchtowerChallenge(bytes32 channelId, bytes latestState, address beneficiary) external",
+  "function isWatchtowerAuthorized(bytes32 channelId, address watchtower) external view returns (bool)",
+] as const;
+
+export interface WatchtowerMetadata {
+  name: string;
+  description: string;
+  capabilities: string[];
+}
+
+export interface WatchtowerStatus {
+  addr: string;
+  name: string;
+  description: string;
+  capabilities: string[];
+  active: boolean;
+  registeredAt: number;
+}
+
+export class WatchtowerClient {
+  private registry: ethers.Contract;
+  private channelContract: ethers.Contract;
+  private signer: ethers.Signer | null;
+  private _channelClient: ChannelClient;
+
+  constructor(
+    registryAddress: string,
+    channelContractAddress: string,
+    runner: ContractRunner
+  ) {
+    this.registry = new ethers.Contract(registryAddress, WATCHTOWER_REGISTRY_ABI, runner);
+    this.channelContract = new ethers.Contract(channelContractAddress, SESSION_CHANNEL_WATCHTOWER_ABI, runner);
+    this.signer = runner instanceof AbstractSigner ? (runner as ethers.Signer) : null;
+    this._channelClient = new ChannelClient(channelContractAddress, runner);
+  }
+
+  /**
+   * Register this node as a watchtower in the WatchtowerRegistry.
+   */
+  async registerWatchtower(metadata: WatchtowerMetadata): Promise<{ txHash: string }> {
+    if (!this.signer) throw new Error("Signer required");
+    const tx = await this.registry.register(metadata.name, metadata.description, metadata.capabilities);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash };
+  }
+
+  /**
+   * Submit a watchtower challenge on behalf of `beneficiary`.
+   * The `state` must be a doubly-signed ChannelState with a higher sequenceNumber
+   * than the one currently recorded on-chain.
+   */
+  async submitChallenge(
+    channelId: string,
+    state: ChannelState,
+    beneficiary: string
+  ): Promise<{ txHash: string }> {
+    if (!this.signer) throw new Error("Signer required");
+    const encoded = this._channelClient.encodeChannelState(state);
+    const tx = await this.channelContract.submitWatchtowerChallenge(channelId, encoded, beneficiary);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash };
+  }
+
+  /**
+   * Get the on-chain registration status of a watchtower address.
+   */
+  async getWatchtowerStatus(watchtowerAddress: string): Promise<WatchtowerStatus> {
+    const raw = await this.registry.getWatchtower(watchtowerAddress);
+    return {
+      addr: raw.addr,
+      name: raw.name,
+      description: raw.description,
+      capabilities: [...raw.capabilities],
+      active: raw.active,
+      registeredAt: Number(raw.registeredAt),
+    };
+  }
+
+  /**
+   * Authorize a watchtower to challenge on your behalf for a specific channel.
+   */
+  async authorizeWatchtower(channelId: string, watchtower: string): Promise<{ txHash: string }> {
+    if (!this.signer) throw new Error("Signer required");
+    const tx = await this.channelContract.authorizeWatchtower(channelId, watchtower);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash };
+  }
+
+  /**
+   * Revoke a watchtower's authorization for a channel.
+   */
+  async revokeWatchtower(channelId: string, watchtower: string): Promise<{ txHash: string }> {
+    if (!this.signer) throw new Error("Signer required");
+    const tx = await this.channelContract.revokeWatchtower(channelId, watchtower);
+    const receipt = await tx.wait();
+    return { txHash: receipt.hash };
+  }
+
+  /**
+   * Check whether a watchtower is authorized for a channel.
+   */
+  async isWatchtowerAuthorized(channelId: string, watchtower: string): Promise<boolean> {
+    return this.channelContract.isWatchtowerAuthorized(channelId, watchtower);
+  }
+
+  /** Expose ChannelClient for polling in watch loops. */
+  get channelClient(): ChannelClient {
+    return this._channelClient;
+  }
+}

package/test/negotiation-signing.test.js

@@ -0,0 +1,157 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { ethers } = require('ethers');
+const {
+  signNegotiationMessage,
+  createSignedProposal,
+  parseNegotiationMessage,
+} = require('../dist');
+const { NegotiationGuard } = require('../dist');
+
+// Minimal mock ContractRunner + Registry that always returns isRegistered=true
+function makeRunner(isRegistered = true) {
+  // NegotiationGuard calls this.registry.isRegistered(addr)
+  // We stub it by creating a fake contract
+  return { isRegistered };
+}
+
+function makeMockGuard(isRegistered = true, opts = {}) {
+  const guard = new NegotiationGuard({
+    agentRegistryAddress: '0x0000000000000000000000000000000000000001',
+    runner: {},
+    ...opts,
+  });
+  // Replace registry with a mock
+  guard['registry'] = {
+    isRegistered: async () => isRegistered,
+  };
+  return guard;
+}
+
+const WALLET = ethers.Wallet.createRandom();
+
+const BASE_INPUT = {
+  from: WALLET.address,
+  to: '0x0000000000000000000000000000000000000002',
+  serviceType: 'legal.patent-analysis.us.v1',
+  price: '50000000000000000',
+  token: '0x0000000000000000000000000000000000000000',
+  deadline: '2026-03-11T22:00:00Z',
+  spec: 'Analyze patent US11234567',
+  specHash: '0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1',
+};
+
+test('sign and verify a PROPOSE message passes NegotiationGuard', async () => {
+  const proposal = await createSignedProposal(BASE_INPUT, WALLET);
+  assert.equal(proposal.type, 'PROPOSE');
+  assert.ok(proposal.sig.startsWith('0x'));
+  assert.ok(proposal.timestamp > 0);
+  assert.ok(proposal.expiresAt > proposal.timestamp);
+
+  const guard = makeMockGuard(true);
+  const result = await guard.verify(JSON.stringify(proposal));
+  assert.equal(result.valid, true, `expected valid but got error: ${result.error}`);
+  assert.equal(result.recoveredSigner.toLowerCase(), WALLET.address.toLowerCase());
+});
+
+test('stale timestamp fails with TIMESTAMP_TOO_OLD', async () => {
+  const proposal = await createSignedProposal(BASE_INPUT, WALLET);
+  // Backdate timestamp by 120 seconds (beyond 60s tolerance)
+  const stale = { ...proposal, timestamp: proposal.timestamp - 120 };
+  // Re-sign with the altered timestamp so signature is valid but timestamp is old
+  const { ethers: _ethers } = require('ethers');
+  // We just inject a stale timestamp without re-signing — sig will be invalid
+  // but timestamp check fires first
+  const guard = makeMockGuard(true);
+  const result = await guard.verify(JSON.stringify(stale));
+  assert.equal(result.valid, false);
+  assert.equal(result.error, 'TIMESTAMP_TOO_OLD');
+});
+
+test('future timestamp fails with TIMESTAMP_IN_FUTURE', async () => {
+  const proposal = await createSignedProposal(BASE_INPUT, WALLET);
+  const future = { ...proposal, timestamp: proposal.timestamp + 120 };
+  const guard = makeMockGuard(true);
+  const result = await guard.verify(JSON.stringify(future));
+  assert.equal(result.valid, false);
+  assert.equal(result.error, 'TIMESTAMP_IN_FUTURE');
+});
+
+test('wrong signer (from mismatch) fails with INVALID_SIGNATURE', async () => {
+  const proposal = await createSignedProposal(BASE_INPUT, WALLET);
+  // Swap from to a different address
+  const tampered = {
+    ...proposal,
+    from: '0x0000000000000000000000000000000000000099',
+  };
+  const guard = makeMockGuard(true);
+  const result = await guard.verify(JSON.stringify(tampered));
+  assert.equal(result.valid, false);
+  assert.equal(result.error, 'INVALID_SIGNATURE');
+});
+
+test('replayed nonce fails with NONCE_REPLAYED', async () => {
+  const proposal = await createSignedProposal(BASE_INPUT, WALLET);
+  const guard = makeMockGuard(true);
+  const first = await guard.verify(JSON.stringify(proposal));
+  assert.equal(first.valid, true);
+  const second = await guard.verify(JSON.stringify(proposal));
+  assert.equal(second.valid, false);
+  assert.equal(second.error, 'NONCE_REPLAYED');
+});
+
+test('oversized message fails with MESSAGE_TOO_LARGE', async () => {
+  const bigSpec = 'x'.repeat(64 * 1024 + 1);
+  const guard = makeMockGuard(true);
+  const result = await guard.verify(JSON.stringify({ spec: bigSpec }));
+  assert.equal(result.valid, false);
+  assert.equal(result.error, 'MESSAGE_TOO_LARGE');
+});
+
+test('parseNegotiationMessage throws on oversized message', () => {
+  const big = JSON.stringify({ type: 'PROPOSE', data: 'x'.repeat(64 * 1024 + 1) });
+  assert.throws(() => parseNegotiationMessage(big), /64KB/);
+});
+
+test('expired PROPOSE fails with MESSAGE_EXPIRED', async () => {
+  const now = Math.floor(Date.now() / 1000);
+  // Build a message with expiresAt in the past, but valid timestamp
+  const unsigned = {
+    type: 'PROPOSE',
+    from: WALLET.address,
+    to: BASE_INPUT.to,
+    serviceType: BASE_INPUT.serviceType,
+    price: BASE_INPUT.price,
+    token: BASE_INPUT.token,
+    deadline: BASE_INPUT.deadline,
+    spec: BASE_INPUT.spec,
+    specHash: BASE_INPUT.specHash,
+    nonce: ethers.hexlify(ethers.randomBytes(16)),
+    timestamp: now,
+    expiresAt: now - 10, // already expired
+  };
+  const proposal = await signNegotiationMessage(unsigned, WALLET);
+  const guard = makeMockGuard(true);
+  const result = await guard.verify(JSON.stringify(proposal));
+  assert.equal(result.valid, false);
+  assert.equal(result.error, 'MESSAGE_EXPIRED');
+});
+
+test('unregistered signer fails with SIGNER_NOT_REGISTERED', async () => {
+  const proposal = await createSignedProposal(BASE_INPUT, WALLET);
+  const guard = makeMockGuard(false); // registry returns false
+  const result = await guard.verify(JSON.stringify(proposal));
+  assert.equal(result.valid, false);
+  assert.equal(result.error, 'SIGNER_NOT_REGISTERED');
+});
+
+test('registry downtime fails open (signature-only verification passes)', async () => {
+  const proposal = await createSignedProposal(BASE_INPUT, WALLET);
+  const guard = makeMockGuard(true);
+  // Override registry to throw
+  guard['registry'] = { isRegistered: async () => { throw new Error('network error'); } };
+  const result = await guard.verify(JSON.stringify(proposal));
+  // Should pass with signature-only verification
+  assert.equal(result.valid, true);
+  assert.equal(result.recoveredSigner.toLowerCase(), WALLET.address.toLowerCase());
+});

package/test/sdk.test.js

@@ -0,0 +1,19 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createNegotiationProposal, createNegotiationAccept, AgreementStatus, ProviderResponseType, DisputeOutcome, EvidenceType, ArbitrationVote } = require('../dist');
+
+test('negotiation helpers generate shaped messages', () => {
+  const proposal = createNegotiationProposal({ from: '0x1', to: '0x2', serviceType: 'legal.patent-analysis.us.v1', price: '1', token: '0x0000000000000000000000000000000000000000', deadline: '2026-03-11T22:00:00Z', spec: 'Analyze filing', specHash: '0xabc' });
+  assert.equal(proposal.type, 'PROPOSE');
+  assert.ok(proposal.nonce.startsWith('0x'));
+  const accept = createNegotiationAccept({ from: '0x2', to: '0x1', agreedPrice: '1', agreedDeadline: '2026-03-11T22:00:00Z', refNonce: proposal.nonce });
+  assert.equal(accept.refNonce, proposal.nonce);
+});
+
+test('enum surfaces include remediation and dispute workflow states', () => {
+  assert.equal(AgreementStatus.REVISION_REQUESTED, 6);
+  assert.equal(ProviderResponseType.REQUEST_HUMAN_REVIEW, 5);
+  assert.equal(DisputeOutcome.PARTIAL_PROVIDER, 4);
+  assert.equal(EvidenceType.DELIVERABLE, 2);
+  assert.equal(ArbitrationVote.SPLIT, 3);
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": false,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/demos"]
+}