feat(publisher): proposal pointers — kind 32100 joins record, Irys and chain

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: MaxBrych

docs/PUBLIC_DATA_ON_NOSTR.md

@@ -29,6 +29,7 @@ public datasets onto the relay every 5 minutes — first live pass: 41 events ac
 | **town news** — NIP-23 `30023`, `d=news:<uuid>`, town-signed, slug tag for routing | |
 | **restaurant menus** — kind `32101` (`restaurant:<id>`), one replaceable event per restaurant, prices as raw decimals + EUR | |
 | **civic notices** — kind `32102` (`alert:<id>` or `announcement:<id>`), town-signed, resolved alerts are edits (never deleted) | |
+| **governance proposals** — kind `32100` (`proposal:<id>`), a discoverable pointer: body on Irys, state on-chain, status snapshot in tags | |
 | **marketplace** — NIP-15 `30018`, seller opt-in gated (unrevoked npub binding), withdrawal-as-edit | |
 | **business deals** — NIP-99 `30402`, offers signed under the business's derived key | |
 | **images** — mirrored content-addressed at `/media/<sha256>` (Blossom-shaped reads); the hash in the signed event is the integrity check | |

packages/protocol/examples/roebel.netizen.json

@@ -209,7 +209,8 @@
         "businesses",
         "news",
         "notices",
-        "menus"
+        "menus",
+        "proposals"
       ],
       "intervalSeconds": 300,
       "backfeed": true

packages/publisher/src/cli.ts

@@ -23,7 +23,7 @@ function required(name: string): string {
   return value;
 }
 
-const VALID_DATASETS = new Set<DatasetName>(["events", "cinema", "orgs", "articles", "marketplace", "deals", "news", "businesses", "notices", "menus"]);
+const VALID_DATASETS = new Set<DatasetName>(["events", "cinema", "orgs", "articles", "marketplace", "deals", "news", "businesses", "notices", "menus", "proposals"]);
 
 async function main(): Promise<void> {
   const nodeId = required("NODE_ID");
@@ -40,7 +40,7 @@ async function main(): Promise<void> {
     .map((d) => d.trim())
     .filter((d): d is DatasetName => VALID_DATASETS.has(d as DatasetName));
   if (datasets.length === 0) {
-    console.error("PUBLISH_DATASETS names no known dataset (events, cinema, orgs, articles, marketplace, deals, news, businesses, notices, menus)");
+    console.error("PUBLISH_DATASETS names no known dataset (events, cinema, orgs, articles, marketplace, deals, news, businesses, notices, menus, proposals)");
     process.exit(2);
   }
 
@@ -54,6 +54,8 @@ async function main(): Promise<void> {
 
   console.log(`publisher for "${nodeId}" -> ${relayUrl}; datasets: ${datasets.join(", ")}`);
 
+  const governor = process.env.PROPOSAL_GOVERNOR;
+
   // Content-addressed media mirror: images referenced by published events are
   // fetched once, stored by sha256 beside a content-type sidecar, and the
   // event's URL is rewritten to the node's own /media/<sha>. Any failure keeps
@@ -147,6 +149,7 @@ async function main(): Promise<void> {
         datasets,
         fetchRows,
         relayUrl,
+        ...(governor ? { governor } : {}),
         ...(mirrorMedia ? { mirrorMedia } : {}),
         // Announce signing keys BEFORE publishing, atomically — the allow-list
         // syncer reads this file on its own schedule and must never see a half

packages/publisher/src/mappers.ts

@@ -586,6 +586,52 @@ export function noticeToSpec(
 /** Netizen menu — see the fork-with-fallback spec §3.2. */
 export const KIND_MENU = 32101;
 
+/** Netizen proposal metadata — see the fork-with-fallback spec §3.2. */
+export const KIND_PROPOSAL_META = 32100;
+
+/**
+ * A governance proposal → a discoverable pointer on the record.
+ *
+ * The body is already permanent on Irys and the authoritative state (votes,
+ * tallies, execution) lives on-chain; this event makes both findable and
+ * joinable from the record. The `status` tag is a SNAPSHOT for list rendering
+ * — clients needing truth read the Governor. The proposer's wallet is
+ * deliberately absent: it is on-chain for those who need it, and the record
+ * never carries raw addresses.
+ */
+export function proposalToSpec(row: Row, governor: string): PublishSpec | null {
+  if (!governor) return null;
+  const proposalId = str(row, "proposal_id");
+  const title = str(row, "title");
+  if (!proposalId || !title) return null;
+
+  const tags: string[][] = [
+    ["d", `proposal:${proposalId}`],
+    ["title", title],
+    ["governor", governor],
+    ["t", "proposal"],
+  ];
+  const chainId = str(row, "blockchain_proposal_id");
+  if (chainId) tags.push(["proposal_id", chainId]);
+  const irys = str(row, "irys_content_id");
+  if (irys) tags.push(["irys", irys]);
+  const category = str(row, "category");
+  if (category) tags.push(["t", category]);
+  const state = row["state"];
+  if (state !== null && state !== undefined) tags.push(["status", String(state)]);
+  const createdAt = str(row, "created_at");
+  if (createdAt) tags.push(["published_at", String(Math.floor(Date.parse(createdAt) / 1000))]);
+
+  return {
+    scope: TOWN_SCOPE,
+    kind: KIND_PROPOSAL_META,
+    d: `proposal:${proposalId}`,
+    content: str(row, "summary") ?? "",
+    tags,
+    createdAt: unixFromUpdatedAt(row),
+  };
+}
+
 export interface MenuInput {
   restaurant: Row;
   categories: Row[];

packages/publisher/src/sync.ts

@@ -18,6 +18,7 @@ import {
   noticeToSpec,
   orgPostToSpec,
   orgToSpec,
+  proposalToSpec,
   type MenuInput,
   type PublishSpec,
 } from "./mappers.js";
@@ -64,6 +65,11 @@ export interface PublisherDeps {
    */
   onPubkeys?: (pubkeys: string[]) => Promise<void>;
   log?: (message: string) => void;
+  /**
+   * Governor address for proposals ("100:0x5F5e…" format: chainId:address).
+   * Required if datasets includes "proposals".
+   */
+  governor?: string;
 }
 
 export interface PublishSummary {
@@ -77,7 +83,7 @@ export interface PublishSummary {
 
 /** Build the full spec list for one pass. Exposed for tests. */
 export async function buildSpecs(
-  deps: Pick<PublisherDeps, "datasets" | "fetchRows" | "nodeId">,
+  deps: Pick<PublisherDeps, "datasets" | "fetchRows" | "nodeId" | "governor">,
 ): Promise<PublishSpec[]> {
   const specs: PublishSpec[] = [];
   const wantsOrgs = deps.datasets.includes("orgs");
@@ -264,6 +270,20 @@ export async function buildSpecs(
       if (spec) specs.push(spec);
     }
   }
+  if (deps.datasets.includes("proposals")) {
+    if (!deps.governor) {
+      // Deliberately loud: a configured dataset that silently publishes nothing is a lie.
+      throw new Error("datasets includes 'proposals' but PROPOSAL_GOVERNOR is not set");
+    }
+    const rows = await deps.fetchRows(
+      "proposals",
+      "select=id,proposal_id,blockchain_proposal_id,proposal_number,title,summary,category,irys_content_id,state,created_at,updated_at",
+    );
+    for (const row of rows) {
+      const spec = proposalToSpec(row, deps.governor);
+      if (spec) specs.push(spec);
+    }
+  }
   return specs;
 }
 

packages/publisher/test/mappers.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import { htmlToMarkdown } from "../src/html-to-md.js";
-import { articleToSpec, berlinToUnix, businessToSpec, dealToSpec, eventToSpec, listingToSpec, MAPPER_VERSION, menuToSpec, movieToSpec, newsToSpec, noticeToSpec, orgPostToSpec, orgToSpec } from "../src/mappers.js";
+import { articleToSpec, berlinToUnix, businessToSpec, dealToSpec, eventToSpec, listingToSpec, MAPPER_VERSION, menuToSpec, movieToSpec, newsToSpec, noticeToSpec, orgPostToSpec, orgToSpec, proposalToSpec } from "../src/mappers.js";
 
 const ORG_ID = "11111111-1111-1111-1111-111111111111";
 const ORGS = new Set([ORG_ID]);
@@ -566,3 +566,33 @@ describe("menu mapping", () => {
     assert.equal(menu.categories[1].name, "Another Active");
   });
 });
+
+describe("proposal mapping", () => {
+  it("proposalToSpec: a proposal becomes a discoverable pointer", () => {
+    const spec = proposalToSpec(
+      { id: "p-row-1", proposal_id: "42", blockchain_proposal_id: "0xabc123", proposal_number: 7,
+        title: "Neuer Spielplatz", summary: "Am Hafen", category: "infrastruktur",
+        irys_content_id: "IRYS_TX_1", state: 1, created_at: "2026-07-01T10:00:00Z",
+        updated_at: "2026-07-02T10:00:00Z",
+        proposer_address: "0x5e6528DEADBEEF" },
+      "100:0x5F5e499Dc1872c2Ce19a4b50cd10f680e78E3Ba3",
+    );
+    assert.ok(spec);
+    assert.equal(spec!.kind, 32100);
+    assert.equal(spec!.scope, "town");
+    assert.equal(spec!.d, "proposal:42");
+    assert.equal(spec!.content, "Am Hafen");
+    const tag = (n: string) => spec!.tags.find((t) => t[0] === n)?.[1];
+    assert.equal(tag("title"), "Neuer Spielplatz");
+    assert.equal(tag("governor"), "100:0x5F5e499Dc1872c2Ce19a4b50cd10f680e78E3Ba3");
+    assert.equal(tag("proposal_id"), "0xabc123");
+    assert.equal(tag("irys"), "IRYS_TX_1");
+    assert.equal(tag("status"), "1");
+    // The proposer's wallet must NOT ride on the record event.
+    assert.ok(!JSON.stringify(spec).includes("0x5e6528DEADBEEF"));
+  });
+
+  it("proposalToSpec: no governor configured → nothing publishes", () => {
+    assert.equal(proposalToSpec({ id: "x", proposal_id: "1", title: "t" }, ""), null);
+  });
+});