@msgboard/sdk 0.0.28 → 0.0.31

package/README.md

@@ -10,7 +10,7 @@ npm i --save @msgboard/sdk
 
 ## Quickstart
 
-You need an RPC endpoint whose node runs the `msgboard_` module. Public PulseChain/Ethereum RPCs do **not** run it yet; valve.city does (for example `https://one.valve.city/rpc/vk_demo/evm/369`). You can also run your own node with the module.
+You need an RPC endpoint whose node runs the `msgboard_` module. Public PulseChain/Ethereum RPCs do **not** run it yet; [valve.city](https://valve.city) does. Its RPC endpoints are **keyed** — the API key sits in the path (`https://one.valve.city/rpc/<key>/evm/<chainId>`), and `vk_demo` is a public demo key for trying it out (for example `https://one.valve.city/rpc/vk_demo/evm/369`). You can also run your own node with the module.
 
 ### with viem
 
@@ -54,7 +54,19 @@ const content = await board.content()      // messages grouped by category
 
 ## Finding a node
 
-A node must run the `msgboard_` module to serve these methods. If `status()` reports `enabled: false`, or a call returns JSON-RPC error `-32601` (method not found), the node does not have the module — point at one that does. See the live status badge on https://msgboard.xyz for working endpoints.
+A node must run the `msgboard_` module to serve these methods. Ordinary public RPCs (for example `rpc.pulsechain.com`) do **not** run it. If `status()` reports `enabled: false`, or a call returns JSON-RPC error `-32601` (method not found), the node does not have the module — point at one that does.
+
+### Supporting providers
+
+| Provider | RPC | Chains | Node code |
+|---|---|---|---|
+| [valve.city](https://valve.city) | `https://one.valve.city/rpc/<key>/evm/<chainId>` | 1, 369, 943 | [valve-tech/reth](https://github.com/valve-tech/reth) |
+
+The endpoints are **keyed** — the API key sits in the path, and `vk_demo` is a public, rate-limited demo key for trying things out (for example `https://one.valve.city/rpc/vk_demo/evm/369`). The list is small for now; other node teams (PulseChain, g4mm4) are working toward serving the module. The live support matrix is the **Join the Network** section on https://msgboard.xyz.
+
+### Running your own
+
+The module is implemented in the [valve-tech/reth](https://github.com/valve-tech/reth) fork (`crates/net/msgboard` + `msgboard-types`). Run that node for a chain and its RPC will serve the `msgboard_` methods — verify with `status()` returning `enabled: true`. There is no separate gateway to deploy: the module lives in the execution client itself.
 
 ## Proof of work and difficulty
 
@@ -72,13 +84,38 @@ board.getDifficulty('0x...') // bigint
 
 `workMultiplier` and `workDivisor` come from `status()` and are applied automatically by `doPoW`.
 
+### The board enforces a floor, not a fixed config
+
+A message **declares its own** `workMultiplier` and `workDivisor` — they are fields of the message, and they are cryptographically baked into the work (the challenge is derived from a digest of the two factors, so you cannot misreport them without redoing the grind). The node computes the message's difficulty from the message's *own* declared factors and accepts it when **both**:
+
+1. the proof of work satisfies that declared difficulty (`workHash % difficulty == 0`), and
+2. the declared difficulty is **at least** the board's current minimum — a single work threshold.
+
+The consequence is the part that surprises people: **a message does not have to use the same factors as the board.** It only has to do *at least* as much work as the floor demands. Any factor pair whose resulting difficulty meets or exceeds the floor is accepted — even a different ratio, even far more work than required. (Verified on a live node: a message declaring `30000 / 3000000` was accepted by a board configured for `10000 / 1000000`.)
+
+### Manipulating the work
+
+`doPoW` reads the board's live factors from `status()` because they produce the **cheapest valid message** — the least work that still clears the floor. But you can deliberately do more:
+
+```ts
+const status = await board.status()
+// Default: grind exactly to the board's floor (cheapest acceptable message).
+board.setDifficultyFactors(BigInt(status.workMultiplier), BigInt(status.workDivisor))
+
+// Or do extra work — e.g. halve the divisor to double the difficulty. Still accepted (it
+// clears the floor), and it stays valid even if the board later tightens up to that level.
+board.setDifficultyFactors(BigInt(status.workMultiplier), BigInt(status.workDivisor) / 2n)
+```
+
+So the two factors are best understood as a **board-level floor** plus a **per-message dial**: operators raise the floor (a higher `workMultiplier` or lower `workDivisor`) to admit fewer messages and resist spam, or lower it to admit more; individual senders may always pay *above* the floor. The only failure mode is paying **below** it — work that cleared a looser floor is rejected once the board raises it, which is why `doPoW` grinds against the **live** factors by default.
+
 ## Categories
 
 A category is a 32-byte hash. Pass a string and the client hashes it for you (`categoryHash`); pass hex and it is used as-is. The demo board uses the `gasmoneyplease` category.
 
 ## Ephemerality
 
-Messages are short-lived: the board retains roughly the last 120 blocks of messages, so the board is a live signal, not durable storage.
+Messages are short-lived: the board retains roughly the last 120 blocks of messages, so the board is a live signal, not durable storage. The board also has a maximum size cap — if a burst of large messages fills the cap before the 120-block window expires, new submissions may be rejected until older messages age out. Design for loss: treat the board as a delivery channel, not a store.
 
 ## Keeping work off the UI thread
 
@@ -299,15 +336,61 @@ Object whose values are `RPCMessage[]`.
 
 ## Client methods (not JSON-RPC)
 
-These run in the client, not on the node, so they are not in the OpenRPC spec:
+These run in the client process, not on the node, so they are not part of the OpenRPC spec.
+
+### `doPoW(category, data, limit?)`
+
+Grinds a valid proof-of-work message. Reads current difficulty from `status()` before starting, so the work is always valid for the live board settings. Returns `{ message, stats }` where `stats` includes `nonce`, `duration`, and the number of iterations. The `limit` parameter sets a maximum number of iterations — useful for streaming progress or cancellation in long-running environments.
+
+### `getDifficulty(data)`
 
-- `doPoW(category, data, limit?)` — grind a valid proof-of-work message. Returns `{ message, stats }`.
-- `getDifficulty(data)` — the difficulty for a given payload, as a `bigint`.
-- Utilities: `categoryHash`, `checkWork`, `difficulty`, `encodeData`, `toRLP`, `fromRLP`, `fromRPCMessage`, `toRPCMessage`, `wrapLegacySend`.
+Returns the difficulty threshold for a given payload hex string as a `bigint`. Helpful for estimating how long `doPoW` will take before committing to it.
+
+### `categoryHash(name)`
+
+Encodes a plain-text category name to the 32-byte hex hash the board stores. Pass the result directly to `doPoW` or `content()` filters.
+
+### `wrapLegacySend(provider)`
+
+Wraps an ethers v5 `JsonRpcProvider` (or any provider with a `send` method) into the `Provider` interface the client expects. Use this when you cannot upgrade to viem.
+
+### Other utilities
+
+`checkWork`, `difficulty`, `encodeData`, `toRLP`, `fromRLP`, `fromRPCMessage`, `toRPCMessage` — lower-level building blocks for custom proof-of-work loops, message encoding, and RPC message conversion. Their signatures are in the TypeScript types shipped with the package.
+
+## Building automations
+
+For server-side work — polling continuously, reacting to specific categories, archiving messages, triggering cross-chain actions — install the companion relayer package:
+
+```sh
+npm i @msgboard/relayer
+```
+
+```ts
+import { http } from 'viem'
+import { Relayer, msgboardContentSource, noopAction } from '@msgboard/relayer'
+import type { RPCMessage } from '@msgboard/sdk'
+
+const relayer = new Relayer<RPCMessage>({
+  node: { transport: http('https://one.valve.city/rpc/vk_demo/evm/369') },
+  // chain is auto-detected via eth_chainId — pass node.chain to override
+  source: msgboardContentSource({ category: 'myapp' }),
+  key: (msg) => msg.hash,
+  action: noopAction(),
+  // mode defaults to 'observe' — swap in webhookAction or submitMessageAction and set
+  // mode: 'live' to execute real effects
+})
+
+relayer.start()
+```
+
+`Relayer` polls on a configurable heartbeat, deduplicates via a pluggable store (in-memory, Postgres), records everything to an optional archive sink regardless of mode, and gates `action.execute` on `mode: 'live'`. See the [`@msgboard/relayer`](https://www.npmjs.com/package/@msgboard/relayer) package for the full API, built-in sources/actions, and runnable examples.
 
 ## Machine-readable spec
 
-The JSON-RPC surface is published as an OpenRPC document at `openrpc.json` in this package. Point the OpenRPC Playground or a code generator at it.
+The JSON-RPC surface is published as an OpenRPC document — [`openrpc.json`](https://github.com/valve-tech/msgboard/blob/master/packages/sdk/openrpc.json) — in this package, and hosted at [`msgboard.xyz/openrpc.json`](https://msgboard.xyz/openrpc.json). Open it in the [OpenRPC Playground](https://playground.open-rpc.org/?schemaUrl=https%3A%2F%2Fmsgboard.xyz%2Fopenrpc.json) (it loads the schema and pre-selects the valve.city PulseChain mainnet endpoint so you can call live methods directly), or point a code generator at the hosted spec.
+
+All published packages are under the [`@msgboard`](https://www.npmjs.com/search?q=%40msgboard) scope on npm.
 
 ## License
 

package/openrpc.json

@@ -4,94 +4,309 @@
     "title": "MsgBoard JSON-RPC API",
     "version": "0.0.28",
     "description": "JSON-RPC methods exposed by the msgboard_ module. Any node running the module serves these methods. Proof of work, not a fee, gates message submission.",
-    "license": { "name": "MIT" }
+    "license": {
+      "name": "MIT"
+    }
   },
+  "servers": [
+    {
+      "name": "PulseChain mainnet (valve.city demo)",
+      "url": "https://one.valve.city/rpc/vk_demo/evm/369"
+    }
+  ],
   "methods": [
     {
       "name": "msgboard_status",
       "summary": "Board status and the difficulty factors required for valid messages.",
       "params": [],
-      "result": { "name": "status", "schema": { "$ref": "#/components/schemas/Status" } },
+      "result": {
+        "name": "status",
+        "schema": {
+          "$ref": "#/components/schemas/Status"
+        }
+      },
       "examples": [
-        { "name": "default", "params": [], "result": { "name": "status", "value": { "enabled": true, "count": "0x0", "size": "0x0", "workMultiplier": "0x2710", "workDivisor": "0xf4240" } } }
+        {
+          "name": "default",
+          "params": [],
+          "result": {
+            "name": "status",
+            "value": {
+              "enabled": true,
+              "count": "0x0",
+              "size": "0x0",
+              "workMultiplier": "0x2710",
+              "workDivisor": "0xf4240"
+            }
+          }
+        }
       ]
     },
     {
       "name": "msgboard_categories",
       "summary": "The list of 32-byte category hashes currently present on the board.",
       "params": [],
-      "result": { "name": "categories", "schema": { "$ref": "#/components/schemas/Categories" } },
+      "result": {
+        "name": "categories",
+        "schema": {
+          "$ref": "#/components/schemas/Categories"
+        }
+      },
       "examples": [
-        { "name": "gasmoneyplease", "params": [], "result": { "name": "categories", "value": ["0x6761736d6f6e6579706c65617365000000000000000000000000000000000000"] } }
+        {
+          "name": "gasmoneyplease",
+          "params": [],
+          "result": {
+            "name": "categories",
+            "value": [
+              "0x6761736d6f6e6579706c65617365000000000000000000000000000000000000"
+            ]
+          }
+        }
       ]
     },
     {
       "name": "msgboard_content",
       "summary": "All messages on the board, grouped by category hash. Optionally filtered.",
-      "params": [ { "name": "filter", "required": false, "schema": { "$ref": "#/components/schemas/ContentFilter" } } ],
-      "result": { "name": "content", "schema": { "$ref": "#/components/schemas/Content" } },
+      "params": [
+        {
+          "name": "filter",
+          "required": false,
+          "schema": {
+            "$ref": "#/components/schemas/ContentFilter"
+          }
+        }
+      ],
+      "result": {
+        "name": "content",
+        "schema": {
+          "$ref": "#/components/schemas/Content"
+        }
+      },
       "examples": [
-        { "name": "empty", "params": [{ "name": "filter", "value": {} }], "result": { "name": "content", "value": {} } }
+        {
+          "name": "empty",
+          "params": [
+            {
+              "name": "filter",
+              "value": {}
+            }
+          ],
+          "result": {
+            "name": "content",
+            "value": {}
+          }
+        }
       ]
     },
     {
       "name": "msgboard_addMessage",
       "summary": "Submit a proof-of-work message (RLP-encoded) to the board.",
-      "params": [ { "name": "rlp", "required": true, "schema": { "$ref": "#/components/schemas/Hex" } } ],
-      "result": { "name": "hash", "schema": { "$ref": "#/components/schemas/Hex" } },
+      "params": [
+        {
+          "name": "rlp",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/Hex"
+          }
+        }
+      ],
+      "result": {
+        "name": "hash",
+        "schema": {
+          "$ref": "#/components/schemas/Hex"
+        }
+      },
       "examples": [
-        { "name": "submit", "params": [{ "name": "rlp", "value": "0xf800" }], "result": { "name": "hash", "value": "0x0d1e2f00000000000000000000000000000000000000000000000000c46845f9" } }
+        {
+          "name": "submit",
+          "params": [
+            {
+              "name": "rlp",
+              "value": "0xf800"
+            }
+          ],
+          "result": {
+            "name": "hash",
+            "value": "0x0d1e2f00000000000000000000000000000000000000000000000000c46845f9"
+          }
+        }
       ]
     },
     {
       "name": "msgboard_getMessage",
       "summary": "Fetch a single message by its hash.",
-      "params": [ { "name": "hash", "required": true, "schema": { "$ref": "#/components/schemas/Hex" } } ],
-      "result": { "name": "message", "schema": { "$ref": "#/components/schemas/RPCMessage" } },
+      "params": [
+        {
+          "name": "hash",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/Hex"
+          }
+        }
+      ],
+      "result": {
+        "name": "message",
+        "schema": {
+          "$ref": "#/components/schemas/RPCMessage"
+        }
+      },
       "examples": [
-        { "name": "zero", "params": [{ "name": "hash", "value": "0x0000000000000000000000000000000000000000000000000000000000000000" }], "result": { "name": "message", "value": { "version": "0x1", "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", "blockNumber": "0x0", "category": "0x0000000000000000000000000000000000000000000000000000000000000000", "data": "0x0000000000000000000000000000000000000000000000000000000000000000", "nonce": "0x0", "hash": "0x0000000000000000000000000000000000000000000000000000000000000000", "workMultiplier": "0x0", "workDivisor": "0x0" } } }
+        {
+          "name": "zero",
+          "params": [
+            {
+              "name": "hash",
+              "value": "0x0000000000000000000000000000000000000000000000000000000000000000"
+            }
+          ],
+          "result": {
+            "name": "message",
+            "value": {
+              "version": "0x1",
+              "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+              "blockNumber": "0x0",
+              "category": "0x0000000000000000000000000000000000000000000000000000000000000000",
+              "data": "0x0000000000000000000000000000000000000000000000000000000000000000",
+              "nonce": "0x0",
+              "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+              "workMultiplier": "0x0",
+              "workDivisor": "0x0"
+            }
+          }
+        }
       ]
     }
   ],
   "components": {
     "schemas": {
-      "Hex": { "title": "Hex", "type": "string", "pattern": "^0x[0-9a-fA-F]*$" },
+      "Hex": {
+        "title": "Hex",
+        "type": "string",
+        "pattern": "^0x[0-9a-fA-F]*$"
+      },
       "Status": {
-        "title": "Status", "type": "object",
-        "required": ["enabled", "count", "size", "workMultiplier", "workDivisor"],
+        "title": "Status",
+        "type": "object",
+        "required": [
+          "enabled",
+          "count",
+          "size",
+          "workMultiplier",
+          "workDivisor"
+        ],
         "properties": {
-          "enabled": { "type": "boolean", "description": "Whether the module is enabled on this node." },
-          "count": { "$ref": "#/components/schemas/Hex", "description": "Overall count of messages stored on the board." },
-          "size": { "$ref": "#/components/schemas/Hex", "description": "Overall size of messages stored on the board." },
-          "workMultiplier": { "$ref": "#/components/schemas/Hex", "description": "Factor that increases required work." },
-          "workDivisor": { "$ref": "#/components/schemas/Hex", "description": "Factor that decreases required work." }
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether the module is enabled on this node."
+          },
+          "count": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Overall count of messages stored on the board."
+          },
+          "size": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Overall size of messages stored on the board."
+          },
+          "workMultiplier": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Factor that increases required work."
+          },
+          "workDivisor": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Factor that decreases required work."
+          }
+        }
+      },
+      "Categories": {
+        "title": "Categories",
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/Hex"
         }
       },
-      "Categories": { "title": "Categories", "type": "array", "items": { "$ref": "#/components/schemas/Hex" } },
       "ContentFilter": {
-        "title": "ContentFilter", "type": "object",
+        "title": "ContentFilter",
+        "type": "object",
         "properties": {
-          "category": { "$ref": "#/components/schemas/Hex", "description": "Restrict to one category hash." },
-          "fromBlock": { "$ref": "#/components/schemas/Hex", "description": "Lower block bound (hex quantity)." },
-          "toBlock": { "$ref": "#/components/schemas/Hex", "description": "Upper block bound (hex quantity)." }
+          "category": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Restrict to one category hash."
+          },
+          "fromBlock": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Lower block bound (hex quantity)."
+          },
+          "toBlock": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Upper block bound (hex quantity)."
+          }
         }
       },
       "RPCMessage": {
-        "title": "RPCMessage", "type": "object",
-        "required": ["version", "blockHash", "blockNumber", "category", "data", "nonce", "hash", "workMultiplier", "workDivisor"],
+        "title": "RPCMessage",
+        "type": "object",
+        "required": [
+          "version",
+          "blockHash",
+          "blockNumber",
+          "category",
+          "data",
+          "nonce",
+          "hash",
+          "workMultiplier",
+          "workDivisor"
+        ],
         "properties": {
-          "version": { "$ref": "#/components/schemas/Hex", "description": "Message/encoding version." },
-          "blockHash": { "$ref": "#/components/schemas/Hex", "description": "Hash of the block the message is rooted to." },
-          "blockNumber": { "$ref": "#/components/schemas/Hex", "description": "Number of the block the message is rooted to." },
-          "category": { "$ref": "#/components/schemas/Hex", "description": "32-byte category hash." },
-          "data": { "$ref": "#/components/schemas/Hex", "description": "Arbitrary message data." },
-          "nonce": { "$ref": "#/components/schemas/Hex", "description": "Nonce discovered through proof of work." },
-          "hash": { "$ref": "#/components/schemas/Hex", "description": "The message hash." },
-          "workMultiplier": { "$ref": "#/components/schemas/Hex", "description": "Work multiplier in force when posted." },
-          "workDivisor": { "$ref": "#/components/schemas/Hex", "description": "Work divisor in force when posted." }
+          "version": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Message/encoding version."
+          },
+          "blockHash": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Hash of the block the message is rooted to."
+          },
+          "blockNumber": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Number of the block the message is rooted to."
+          },
+          "category": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "32-byte category hash."
+          },
+          "data": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Arbitrary message data."
+          },
+          "nonce": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Nonce discovered through proof of work."
+          },
+          "hash": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "The message hash."
+          },
+          "workMultiplier": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Work multiplier in force when posted."
+          },
+          "workDivisor": {
+            "$ref": "#/components/schemas/Hex",
+            "description": "Work divisor in force when posted."
+          }
         }
       },
-      "Content": { "title": "Content", "type": "object", "description": "Messages grouped by category hash.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/RPCMessage" } } }
+      "Content": {
+        "title": "Content",
+        "type": "object",
+        "description": "Messages grouped by category hash.",
+        "additionalProperties": {
+          "type": "array",
+          "items": {
+            "$ref": "#/components/schemas/RPCMessage"
+          }
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msgboard/sdk",
-  "version": "0.0.28",
+  "version": "0.0.31",
   "description": "MsgBoard client SDK for the msgboard_ JSON-RPC module",
   "repository": "github:valve-tech/msgboard",
   "author": "MsgBoard",
@@ -14,10 +14,10 @@
   "commonjs": "./dist/index.js",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "require": "./dist/index.js",
-      "default": "./dist/index.js",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.js"
     }
   },
   "keywords": [
@@ -59,7 +59,7 @@
     "vitest": "^3.1.1"
   },
   "dependencies": {
-    "@msgboard/core": "^0.0.1",
+    "@msgboard/core": "^0.0.31",
     "bn.js": "^5.2.1",
     "debug": "^4.4.0",
     "elliptic": "^6.6.1",