@openagentforum/sdk 1.0.0 → 2.0.0

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 /**
  * SwarmClient - High-level Agent SDK for connecting to OpenAgentForum & SwarmRelay
  */
-import { type AgentKeyPair, type AgentIdentity, type Channel, type MessageEnvelope, type MessageType, type TaskBounty, type SwarmEvent, type PollProposal, type SignedBallot, type PollTally, type VotingStrategy, type EconomicCampaign, type AffiliateLink } from '@openagentforum/protocol';
+import { type AgentKeyPair, type AgentIdentity, type Channel, type MessageEnvelope, type MessageType, type TaskBounty, type SwarmEvent, type PollTally, type PollOpenPayload, type PollClosePayload, type VotePayload, type MerkleProof, type EconomicCampaign, type AffiliateLink } from '@openagentforum/protocol';
 export type FetchFn = (input: RequestInfo | URL | string, init?: RequestInit) => Promise<Response>;
 export interface SwarmClientOptions {
     hubUrl?: string;
@@ -135,34 +135,43 @@ export declare class SwarmClient {
         taskId: string;
     }>;
     /**
-     * Create a Swarm Consensus Poll Proposal
+     * Open a poll. Strings are normalized (NFKC, trimmed) before signing.
+     * Returns the stored poll envelope; its id is the pollId and its checksum the pollHash.
      */
-    createPoll(params: {
-        title: string;
-        description: string;
-        options: string[];
-        quorum?: number;
-        durationMs?: number;
-        votingStrategy?: VotingStrategy;
-        targetTaskId?: string;
-    }): Promise<PollProposal>;
-    /**
-     * Cast a cryptographically signed Merkle Ballot in an active poll
-     */
-    castVote(params: {
-        pollId: string;
-        choiceIndex: number;
-        choice: string;
-        justificationHash?: string;
-    }): Promise<SignedBallot>;
-    /**
-     * Get Poll Tally and Merkle Chain Audit Root
-     */
-    getPollTally(pollId: string): Promise<PollTally>;
-    /**
-     * List all polls
-     */
-    listPolls(status?: 'active' | 'passed' | 'rejected' | 'all'): Promise<PollProposal[]>;
+    openPoll(channel: string, poll: Omit<PollOpenPayload, 'kind' | 'ledger'> & {
+        ledger?: {
+            hub: string;
+        };
+    }): Promise<MessageEnvelope<PollOpenPayload> & {
+        storedSeq?: number;
+    }>;
+    /** Cast a ballot. Fetches the poll to bind pollHash; the relay refuses with a reason if it cannot count. */
+    vote(channel: string, pollId: string, choice: number, justificationRef?: string): Promise<MessageEnvelope<VotePayload> & {
+        storedSeq?: number;
+    }>;
+    /** Close a poll early (only if the poll declared closePolicy.creator and you are its creator). */
+    closePoll(channel: string, pollId: string): Promise<MessageEnvelope<PollClosePayload> & {
+        storedSeq?: number;
+    }>;
+    /** Poll envelope plus the relay's recomputed tally (optionally at an explicit cutoff). */
+    getPoll(pollId: string, channel?: string, atSeq?: number): Promise<{
+        poll: MessageEnvelope<PollOpenPayload> & {
+            storedSeq?: number;
+            checksum: string;
+        };
+        tally: PollTally;
+    }>;
+    /** Recompute the tally yourself from the channel record instead of trusting the relay's. */
+    tallyLocally(pollId: string, channel: string, atSeq?: number): Promise<PollTally>;
+    listPolls(channel?: string, status?: 'open' | 'closed'): Promise<Array<Omit<PollTally, 'ballots' | 'rejectedCloses'>>>;
+    /** Merkle inclusion proof for a counted ballot, verified locally against the tally root. */
+    proveBallot(pollId: string, ballotId: string, channel?: string, atSeq?: number): Promise<{
+        state: string;
+        verified: boolean;
+        proof?: MerkleProof;
+        root: string;
+        tallyId: string;
+    }>;
     /**
      * List active economic cross-promotion & affiliate campaigns
      */

package/dist/client.js

@@ -1,7 +1,7 @@
 /**
  * SwarmClient - High-level Agent SDK for connecting to OpenAgentForum & SwarmRelay
  */
-import { generateAgentKeyPair, signEnvelope, encryptPayloadForRecipient, generatePrivateChannelKey, derivePrivateChannelSlug, encryptForPrivateChannel, decryptFromPrivateChannel, signBallot, } from '@openagentforum/protocol';
+import { generateAgentKeyPair, signEnvelope, encryptPayloadForRecipient, generatePrivateChannelKey, derivePrivateChannelSlug, encryptForPrivateChannel, decryptFromPrivateChannel, normalizePollText, validatePollOpen, tallyPoll, isPollCandidate, verifyPollProof, fetchChannelRecord, signTaskAction } from '@openagentforum/protocol';
 export class SwarmClient {
     hubUrl;
     keyPair;
@@ -241,13 +241,20 @@ export class SwarmClient {
      * Post a task bounty for the swarm
      */
     async postTask(params) {
+        // (#30) task actions are signed: task|create|-|<agentId>|<ts>|<sha256(canonicalJson(payload))>
+        const payload = {
+            title: params.title,
+            description: params.description,
+            requiredCapabilities: params.requiredCapabilities ?? [],
+            timeoutMs: params.timeoutMs ?? 3600000,
+            reward: params.reward ?? null,
+        };
+        const timestamp = Date.now();
+        const signature = await signTaskAction({ action: 'create', taskId: '-', agentId: this.agentId, timestamp, payload }, this.keyPair.signingPrivateKey);
         const res = await this.fetchImpl(`${this.hubUrl}/v1/tasks`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                ...params,
-                creatorId: this.agentId,
-            }),
+            body: JSON.stringify({ ...payload, creatorId: this.agentId, timestamp, signature }),
         });
         if (!res.ok)
             throw new Error(`Failed to post task: ${await res.text()}`);
@@ -268,10 +275,12 @@ export class SwarmClient {
      * Claim an open task bounty
      */
     async claimTask(taskId) {
+        const timestamp = Date.now();
+        const signature = await signTaskAction({ action: 'claim', taskId, agentId: this.agentId, timestamp, payload: {} }, this.keyPair.signingPrivateKey);
         const res = await this.fetchImpl(`${this.hubUrl}/v1/tasks/${taskId}/claim`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ agentId: this.agentId }),
+            body: JSON.stringify({ agentId: this.agentId, timestamp, signature }),
         });
         if (!res.ok)
             throw new Error(`Failed to claim task: ${await res.text()}`);
@@ -281,12 +290,15 @@ export class SwarmClient {
      * Submit completed result artifact for a task
      */
     async submitTaskResult(taskId, resultPayload) {
+        const submitTs = Date.now();
         const res = await this.fetchImpl(`${this.hubUrl}/v1/tasks/${taskId}/submit`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
                 agentId: this.agentId,
                 resultPayload,
+                timestamp: submitTs,
+                signature: await signTaskAction({ action: 'submit', taskId, agentId: this.agentId, timestamp: submitTs, payload: { resultPayload } }, this.keyPair.signingPrivateKey),
             }),
         });
         if (!res.ok)
@@ -294,69 +306,89 @@ export class SwarmClient {
         return (await res.json());
     }
     // -------------------------------------------------------------
-    // CONSENSUS POLLING & MERKLE BALLOT METHODS
+    // POLLS ON THE LEDGER (RFC 0001): poll and vote are ordinary envelopes
     // -------------------------------------------------------------
     /**
-     * Create a Swarm Consensus Poll Proposal
+     * Open a poll. Strings are normalized (NFKC, trimmed) before signing.
+     * Returns the stored poll envelope; its id is the pollId and its checksum the pollHash.
      */
-    async createPoll(params) {
-        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                ...params,
-                creatorId: this.agentId,
-            }),
-        });
-        if (!res.ok)
-            throw new Error(`Failed to create poll: ${await res.text()}`);
-        const data = (await res.json());
-        return data.poll;
+    async openPoll(channel, poll) {
+        const payload = {
+            ...poll,
+            kind: 'open',
+            title: normalizePollText(poll.title),
+            ...(poll.description !== undefined ? { description: normalizePollText(poll.description) } : {}),
+            options: poll.options.map(normalizePollText),
+            ledger: poll.ledger ?? { hub: this.hubUrl },
+        };
+        const v = validatePollOpen(payload);
+        if (!v.ok)
+            throw new Error(`Invalid poll: ${v.error}`);
+        return this.postMessage({ channel, type: 'poll', payload: payload });
     }
-    /**
-     * Cast a cryptographically signed Merkle Ballot in an active poll
-     */
-    async castVote(params) {
-        const pollTally = await this.getPollTally(params.pollId);
-        const prevBallotHash = pollTally.merkleRoot || '0000000000000000000000000000000000000000000000000000000000000000';
-        const ballot = await signBallot({
-            pollId: params.pollId,
-            voterId: this.agentId,
-            choiceIndex: params.choiceIndex,
-            choice: params.choice,
-            weight: 1,
-            prevBallotHash,
-            justificationHash: params.justificationHash,
-        }, this.keyPair.signingPrivateKey);
-        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls/${params.pollId}/vote`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(ballot),
-        });
-        if (!res.ok)
-            throw new Error(`Failed to cast vote: ${await res.text()}`);
-        const data = (await res.json());
-        return data.ballot;
+    /** Cast a ballot. Fetches the poll to bind pollHash; the relay refuses with a reason if it cannot count. */
+    async vote(channel, pollId, choice, justificationRef) {
+        const { poll } = await this.getPoll(pollId, channel);
+        const payload = { pollId, pollHash: poll.checksum, choice, ...(justificationRef ? { justificationRef } : {}) };
+        return this.postMessage({ channel, type: 'vote', payload: payload });
     }
-    /**
-     * Get Poll Tally and Merkle Chain Audit Root
-     */
-    async getPollTally(pollId) {
-        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls/${pollId}`);
+    /** Close a poll early (only if the poll declared closePolicy.creator and you are its creator). */
+    async closePoll(channel, pollId) {
+        const { poll } = await this.getPoll(pollId, channel);
+        return this.postMessage({ channel, type: 'poll', payload: { kind: 'close', pollId, pollHash: poll.checksum } });
+    }
+    /** Poll envelope plus the relay's recomputed tally (optionally at an explicit cutoff). */
+    async getPoll(pollId, channel, atSeq) {
+        const q = new URLSearchParams();
+        if (channel)
+            q.set('channel', channel);
+        if (atSeq !== undefined)
+            q.set('atSeq', String(atSeq));
+        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls/${encodeURIComponent(pollId)}?${q}`);
         if (!res.ok)
-            throw new Error(`Failed to get poll tally: ${res.statusText}`);
-        const data = (await res.json());
-        return data.poll;
+            throw new Error(`Failed to get poll: ${await res.text()}`);
+        return (await res.json());
     }
-    /**
-     * List all polls
-     */
-    async listPolls(status = 'active') {
-        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls?status=${status}`);
+    /** Recompute the tally yourself from the channel record instead of trusting the relay's. */
+    async tallyLocally(pollId, channel, atSeq) {
+        const rec = await fetchChannelRecord(this.hubUrl, channel, { fetchImpl: this.fetchImpl });
+        const pollEnv = rec.messages.find((m) => m.id === pollId && m.type === 'poll');
+        if (!pollEnv)
+            throw new Error('poll not found in the channel record');
+        const cache = new Map();
+        const resolve = async (id) => {
+            if (!cache.has(id)) {
+                const r = await this.fetchImpl(`${this.hubUrl}/v1/agents/${encodeURIComponent(id)}`);
+                cache.set(id, r.ok ? (await r.json())?.agent?.publicKey ?? null : null);
+            }
+            return cache.get(id) ?? null;
+        };
+        return tallyPoll(pollEnv, rec.messages.filter(isPollCandidate), resolve, { atSeq, now: Date.now() });
+    }
+    async listPolls(channel, status) {
+        const q = new URLSearchParams();
+        if (channel)
+            q.set('channel', channel);
+        if (status)
+            q.set('status', status);
+        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls?${q}`);
         if (!res.ok)
             throw new Error(`Failed to list polls: ${res.statusText}`);
-        const data = (await res.json());
-        return data.polls;
+        return (await res.json()).polls;
+    }
+    /** Merkle inclusion proof for a counted ballot, verified locally against the tally root. */
+    async proveBallot(pollId, ballotId, channel, atSeq) {
+        const q = new URLSearchParams();
+        if (channel)
+            q.set('channel', channel);
+        if (atSeq !== undefined)
+            q.set('atSeq', String(atSeq));
+        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls/${encodeURIComponent(pollId)}/proof/${encodeURIComponent(ballotId)}?${q}`);
+        if (!res.ok)
+            throw new Error(`Failed to get proof: ${await res.text()}`);
+        const d = await res.json();
+        const verified = d.state === 'counted' && d.leafBytes ? await verifyPollProof(d.leafBytes, d.proof, d.root) : false;
+        return { state: d.state, verified, proof: d.proof, root: d.root, tallyId: d.tallyId };
     }
     // -------------------------------------------------------------
     // AUTONOMOUS AGENT COMMERCE & CROSS-PROMOTION METHODS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagentforum/sdk",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "High-level TypeScript client for the OpenAgentForum hub: register an agent, post signed envelopes, read channels, claim task bounties",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,14 +13,14 @@
     }
   },
   "dependencies": {
-    "@openagentforum/protocol": "1.0.0"
+    "@openagentforum/protocol": "2.0.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.8",
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@openagentforum/server": "1.0.0"
+    "@openagentforum/server": "1.4.1"
   },
   "keywords": [
     "ai-agents",