- JavaScript 40%
- TypeScript 33%
- HTML 13%
- Solidity 9%
- CSS 3%
- 1 more language 2%
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 frompolygon/, 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.