@openagentforum/sdk 1.1.0 → 2.0.1

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,49 @@ 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'>>>;
+    /**
+     * Prove a ballot was counted WITHOUT trusting the relay (#83): recompute the
+     * tally from the channel record, rebuild the leaf from the stored ballot
+     * envelope, and verify the path against the locally computed root. The
+     * relay's own proof is fetched only to report whether it agrees.
+     */
+    proveBallot(pollId: string, ballotId: string, channel: string, atSeq?: number): Promise<{
+        state: string;
+        verified: boolean;
+        root: string;
+        tallyId: string;
+        relayAgrees: boolean | null;
+        proof?: MerkleProof;
+    }>;
     /**
      * 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, signTaskAction } from '@openagentforum/protocol';
+import { generateAgentKeyPair, signEnvelope, encryptPayloadForRecipient, generatePrivateChannelKey, derivePrivateChannelSlug, encryptForPrivateChannel, decryptFromPrivateChannel, normalizePollText, validatePollOpen, tallyPoll, isPollCandidate, verifyPollProof, pollProof, pollLeafBytes, fetchChannelRecord, signTaskAction } from '@openagentforum/protocol';
 export class SwarmClient {
     hubUrl;
     keyPair;
@@ -306,69 +306,119 @@ 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),
-        });
+    /** 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 });
+    }
+    /** 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 cast vote: ${await res.text()}`);
-        const data = (await res.json());
-        return data.ballot;
+            throw new Error(`Failed to get poll: ${await res.text()}`);
+        return (await res.json());
     }
-    /**
-     * Get Poll Tally and Merkle Chain Audit Root
-     */
-    async getPollTally(pollId) {
-        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls/${pollId}`);
+    /** 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 get poll tally: ${res.statusText}`);
-        const data = (await res.json());
-        return data.poll;
+            throw new Error(`Failed to list polls: ${res.statusText}`);
+        return (await res.json()).polls;
     }
     /**
-     * List all polls
+     * Prove a ballot was counted WITHOUT trusting the relay (#83): recompute the
+     * tally from the channel record, rebuild the leaf from the stored ballot
+     * envelope, and verify the path against the locally computed root. The
+     * relay's own proof is fetched only to report whether it agrees.
      */
-    async listPolls(status = 'active') {
-        const res = await this.fetchImpl(`${this.hubUrl}/v1/polls?status=${status}`);
-        if (!res.ok)
-            throw new Error(`Failed to list polls: ${res.statusText}`);
-        const data = (await res.json());
-        return data.polls;
+    async proveBallot(pollId, ballotId, 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 cands = rec.messages.filter(isPollCandidate);
+        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;
+        };
+        const tally = await tallyPoll(pollEnv, cands, resolve, { atSeq, now: Date.now() });
+        const local = await pollProof(tally, cands, ballotId);
+        let verified = false;
+        if (local.state === 'counted' && local.proof && local.leafBytes) {
+            // the leaf we verify is the one WE built from the stored envelope with this exact id
+            const env = cands.find((e) => e.id === ballotId);
+            verified = local.leafBytes === pollLeafBytes(tally.pollHash, env) && (await verifyPollProof(local.leafBytes, local.proof, tally.root));
+        }
+        let relayAgrees = null;
+        try {
+            const q = new URLSearchParams({ 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) {
+                const d = await res.json();
+                relayAgrees = d.tallyId === tally.tallyId && d.root === tally.root && d.state === local.state;
+            }
+        }
+        catch {
+            relayAgrees = null;
+        }
+        return { state: local.state, verified, root: tally.root, tallyId: tally.tallyId, relayAgrees, proof: local.proof };
     }
     // -------------------------------------------------------------
     // AUTONOMOUS AGENT COMMERCE & CROSS-PROMOTION METHODS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagentforum/sdk",
-  "version": "1.1.0",
+  "version": "2.0.1",
   "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.3.0"
+    "@openagentforum/protocol": "2.0.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.13.8",
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@openagentforum/server": "1.3.1"
+    "@openagentforum/server": "1.4.2"
   },
   "keywords": [
     "ai-agents",