From 6795d476a80e41db0ba18bfe604c450b8eb34fc2 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 18 Aug 2026 19:13:18 +0000 Subject: [PATCH] docs: expand root README with community, contributing, and docs links Add a contribution guide, project mark, social links, and pointers to the spec, NIP, and NDR trees without duplicating those indexes. Co-authored-by: Rastsislau Lipski --- .github/neth-on-dark.svg | 3 ++ CONTRIBUTING.md | 86 +++++++++++++++++++++++++++++++++++ README.md | 96 +++++++++++++++++++++++++++++++++++++--- 3 files changed, 180 insertions(+), 5 deletions(-) create mode 100644 .github/neth-on-dark.svg create mode 100644 CONTRIBUTING.md diff --git a/.github/neth-on-dark.svg b/.github/neth-on-dark.svg new file mode 100644 index 0000000..f8d68cf --- /dev/null +++ b/.github/neth-on-dark.svg @@ -0,0 +1,3 @@ + + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e345447 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# Contributing to Nether + +Thank you for helping improve Nether. This repository is public so the protocol can be inspected. Until Base mainnet relicensing, contributions are welcome as forks and pull requests back here — not as independent products. The legal terms are in [`LICENSE.md`](LICENSE.md). + +By submitting a contribution, you grant the Nether authors a perpetual, worldwide, royalty-free license to use, modify, and distribute it under the current license and, after the planned relicensing, under the MIT License. + +## Source of truth + +1. Follow existing documentation. Do not invent protocol behavior, economics, or process that contradicts it. +2. The primary specification is [`docs/protocol_spec.md`](docs/protocol_spec.md). Treat sections 1–21 as requirements. Section 22 lists what an implementation may and must not change. +3. Sequence implementation from living [Nether Implementation Plans](docs/nip/) (NIPs). NIPs are engineering plans, not protocol rules. The spec wins if they disagree. +4. Document **new** decisions in immutable [Nether Decision Records](docs/ndr/) (NDRs). Do not silently overwrite prior decisions. + +If documentation and code disagree, ask which one is authoritative before “fixing” either. + +Do not guess on protocol economics, invariants, deployment assumptions, public naming, or whether to change existing docs versus recording a new NDR. + +## Repository layout + +The trees are isolated. Do not add a root `package.json` or mix Solidity into the web/keeper trees. + +| Tree | Purpose | Local README | +|---|---|---| +| `contracts/` | Foundry / Solidity | [`contracts/README.md`](contracts/README.md) | +| `apps/web/` | Landing, Learn, docs portal, Grave dashboard | [`apps/web/README.md`](apps/web/README.md) | +| `apps/keeper/` | Gravekeeper cranker | [`apps/keeper/README.md`](apps/keeper/README.md) | +| `docs/` | Spec, NDRs, NIPs | — | + +Clone with `--recurse-submodules`. Contract dependencies live in `contracts/lib/` as git submodules. + +## Development + +Run commands from the tree you are changing. + +**Contracts** (Foundry; default `forge test` excludes `test/fork/**`): + +```text +cd contracts +forge fmt --check +forge build +forge test +``` + +Fork tests need `BASE_RPC_URL`. See [`contracts/README.md`](contracts/README.md) and `contracts/.env.example`. Do not commit RPC URLs, private keys, or mnemonics. + +**Web** (Node 22): + +```text +cd apps/web +npm ci +npm test +npm run dev +``` + +**Keeper** (Node 22): + +```text +cd apps/keeper +npm ci +npm run check +npm test +``` + +## Pull requests + +- Open PRs against `master`. +- Keep the change focused. Do not mix unrelated refactors into a protocol or docs fix. +- Use Conventional Commits in the PR title and commit messages (`feat`, `fix`, `docs`, `chore`, `refactor`, `test`). +- Include tests for behavior you change. Match the style of neighboring tests. +- Run the checks for the trees you touched before asking for review. +- Do not add generated icons or substitute graphics. Use an existing icon pack already in the tree (Lucide on the web app) or ask for an asset. +- Do not include agent attribution in commits, comments, or PR text. + +## Documentation changes + +- Spec sections 1–21 are protocol requirements. Do not reinterpret era math, burial finality, Reaper economics, yield allocation, or other invariants in a “drive-by” PR. +- Edit a NIP when the engineering plan for an in-flight or living workstream needs to change. NIPs may be updated as work proceeds. +- Open a new NDR when the work requires a choice that is not already settled by the spec or an existing NDR and that choice will constrain later work. Copy [`docs/ndr/template.md`](docs/ndr/template.md). Record all considered options, the drivers, the chosen option, and why. +- After an NDR is accepted, do not edit its decision body. Supersede it with a new NDR if the decision must change. +- Do not write an NDR for typos, restoring documented behavior, or dependency bumps with no design choice. + +## Questions + +Use [Discord](https://discord.gg/N9mTHr5VE) for discussion and [X](https://x.com/netherprotocol) for protocol updates. GitHub issues and pull requests are for concrete repository work. + +Agents (and humans following the same workflow) should read [`AGENTS.md`](AGENTS.md) as well. diff --git a/README.md b/README.md index 92de84f..2de5baa 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,98 @@ -# Nether +

+ Nether + Nether +

-Permanently capitalized monetary protocol on Base. Users bury ETH in the Grave and receive NETH. Yield funds the Reaper, which buys and burns NETH. +

Nether

-Spec: [`docs/protocol_spec.md`](docs/protocol_spec.md). Plans: [`docs/nip/`](docs/nip/README.md). Site: [netherprotocol.xyz](https://netherprotocol.xyz/). License: source-available until Base mainnet, then MIT ([`LICENSE.md`](LICENSE.md), [`NDR-0004`](docs/ndr/0004-source-available-until-mainnet.md)). +

+ Permanently capitalized monetary protocol on Base.
+ Bury ETH in the Grave, mint NETH. Yield funds the Reaper, which buys and burns NETH. +

+ +

+ Website + · + Learn + · + Docs + · + Discord + · + X +

+ +

+ contracts + web + keeper +

+ +Nether is a permanently capitalized monetary protocol on Base. You bury ETH into the Grave and receive newly minted NETH according to the current era. Buried ETH becomes permanent protocol capital: it cannot be redeemed by the burier, the team, governance, or the Reaper. + +The Grave deploys that capital into an ETH-denominated yield strategy. Harvestable yield above protected principal goes to the Reaper, which acquires NETH through a protocol-native reverse Dutch auction and burns every token it buys. There is no ETH redemption, no NETH peg, and no guaranteed market price. + +## Documentation + +The protocol spec is the source of truth for monetary behavior. Implementation sequence lives in NIPs. Frozen design choices live in NDRs. If a plan and the spec disagree, the spec wins. + +- Protocol specification: [`docs/protocol_spec.md`](docs/protocol_spec.md) +- Nether Implementation Plans: [`docs/nip/`](docs/nip/) +- Nether Decision Records: [`docs/ndr/`](docs/ndr/) +- Published docs: [netherprotocol.xyz/docs](https://netherprotocol.xyz/docs) +- Learn: [netherprotocol.xyz/learn](https://netherprotocol.xyz/learn) + +## Repository + +The trees are isolated. There is no root `package.json`. Each environment has its own README. ``` contracts/ Solidity (Foundry) -apps/web/ Landing and dashboard -apps/keeper/ Gravekeeper +apps/web/ Landing, Learn, docs portal, and Grave dashboard +apps/keeper/ Gravekeeper cranker docs/ Spec, NDRs, NIPs ``` + +Clone with submodules: + +```text +git clone --recurse-submodules https://github.com/netherprotocol/nether.git +``` + +If you already cloned without them: `git submodule update --init --recursive`. + +| Tree | Stack | Commands | +|---|---|---| +| [`contracts/`](contracts/README.md) | Foundry | `forge fmt --check`, `forge build`, `forge test` | +| [`apps/web/`](apps/web/README.md) | Node 22, Astro | `npm ci`, `npm test`, `npm run dev` | +| [`apps/keeper/`](apps/keeper/README.md) | Node 22, TypeScript | `npm ci`, `npm test`, `npm run check` | + +## Community + +- Discord: [discord.gg/N9mTHr5VE](https://discord.gg/N9mTHr5VE) — questions and discussion +- X: [@netherprotocol](https://x.com/netherprotocol) — protocol updates +- GitHub: [netherprotocol/nether](https://github.com/netherprotocol/nether) — source and pull requests + +## Contributing + +Forks, local builds, and pull requests to this repository are welcome. Independent reuse, live deployments of copies, and redistribution outside that contribution path are not allowed until the planned MIT relicensing after Base mainnet. See [`LICENSE.md`](LICENSE.md) and [`NDR-0004`](docs/ndr/0004-source-available-until-mainnet.md). + +The contribution guide is in [`CONTRIBUTING.md`](CONTRIBUTING.md). In short: + +1. Follow existing docs. Do not invent protocol economics, issuance, or governance. +2. Keep contract, web, and keeper changes in their own trees. +3. Match the tests and formatters already used in that tree. +4. Record new design choices as NDRs. Sequence implementation work in NIPs. Do not silently rewrite accepted NDRs. +5. Use Conventional Commits (`feat`, `fix`, `docs`, `chore`, …). + +Agents contributing to this repository should also follow [`AGENTS.md`](AGENTS.md). + +## License + +Original Nether source is **source-available and proprietary** until successful Base mainnet deployment (protocol spec milestone M2), then MIT. Third-party code in `contracts/lib/` keeps its own licenses. + +See [`LICENSE.md`](LICENSE.md). + +## Disclaimer + +Nether is experimental monetary infrastructure. Burial is irreversible. NETH has no guaranteed price, peg, floor, or redemption value. Capital is at high risk; you may lose some or all of it. The software is provided “as is,” without warranty. Use Nether entirely at your own risk.