README.md

buzz #

Two independent intake paths, one repo. See SPEC.md for the design and ISSUE/ for the plan, decisions and delivery notes.

mqtt/      WS intake: PoW gate -> AEAD -> public MQTT broker -> consumer -> text file
polygon/   on-chain intake: HTML form -> MetaMask tx (pipe record) -> watcher -> text file
  hardhat/ optional isolated Hardhat 3 project (compile/deploy only)
ISSUE/     plan, decisions (D*), open questions, per-feature delivery notes

mqtt path #

npm start                     # serve the PoW page + WS intake (needs POW_KEY, AEAD_KEY)
npm run consumer              # subscribe, decrypt, append OUT_FILE
npm run smoke                 # real round-trip through broker.emqx.io

Config: mqtt/.env.example. PUBLISH=0 disables the broker client. AEAD envelopes authenticate their header (v/kid/seq/ts); upgrade publisher and consumer together (see ISSUE/016-SAST-REMEDIATION.md).

polygon path #

npm run build:contract        # solc 0.8.38 -> polygon/build (gitignored)
npm run e2e                   # PRIVATE_KEY=0x... : deploy on Amoy, submit, watcher writes line
npm run e2e:local             # local Hardhat node -> deploy -> submit -> watcher (one command)
npm run watch                 # BUZZ_ADDRESS=0x... OUT_DIR=chain -> daily text files
                              #   CONFIRMATIONS, CHUNK, BACKFILL/START_BLOCK, MAX_BYTES_PER_DAY
                              #   CHAIN_ID=0x... binds state, POLYGON_RPC_2=... cross-checks logs
npm run form                  # serve the submit form (PORT=3000)
                              #   BUZZ_ADDRESS=0x... CHAIN_ID=0x13882 npm run form

The form is served with a generated config.js and the same validator the watcher uses (polygon/public/format.js). Opening polygon/public/index.html directly does not work in most browsers: file:// blocks ES modules (CORS). For plain static hosting, edit polygon/public/config.js instead of using npm run form.

polygon runbook #

Deploy: run these from polygon/hardhat (details in hardhat path):

npm run deploy:local    # localhost (start `npm run node` first)
PRIVATE_KEY=0x... npm run deploy:amoy
PRIVATE_KEY=0x... npm run deploy:polygon

Watch (from the repo root):

# local
BUZZ_ADDRESS=0x... POLYGON_RPC=http://127.0.0.1:8545 \
CHAIN_ID=0x7a69 CONFIRMATIONS=0 OUT_DIR=chain-local npm run watch

# Amoy
BUZZ_ADDRESS=0x... POLYGON_RPC=https://polygon-amoy-bor-rpc.publicnode.com \
CHAIN_ID=0x13882 OUT_DIR=chain-amoy npm run watch

# mainnet
BUZZ_ADDRESS=0x... CHAIN_ID=0x89 OUT_DIR=chain npm run watch

Form (from the repo root):

# local (MetaMask: add chain 31337, RPC http://127.0.0.1:8545, import a node account)
BUZZ_ADDRESS=0x... CHAIN_ID=0x7a69 PORT=3999 npm run form

# Amoy / mainnet
BUZZ_ADDRESS=0x... CHAIN_ID=0x13882 PORT=3999 npm run form
BUZZ_ADDRESS=0x... CHAIN_ID=0x89 PORT=3999 npm run form

E2E (from the repo root):

# local: starts a Hardhat node on 8545, deploys, submits, runs the watcher, cleans up
npm run e2e:local

# custom record / output directory
RECORD='Bob|instagram|https://example.com/p/1' OUT_DIR=chain-local npm run e2e:local

# Amoy (viem path, not Hardhat; needs polygon/build first)
npm run build:contract
PRIVATE_KEY=0x... AMOY_RPC=https://polygon-amoy-bor-rpc.publicnode.com \
CONFIRMATIONS=1 OUT_DIR=chain-e2e npm run e2e

npm run e2e is Amoy-only; npm run e2e:local is the one-command local loop. It prints the deployed address, the submit tx and the watcher line, then stops the node/watcher.

hardhat path (optional tooling) #

Isolated Hardhat 3 project in polygon/hardhat/ with its own package.json, lockfile and node_modules. polygon/hardhat/contracts is a committed symlink to ../contracts, so the canonical source stays polygon/contracts/Buzz.sol. npm test / npm run e2e do not use this project (npm run e2e:local does); they keep using npm run build:contract (solc -> polygon/build).

# from polygon/hardhat
npm install
npx hardhat compile

PRIVATE_KEY=0x... npm run deploy:amoy      # 80002 / 0x13882
PRIVATE_KEY=0x... npm run deploy:polygon   # 137 / 0x89

npm run node          # localhost (shell 1)
npm run deploy:local  # localhost (shell 2)
network chain ID default RPC
localhost 31337 (0x7a69) http://127.0.0.1:8545
amoy 80002 (0x13882) https://polygon-amoy-bor-rpc.publicnode.com
polygon 137 (0x89) https://polygon-bor-rpc.publicnode.com

Override with AMOY_RPC / POLYGON_RPC. scripts/deploy.ts asks the node for eth_chainId and refuses a mismatch (wrong RPC fails loudly), then prints BUZZ_ADDRESS=0x... and the tx hash. Use that address for npm run watch / npm run form and keep POLYGON_RPC + CHAIN_ID on the same chain.

Amoy gas: https://faucet.polygon.technology. PRIVATE_KEY must be exported — Hardhat 3 does not load .env automatically. artifacts/, cache/, node_modules/ are gitignored. npx hardhat verify is optional and publishes the deployer link; skip it if the anonymity constraint matters. Full details and the config snippet: polygon/hardhat/README.md.

tests #

npm test              # app/unit tests (50)
npm run test:contract # Solidity contract tests (Hardhat node:test, 5)

layout rules #

  • mqtt/ never imports from polygon/, and vice versa. Shared code goes to a new folder only when a second consumer exists.
  • Text dumps are append-only, one line per record, tabs as separators, no JSON wrapper for the polygon path (fields are charset-validated), JSON-encoded body for the MQTT path.