From 4590bb7cba4b89455a15cba0fa7b709efa5225aa Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:04:10 +0000 Subject: [PATCH 01/13] docs: add Phase 1 shaped docs tree for issue 47 Replace the root README command dump with a thin pointer into docs/. Add STANDARD, Overview, Architecture, and Quickstart shells. Correct the release-build command to make build release=1. Co-authored-by: Tanveer Wahid --- README.md | 76 ++++++-------------------------- docs/ARCHITECTURE.md | 50 ++++++++++++++++++++++ docs/QUICKSTART.md | 52 ++++++++++++++++++++++ docs/README.md | 100 +++++++++++++++++++++++++++++++++++++++++++ docs/STANDARD.md | 85 ++++++++++++++++++++++++++++++++++++ 5 files changed, 301 insertions(+), 62 deletions(-) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/QUICKSTART.md create mode 100644 docs/README.md create mode 100644 docs/STANDARD.md diff --git a/README.md b/README.md index 4b57476..55d7680 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,38 @@ # node-rs -A Rust implementation of KeetaNet node +This repository is a Rust workspace for Keeta Network node crates. -## Development +The toolchain pin is Rust `1.94.0` in `rust-toolchain.toml`. -### Quick Start +## Commands -For first-time setup, simply run: +First-time setup: ```bash make developer ``` -This will: - -- Install Rust (if not already installed) -- Install development tools -- Run initial build and tests - -### Building +Debug build: ```bash -# Debug build make build - -# Release build -make release - -# Check compilation without building -make check -``` - -### Testing - -```bash -# Test defaults with all features -make test - -# Test all features individually from packages with features -make test-feat - -# Test everything -make test-all -``` - -### Code Coverage - -```bash -# Generate HTML coverage report (opens in browser) -make coverage -``` - -### Linting - -```bash -# Format code and run clippy -make do-lint ``` -### Documentation +Release build: ```bash -# Generate documentation and open it -make do-docs +make build release=1 ``` -### Other Commands +Check compilation without a full build: ```bash -# Clean build artifacts -make clean - -# Show all available commands -make help +make check ``` -### CI Commands +## Documentation -```bash -# Generate LCOV coverage report for CI -make coverage-ci - -# Format code and clippy without fixes -make do-lint-ci -``` +- [Overview](docs/README.md) +- [Quickstart](docs/QUICKSTART.md) +- [Architecture](docs/ARCHITECTURE.md) +- [Documentation Standard](docs/STANDARD.md) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..afc8496 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,50 @@ +# Architecture + +## Abstract + +This page names the crate boundaries of the `node-rs` Cargo workspace. A later documentation pass fills the cross-file invariants and the rejected alternatives. This page records the workspace members and the two empty stub crates. + +## Purpose + +An engineer reads this page to name the crates in the workspace. After reading, the engineer can tell which crates are product surfaces and which crates are empty stubs. + +## Related documents + +- [Overview](README.md) for the cultural map and living index. +- [Quickstart](QUICKSTART.md) for install and build. +- [Documentation Standard](STANDARD.md) for page shape and the inclusion test. + +## Workspace + +This repository is a Cargo workspace. Root `Cargo.toml` lists the members under `[workspace].members`. The workspace resolver is `2`. The workspace excludes `keetanetwork-client-wasi/host-tests`. + +The member crates on this tip are `keetanetwork-account`, `keetanetwork-error`, `keetanetwork-crypto`, `keetanetwork-x509`, `keetanetwork-asn1`, `keetanetwork-utils`, `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-ledger`, `keetanetwork-node`, `keetanetwork-client`, `keetanetwork-bindings`, `keetanetwork-client-wasm`, and `keetanetwork-client-wasi`. + +Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. This page does not copy those export lists. + +A later documentation pass fills the crate-boundary invariants, the rejected alternatives, and the enforcement points. + +## Stub crates + +`keetanetwork-node` is an empty stub. `keetanetwork-node/src/lib.rs` holds crate docs only. That file exports no types on this tip. + +`keetanetwork-ledger` is an empty stub. `keetanetwork-ledger/src/lib.rs` holds crate docs only. That file exports no types on this tip. + +This page names those crates as stubs only. + +```mermaid +flowchart LR + workspace_root[root Cargo.toml] + crate_product[product member crates] + crate_node[keetanetwork-node] + crate_ledger[keetanetwork-ledger] + workspace_root --> crate_product + workspace_root --> crate_node + workspace_root --> crate_ledger +``` + +`crate_node` and `crate_ledger` are the stub ids. A later pass may split `crate_product` into one id per member once those invariants have a home. + +## Falsified by + +A change to the workspace `members` or `exclude` lists in root `Cargo.toml`. A change that adds types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md new file mode 100644 index 0000000..929136c --- /dev/null +++ b/docs/QUICKSTART.md @@ -0,0 +1,52 @@ +# Quickstart + +## Abstract + +This page is the install and first-build path for the `node-rs` workspace. It records the Makefile targets a reader uses on this tip. A later pass adds the Packages gate and the first-use snippet. + +## Purpose + +Read this page when you clone the repository or when you need the correct build command. After reading you can set up the toolchain and run a debug or release build. + +## Pin the toolchain + +Use Rust `1.94.0` from `rust-toolchain.toml`. After you clone, that pin wins over a default rustup toolchain. + +The file also requests `rustfmt`, `clippy`, and `llvm-tools-preview`. It also requests the `wasm32-unknown-unknown`, `wasm32-wasip1`, and `wasm32-wasip2` targets. + +## Set up the tree + +Run first-time setup. + +```bash +make developer +``` + +`make developer` installs rustc through `scripts/rustup-init.sh` when rustc is missing. That script requests the `stable` toolchain. The repo pin still selects `1.94.0` for this tree after clone. + +## Build + +Use the Make targets. Use `make build release=1` for a release build. + +| Target | What you get | +| --- | --- | +| `make developer` | First-time toolchain and tool setup | +| `make build` | Debug build through `cargo build` | +| `make build release=1` | Release build through `cargo build --release` | +| `make check` | Compilation check through `cargo check` | + +Release build: + +```bash +make build release=1 +``` + +`make release` runs `scripts/release.sh` and publishes crates. That target is a publish path. It is not a release build. + +## Later install notes + +A later pass adds the GitHub Packages gate, the cargo-only path, the test matrix, and the first-use snippet. Until that pass lands, use `make build` and `make check` on this tree. + +## Falsified by + +A change to the `build`, `check`, `developer`, or `release` targets in `Makefile`. A change to the channel in `rust-toolchain.toml`. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..40bc328 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,100 @@ +# Overview + +## Abstract + +This guide is the cultural map for the `node-rs` workspace. Invariant detail lives on [Architecture](ARCHITECTURE.md). Install and build steps live on [Quickstart](QUICKSTART.md). + +## Purpose + +An engineer reads this guide in the first week on the workspace. After reading, the engineer can name the page that holds each inbound question. The engineer can also find the living documentation map. + +| Next question | The page | +| --- | --- | +| What is always true across crate boundaries? | [Architecture](ARCHITECTURE.md) | +| How does a reader install and build? | [Quickstart](QUICKSTART.md) | +| How does a writer review a page in this tree? | [Documentation Standard](STANDARD.md) | + +## What this workspace is + +This repository is a Cargo workspace of Keeta Network node crates. Root `Cargo.toml` lists the fourteen members. Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. + +`keetanetwork-node` and `keetanetwork-ledger` are empty stubs on this tip. Those crates do not hold product types. [Architecture](ARCHITECTURE.md) names that boundary. + +Each member crate carries its own version in that crate `Cargo.toml`. This guide does not treat the unused workspace package version as the repository version. + +The files state three license strings. Root `LICENSE` is the Keeta Token Network Community License (v1.0). Workspace `Cargo.toml` `license` is `MIT`. `keetanetwork-utils/node-harness/package.json` `license` is `Keeta Token Network Community License`. This guide cites those files as written. + +## How the pieces fit together + +Make owns the build. The [package README](../README.md) and the `Makefile` drive setup, build, check, test, and publish. [Quickstart](QUICKSTART.md) holds the commands. + +Crate rustdoc is the API reference. `make do-docs` generates it. This tree does not copy export lists. + +## Planned concept pages + +A later Architecture draft filters these candidates. A page lands only when it still holds a non-rustdoc invariant. + +| Planned page | Topic the candidate would hold | +| --- | --- | +| `docs/concepts/features-and-no-std.md` | Shared `std` / `alloc` / `der` / `rasn` consumer gates | +| `docs/concepts/accounts.md` | Account identities consumed across crates | +| `docs/concepts/blocks.md` | Block signing and opening-hash rules | +| `docs/concepts/votes.md` | Vote, quote, and staple rules | +| `docs/concepts/certificates.md` | X.509 builders and certificate stores | +| `docs/concepts/client.md` | Client transport and generated HTTP | +| `docs/concepts/bindings.md` | Shared bindings plus wasm and WASI projections | + +Those paths are not living pages until the files exist. + +## Where the tree lives + +| Path | Role | +| --- | --- | +| Root `README.md` | Thin pointer into this tree | +| `docs/README.md` | This overview | +| `docs/STANDARD.md` | Documentation contract | +| `docs/ARCHITECTURE.md` | Crate boundaries and later invariants | +| `docs/QUICKSTART.md` | Install and build procedure | +| `docs/concepts/*` | Single-topic pages that pass the inclusion test | + +GitHub issues and pull requests stay the history home. + +## Day-to-day + +### Tooling + +- The toolchain pin is Rust `1.94.0` in `rust-toolchain.toml`. +- The primary targets are `make developer`, `make build`, `make build release=1`, and `make check`. +- Crate rustdoc opens through `make do-docs`. + +### Where to put work + +| Change | Place | +| --- | --- | +| A crate-boundary invariant | The crate source, then [Architecture](ARCHITECTURE.md) | +| An install or build step | `Makefile`, then [Quickstart](QUICKSTART.md) | +| A documentation page | This tree, then the next-question table on this guide. Writers follow [Documentation Standard](STANDARD.md). | +| A public type contract | rustdoc on that type | + +### First-week reading order + +1. This guide. +2. [Architecture](ARCHITECTURE.md). +3. [Quickstart](QUICKSTART.md). +4. [Documentation Standard](STANDARD.md) before a docs edit. +5. The crate `lib.rs` rustdoc for the crate under change. + +## Cultural one-liners + +- **Make owns the build.** Prefer the `Makefile` targets over raw tool invocations. +- **The toolchain file wins after clone.** `rust-toolchain.toml` selects Rust `1.94.0`. +- **Release build is `make build release=1`.** That target is not `make release`. +- **Stubs stay stubs.** `keetanetwork-node` and `keetanetwork-ledger` have no product types on this tip. +- **rustdoc is the API reference.** This tree holds cross-file contracts. + +## Falsified by + +- A change to the living documentation map that the first-week links follow. +- A change to the workspace `members` list in root `Cargo.toml`. +- A change that adds product types to `keetanetwork-node` or `keetanetwork-ledger`. +- A change to the license strings in root `LICENSE`, workspace `Cargo.toml`, or `keetanetwork-utils/node-harness/package.json`. diff --git a/docs/STANDARD.md b/docs/STANDARD.md new file mode 100644 index 0000000..22b7706 --- /dev/null +++ b/docs/STANDARD.md @@ -0,0 +1,85 @@ +# Documentation Standard + +## Abstract + +This page is the documentation contract for the `node-rs` workspace. It states what belongs in a documentation page. It also fixes the prose, the register, and the page shape. + +## Purpose + +An engineer reads this page before writing or reviewing documentation in this repository. After reading, the engineer can tell whether a page belongs in the tree. The engineer can also write the page in the expected prose and shape. + +## Requirements Language + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here. + +This page is the one home for that declaration. Other pages in this tree MAY use those keywords under this home. They MUST NOT repeat this section. + +## The inclusion test + +Documentation earns its maintenance cost by holding the knowledge that lives outside any one file. A page MUST carry at least one of the following. + +- An invariant that spans several files, which puts it beyond the reach of a single file. +- A decision and the alternative it rejected, so a later reader keeps it closed. +- A contract that binds consumer behavior, such as a feature gate or a signing rule. +- A procedure an operator runs under pressure. + +A page MUST NOT carry the following. The source is the one correct home for each one. + +- Barrel maps, export lists, or directory listings. +- Field tables that repeat crate rustdoc without adding operator semantics. +- One README per workspace crate that only restates that crate `Cargo.toml` and `pub use`. +- A product page for `keetanetwork-node` or `keetanetwork-ledger` while those crates remain empty stubs. +- A decision log, a changelog of past reviews, or a ticket or phase diary. + +One body of knowledge takes one page as its home. A second page that needs it MUST link to that home rather than restate it. The [Overview](README.md) names the living pages. + +A concept page under `docs/concepts/` lands only when it still holds a non-rustdoc invariant after the Architecture draft. A candidate that collapses to a field list MUST NOT land. + +When a page must name a symbol, it cites that symbol as `Symbol` in `path/to/file`. The source carries its own detail. + +## Prose + +A page uses full sentences and keeps their articles. A sentence holds one topic. A sentence does not join independent clauses with a semicolon. Prose uses the active voice and the present tense. + +A page uses the exact technical noun, in code font, on every mention of the same thing. A page uses the ASCII hyphen only and writes each relation as words. A page prefers a table, a list, or a diagram when that form reorganizes substance. + +A page states contracts in the positive. A page names the command or path that is true on this tip. + +Each register addresses its reader differently. A page MUST hold one register throughout. + +| Register | Reader | Voice | +| --- | --- | --- | +| Concept | An engineer building a model of the system | Third person, declarative | +| Implementation | An engineer integrating the software into a service | Second person, imperative | +| Operations | An operator under time pressure | Second person, imperative, one action per step | +| Reference | An engineer checking an exact contract | Third person, terse, declarative | + +## Page shape + +Every page under `docs/**` MUST carry the following sections, in the following order. + +1. **Title.** The subject of the page, as a noun phrase. +2. **Abstract.** Two or three sentences on what the page holds. +3. **Purpose.** Who reads the page, and what they can do afterward. +4. **Body.** The sections that carry the content, which SHOULD sit in the correct dependency order. +5. **Falsified by.** The changes that make the page wrong. + +The closing section is the maintenance contract. It MUST name the code or tree changes that invalidate the page. + +A page SHOULD cite the test or rustdoc example that encodes an invariant when that file is the enforcement point. One citation replaces a prose argument that the guarantee holds. + +The root `README.md` MAY stay a thin pointer. It does not use this page shape. It MUST NOT redeclare Requirements Language. + +Navigation and audience live on the [Overview](README.md). This page MUST NOT carry a page index. + +A Mermaid diagram, when used, MUST give every node and participant an id that is not a Mermaid keyword. Ids such as `crate_account` and `crate_client` stay keyword-safe. A bare id `graph`, `end`, or `subgraph` is invalid. + +## rustdoc comments + +A `///` comment MUST add signal that the signature cannot carry. It MUST NOT narrate the next line. It MUST NOT add a historical aside. Happy-path comments MUST state the contract in the positive. + +Public surfaces that already have rustdoc examples MUST keep a short snippet. Full flows belong as GitHub line links into tests on the branch tip. This tree MUST NOT invent an `examples/` directory. + +## Falsified by + +A change to the prose contract, to the inclusion test, or to the page shape. From 285ce02435bbcc120e86a7c78d2865a034679453 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:08:32 +0000 Subject: [PATCH 02/13] docs: fill Phase 2 Quickstart and Architecture substance Record Makefile test, wasm, WASI, and rustdoc targets. State the GitHub Packages gate and the cargo-only path. Cite KeetaClient and BlockBuilder rustdoc examples. Expand crate-boundary contracts and rejected alternatives. Drop unfilled concept pages from the Overview living map. Co-authored-by: Tanveer Wahid --- docs/ARCHITECTURE.md | 93 ++++++++++++++++++++++++++++++++++++-------- docs/QUICKSTART.md | 88 +++++++++++++++++++++++++++++++++++++---- docs/README.md | 26 ++++--------- 3 files changed, 164 insertions(+), 43 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index afc8496..6f2c17d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,16 +2,16 @@ ## Abstract -This page names the crate boundaries of the `node-rs` Cargo workspace. A later documentation pass fills the cross-file invariants and the rejected alternatives. This page records the workspace members and the two empty stub crates. +This page names the crate boundaries of the `node-rs` Cargo workspace. It states the cross-file contracts that a single crate rustdoc page cannot hold. It also names the two empty stub crates and the alternatives this tree rejects. ## Purpose -An engineer reads this page to name the crates in the workspace. After reading, the engineer can tell which crates are product surfaces and which crates are empty stubs. +An engineer reads this page to name the crates in the workspace and the invariants that span them. After reading, the engineer can tell which crates are product surfaces, which crates are empty stubs, and which page or source file owns each contract. ## Related documents - [Overview](README.md) for the cultural map and living index. -- [Quickstart](QUICKSTART.md) for install and build. +- [Quickstart](QUICKSTART.md) for install, build, test, and first use. - [Documentation Standard](STANDARD.md) for page shape and the inclusion test. ## Workspace @@ -20,9 +20,69 @@ This repository is a Cargo workspace. Root `Cargo.toml` lists the members under The member crates on this tip are `keetanetwork-account`, `keetanetwork-error`, `keetanetwork-crypto`, `keetanetwork-x509`, `keetanetwork-asn1`, `keetanetwork-utils`, `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-ledger`, `keetanetwork-node`, `keetanetwork-client`, `keetanetwork-bindings`, `keetanetwork-client-wasm`, and `keetanetwork-client-wasi`. -Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. This page does not copy those export lists. +Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. This page does not copy those export lists. Each member crate carries its own version in that crate `Cargo.toml`. -A later documentation pass fills the crate-boundary invariants, the rejected alternatives, and the enforcement points. +## Crate-boundary map + +Account identities flow into block, vote, x509, client, and bindings. The client re-exports vote types for callers. Bindings project the same core into wasm and WASI. + +```mermaid +flowchart LR + crate_account[keetanetwork-account] + crate_block[keetanetwork-block] + crate_vote[keetanetwork-vote] + crate_x509[keetanetwork-x509] + crate_client[keetanetwork-client] + crate_bindings[keetanetwork-bindings] + crate_wasm[keetanetwork-client-wasm] + crate_wasi[keetanetwork-client-wasi] + crate_node[keetanetwork-node] + crate_ledger[keetanetwork-ledger] + crate_account --> crate_block + crate_account --> crate_vote + crate_account --> crate_x509 + crate_account --> crate_client + crate_account --> crate_bindings + crate_block --> crate_vote + crate_block --> crate_client + crate_vote --> crate_client + crate_client --> crate_wasm + crate_client --> crate_wasi + crate_bindings --> crate_wasm + crate_bindings --> crate_wasi +``` + +`crate_node` and `crate_ledger` sit in the workspace with no product types. The arrows follow member `Cargo.toml` dependencies on this tip. The `crate_client` to `crate_wasi` arrow is the `p2` feature. Feature `p1` stays on the pure surface. + +## Cross-file contracts + +These statements hold across crates. rustdoc on each type remains the field reference. + +### Identities + +`keetanetwork-account` owns `Account`, `GenericAccount`, `KeyPairType`, and identifier accounts. `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, `keetanetwork-client`, and `keetanetwork-bindings` consume those identities. `CertSigner` and `CertVerifier` live on the account crate. Certificate builders and stores live in `keetanetwork-x509`. + +### Feature gates + +Workspace crates share `std`, `alloc`, `der`, and `rasn` feature names. `keetanetwork-asn1/src/lib.rs` fails the build when neither `der` nor `rasn` is on. That `compile_error!` requires at least one of those features. Both features may be on together. + +`keetanetwork-client` feature `http` requires a runtime. Native builds enable `std`. Browser builds enable `wasm` on `wasm32-unknown-unknown`. The crate `compile_error!` states that pairing. + +### Blocks and votes + +`Block`, `BlockBuilder`, `Operation`, and `AccountRef` live in `keetanetwork-block`. Opening-hash and signing rules span that crate and the client builder. The rustdoc example in `keetanetwork-block/src/lib.rs` shows `as_opening` and `sign`. + +`Vote`, `VoteQuote`, `VoteStaple`, and `PossiblyExpiredVote` live in `keetanetwork-vote`. A quote is a non-binding vote used during fee negotiation. A staple is the compressed bundle of votes and the blocks they cover. `keetanetwork-client` re-exports `Vote`, `VoteQuote`, and `VoteStaple`. + +### Client transport + +`KeetaClient`, `UserClient`, and `TransactionBuilder` live in `keetanetwork-client`. HTTP transport is generated at build time from `keetanetwork-client/openapi/keetanet-node.yaml` through progenitor. The generated types are exposed as the `generated` module when the `codec` feature is on. + +The rustdoc example in `keetanetwork-client/src/lib.rs` constructs `KeetaClient::new("http://localhost:8080/api")`. [Quickstart](QUICKSTART.md) cites that example. + +### Bindings + +`keetanetwork-bindings` is the shared, target-agnostic projection. `keetanetwork-client-wasm` is the browser ABI. Amounts are decimal strings. Errors carry `error.code`. `keetanetwork-client-wasi` selects exactly one of `p1` or `p2` on a WASI target. Both features on, or neither feature on, fail that crate `compile_error!`. ## Stub crates @@ -32,19 +92,18 @@ A later documentation pass fills the crate-boundary invariants, the rejected alt This page names those crates as stubs only. -```mermaid -flowchart LR - workspace_root[root Cargo.toml] - crate_product[product member crates] - crate_node[keetanetwork-node] - crate_ledger[keetanetwork-ledger] - workspace_root --> crate_product - workspace_root --> crate_node - workspace_root --> crate_ledger -``` +## Rejected alternatives + +These decisions stay closed. A later change that reopens one is a migration. -`crate_node` and `crate_ledger` are the stub ids. A later pass may split `crate_product` into one id per member once those invariants have a home. +| Decision | Rejected alternative | Why the alternative lost | +| --- | --- | --- | +| Crate identity lives in each `Cargo.toml` plus rustdoc | One README barrel per member crate | A barrel restates `pub use` and fails the inclusion test | +| Examples stay in crate rustdoc and tests | An `examples/` directory | No such directory exists on this tip. Scope keeps examples in-crate | +| Architecture names node and ledger as stubs | A node or ledger product page | Those `lib.rs` files export no types | +| Quickstart holds the PAT and Packages fact | Revival of branch `docs/add_pat_instructions` | That branch is stale and still taught `make release` as a release build | +| License strings are cited as the files write them | A docs-only license reconcile | Overview cites the three file strings. This tree does not edit `LICENSE` | ## Falsified by -A change to the workspace `members` or `exclude` lists in root `Cargo.toml`. A change that adds types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. +A change to the workspace `members` or `exclude` lists in root `Cargo.toml`. A change that adds types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. A change to the `compile_error!` in `keetanetwork-asn1/src/lib.rs`, `keetanetwork-client/src/lib.rs` feature `http`, or `keetanetwork-client-wasi/src/lib.rs` `p1` / `p2`. A change to the OpenAPI path `keetanetwork-client/openapi/keetanet-node.yaml` or to the client `generated` module gate. diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 929136c..f6d16a0 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -2,11 +2,11 @@ ## Abstract -This page is the install and first-build path for the `node-rs` workspace. It records the Makefile targets a reader uses on this tip. A later pass adds the Packages gate and the first-use snippet. +This page is the install, build, test, and first-use path for the `node-rs` workspace. It records the Makefile targets that are true on this tip. It also states the GitHub Packages gate and the cargo-only path. ## Purpose -Read this page when you clone the repository or when you need the correct build command. After reading you can set up the toolchain and run a debug or release build. +Read this page when you clone the repository or when you need a correct Make command. After reading you can set up the toolchain and run a debug or release build. You can also choose a test path and start from an existing rustdoc example. ## Pin the toolchain @@ -22,7 +22,7 @@ Run first-time setup. make developer ``` -`make developer` installs rustc through `scripts/rustup-init.sh` when rustc is missing. That script requests the `stable` toolchain. The repo pin still selects `1.94.0` for this tree after clone. +`make developer` installs rustc through `scripts/rustup-init.sh -y --default-toolchain stable` when rustc is missing. That script requests the `stable` toolchain. The repo pin still selects `1.94.0` for this tree after clone. ## Build @@ -41,12 +41,86 @@ Release build: make build release=1 ``` -`make release` runs `scripts/release.sh` and publishes crates. That target is a publish path. It is not a release build. +`make release` runs `scripts/release.sh` and publishes crates to crates.io. That target is a publish path. It is not a release build. -## Later install notes +## Test -A later pass adds the GitHub Packages gate, the cargo-only path, the test matrix, and the first-use snippet. Until that pass lands, use `make build` and `make check` on this tree. +`make test` depends on `make node-harness`. It then runs `cargo test --all-features --workspace`. + +| Target | What you get | +| --- | --- | +| `make test` | Harness build, then workspace tests with all features | +| `make test-feat` | Feature matrix from the `Makefile` `test-feat` recipe | +| `make test-all` | `make test` and then `make test-feat` | + +Those targets need the Packages gate below. Use the cargo-only path when you lack Packages read. + +## Wasm and WASI + +Name these targets when you need those ABIs. They also need the Packages gate. The Make targets are the first-use path for those ABIs. + +| Target | What you get | +| --- | --- | +| `make build-wasm` | `wasm-pack build` for `keetanetwork-client-wasm` | +| `make test-wasm` | Harness, wasm-pack node tests, and Playwright in `keetanetwork-client-wasm/tests` | +| `make build-wasi` | WASI P1 and P2 debug artifacts for `keetanetwork-client-wasi` | +| `make test-wasi` | Harness, WASI artifacts, and host tests under `keetanetwork-client-wasi/host-tests` | + +`make test-wasi` selects `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. [Architecture](ARCHITECTURE.md) holds that one-feature contract. + +## rustdoc + +| Target | What you get | +| --- | --- | +| `make do-docs` | `cargo doc` for the workspace, then opens the result | +| `make do-docs-ci` | The same rustdoc build without opening a browser | + +## GitHub Packages gate + +`keetanetwork-utils/node-harness/.npmrc` sets `@keetanetwork:registry=https://npm.pkg.github.com`. The harness `package.json` depends on `@keetanetwork/keetanet-node` from that registry. + +`make node-harness`, `make test`, `make test-all`, `make test-wasm`, and `make test-wasi` need read access to that package. CI sets `NODE_AUTH_TOKEN` for those jobs in `.github/workflows/ci.yml`. + +Set `NODE_AUTH_TOKEN` or `GITHUB_TOKEN` to a GitHub personal access token with `read:packages`. Authorize SSO for the organization when the organization requires it. + +Rust crates in this workspace use path dependencies. `.cargo/config.toml` sets a `wasm32-unknown-unknown` `getrandom` cfg. It does not set a private Cargo registry. + +## Cargo-only path + +Skip the harness when you do not have Packages read. + +```bash +cargo check +cargo build +``` + +You can also run crate tests that do not enable the `node-harness` feature. `make test` still needs the harness and auth. + +## First use + +Start from the rustdoc examples that already live in the crates. This tree does not add an `examples/` directory. + +Construct a `KeetaClient` against the local API from [`keetanetwork-client/src/lib.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-client/src/lib.rs#L11-L37). + +```rust +let client = KeetaClient::new("http://localhost:8080/api").with_network(0u8); +``` + +`UserClient` signing tests live in [`keetanetwork-client/tests/user_signing.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-client/tests/user_signing.rs#L8-L20). A live harness cookbook lives in [`keetanetwork-client/tests/e2e.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-client/tests/e2e.rs#L164). + +Build a signed opening block from [`keetanetwork-block/src/lib.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-block/src/lib.rs#L8-L39). + +```rust +let unsigned = BlockBuilder::default() + .with_network(0u8) + .with_account(account.clone()) + .as_opening() + .build()?; +let block = unsigned.sign()?; +``` + +A harness opening-block cookbook lives in [`keetanetwork-block/tests/e2e.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-block/tests/e2e.rs#L116-L119). ## Falsified by -A change to the `build`, `check`, `developer`, or `release` targets in `Makefile`. A change to the channel in `rust-toolchain.toml`. +A change to the `developer`, `build`, `check`, `test`, `test-feat`, `test-all`, `build-wasm`, `test-wasm`, `build-wasi`, `test-wasi`, `do-docs`, `do-docs-ci`, or `release` targets in `Makefile`. A change to the channel in `rust-toolchain.toml`. A change to the registry line in `keetanetwork-utils/node-harness/.npmrc`. A change to the `KeetaClient` or `BlockBuilder` rustdoc examples in those crate `lib.rs` files. diff --git a/docs/README.md b/docs/README.md index 40bc328..896e973 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ ## Abstract -This guide is the cultural map for the `node-rs` workspace. Invariant detail lives on [Architecture](ARCHITECTURE.md). Install and build steps live on [Quickstart](QUICKSTART.md). +This guide is the cultural map for the `node-rs` workspace. Invariant detail lives on [Architecture](ARCHITECTURE.md). Install, build, and test steps live on [Quickstart](QUICKSTART.md). ## Purpose @@ -11,7 +11,7 @@ An engineer reads this guide in the first week on the workspace. After reading, | Next question | The page | | --- | --- | | What is always true across crate boundaries? | [Architecture](ARCHITECTURE.md) | -| How does a reader install and build? | [Quickstart](QUICKSTART.md) | +| How does a reader install, build, and test? | [Quickstart](QUICKSTART.md) | | How does a writer review a page in this tree? | [Documentation Standard](STANDARD.md) | ## What this workspace is @@ -30,21 +30,7 @@ Make owns the build. The [package README](../README.md) and the `Makefile` drive Crate rustdoc is the API reference. `make do-docs` generates it. This tree does not copy export lists. -## Planned concept pages - -A later Architecture draft filters these candidates. A page lands only when it still holds a non-rustdoc invariant. - -| Planned page | Topic the candidate would hold | -| --- | --- | -| `docs/concepts/features-and-no-std.md` | Shared `std` / `alloc` / `der` / `rasn` consumer gates | -| `docs/concepts/accounts.md` | Account identities consumed across crates | -| `docs/concepts/blocks.md` | Block signing and opening-hash rules | -| `docs/concepts/votes.md` | Vote, quote, and staple rules | -| `docs/concepts/certificates.md` | X.509 builders and certificate stores | -| `docs/concepts/client.md` | Client transport and generated HTTP | -| `docs/concepts/bindings.md` | Shared bindings plus wasm and WASI projections | - -Those paths are not living pages until the files exist. +[Architecture](ARCHITECTURE.md) holds the crate-boundary contracts. Feature gates, identity consumption, client generation, and binding ABIs live there. A `docs/concepts/` page lands only when it still holds a non-rustdoc invariant that Architecture does not already carry. ## Where the tree lives @@ -53,8 +39,8 @@ Those paths are not living pages until the files exist. | Root `README.md` | Thin pointer into this tree | | `docs/README.md` | This overview | | `docs/STANDARD.md` | Documentation contract | -| `docs/ARCHITECTURE.md` | Crate boundaries and later invariants | -| `docs/QUICKSTART.md` | Install and build procedure | +| `docs/ARCHITECTURE.md` | Crate boundaries and cross-file contracts | +| `docs/QUICKSTART.md` | Install, build, test, and first use | | `docs/concepts/*` | Single-topic pages that pass the inclusion test | GitHub issues and pull requests stay the history home. @@ -65,6 +51,7 @@ GitHub issues and pull requests stay the history home. - The toolchain pin is Rust `1.94.0` in `rust-toolchain.toml`. - The primary targets are `make developer`, `make build`, `make build release=1`, and `make check`. +- `make test` and the wasm or WASI test targets need GitHub Packages read. [Quickstart](QUICKSTART.md) holds the cargo-only path. - Crate rustdoc opens through `make do-docs`. ### Where to put work @@ -91,6 +78,7 @@ GitHub issues and pull requests stay the history home. - **Release build is `make build release=1`.** That target is not `make release`. - **Stubs stay stubs.** `keetanetwork-node` and `keetanetwork-ledger` have no product types on this tip. - **rustdoc is the API reference.** This tree holds cross-file contracts. +- **Packages read is a test gate.** `cargo check` and `cargo build` stay open without it. ## Falsified by From e34666e6693eca47d587b48172fd5058e607e019 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:08:42 +0000 Subject: [PATCH 03/13] docs: pin Quickstart example links to branch tip Point KeetaClient and BlockBuilder GitHub line links at the Phase 2 substance commit so the citations follow this branch tip. Co-authored-by: Tanveer Wahid --- docs/QUICKSTART.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index f6d16a0..d60111a 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -100,15 +100,15 @@ You can also run crate tests that do not enable the `node-harness` feature. `mak Start from the rustdoc examples that already live in the crates. This tree does not add an `examples/` directory. -Construct a `KeetaClient` against the local API from [`keetanetwork-client/src/lib.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-client/src/lib.rs#L11-L37). +Construct a `KeetaClient` against the local API from [`keetanetwork-client/src/lib.rs`](https://github.com/KeetaNetwork/node-rs/blob/285ce02435bbcc120e86a7c78d2865a034679453/keetanetwork-client/src/lib.rs#L11-L37). ```rust let client = KeetaClient::new("http://localhost:8080/api").with_network(0u8); ``` -`UserClient` signing tests live in [`keetanetwork-client/tests/user_signing.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-client/tests/user_signing.rs#L8-L20). A live harness cookbook lives in [`keetanetwork-client/tests/e2e.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-client/tests/e2e.rs#L164). +`UserClient` signing tests live in [`keetanetwork-client/tests/user_signing.rs`](https://github.com/KeetaNetwork/node-rs/blob/285ce02435bbcc120e86a7c78d2865a034679453/keetanetwork-client/tests/user_signing.rs#L8-L20). A live harness cookbook lives in [`keetanetwork-client/tests/e2e.rs`](https://github.com/KeetaNetwork/node-rs/blob/285ce02435bbcc120e86a7c78d2865a034679453/keetanetwork-client/tests/e2e.rs#L164). -Build a signed opening block from [`keetanetwork-block/src/lib.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-block/src/lib.rs#L8-L39). +Build a signed opening block from [`keetanetwork-block/src/lib.rs`](https://github.com/KeetaNetwork/node-rs/blob/285ce02435bbcc120e86a7c78d2865a034679453/keetanetwork-block/src/lib.rs#L8-L39). ```rust let unsigned = BlockBuilder::default() @@ -119,7 +119,7 @@ let unsigned = BlockBuilder::default() let block = unsigned.sign()?; ``` -A harness opening-block cookbook lives in [`keetanetwork-block/tests/e2e.rs`](https://github.com/KeetaNetwork/node-rs/blob/4590bb7cba4b89455a15cba0fa7b709efa5225aa/keetanetwork-block/tests/e2e.rs#L116-L119). +A harness opening-block cookbook lives in [`keetanetwork-block/tests/e2e.rs`](https://github.com/KeetaNetwork/node-rs/blob/285ce02435bbcc120e86a7c78d2865a034679453/keetanetwork-block/tests/e2e.rs#L116-L119). ## Falsified by From eb68369207c50f0df3c782f37db2953003990929 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:11:57 +0000 Subject: [PATCH 04/13] docs(rustdoc): A7 public-surface rustdoc on shaped items Restate asn1 der/rasn as at-least-one to match compile_error!. Keep existing KeetaClient and BlockBuilder examples and add GitHub line links into e2e and user_signing tests. Name Architecture account identities on the account crate rustdoc. Co-authored-by: Tanveer Wahid --- keetanetwork-account/src/lib.rs | 7 +++++++ keetanetwork-asn1/src/lib.rs | 3 ++- keetanetwork-block/src/lib.rs | 3 +++ keetanetwork-client/src/lib.rs | 5 +++++ 4 files changed, 17 insertions(+), 1 deletion(-) diff --git a/keetanetwork-account/src/lib.rs b/keetanetwork-account/src/lib.rs index 9476991..ee52b77 100644 --- a/keetanetwork-account/src/lib.rs +++ b/keetanetwork-account/src/lib.rs @@ -1,4 +1,11 @@ //! Account management and cryptographic identities for Keetanetwork. +//! +//! [`Account`] is the typed identity bound to one [`KeyPairType`]. +//! [`GenericAccount`] is the type-erased account used at crate boundaries. +//! [`KeyPairType`] names signing algorithms and identifier accounts. +//! [`CertSigner`] signs X.509-shaped artifacts in certificate mode. +//! [`CertVerifier`] verifies those certificate-mode signatures. +//! Block, vote, x509, client, and bindings crates consume these identities. #![cfg_attr(not(feature = "std"), no_std)] diff --git a/keetanetwork-asn1/src/lib.rs b/keetanetwork-asn1/src/lib.rs index 5be7232..c07ef87 100644 --- a/keetanetwork-asn1/src/lib.rs +++ b/keetanetwork-asn1/src/lib.rs @@ -11,7 +11,8 @@ //! - `rasn` - Use the `rasn` crate for ASN.1 handling //! - `serde` - Enable serde serialization support //! -//! Exactly one of `der` or `rasn` must be enabled. +//! Enable at least one of the `der` and `rasn` features. +//! Both features may be on together. #![cfg_attr(not(feature = "std"), no_std)] diff --git a/keetanetwork-block/src/lib.rs b/keetanetwork-block/src/lib.rs index b2dd31c..b26d700 100644 --- a/keetanetwork-block/src/lib.rs +++ b/keetanetwork-block/src/lib.rs @@ -37,6 +37,9 @@ //! assert_eq!(decoded.hash(), block.hash()); //! # Ok::<(), keetanetwork_block::BlockError>(()) //! ``` +//! +//! A live harness cookbook lives in +//! [keetanetwork-block/tests/e2e.rs](https://github.com/KeetaNetwork/node-rs/blob/e34666e6693eca47d587b48172fd5058e607e019/keetanetwork-block/tests/e2e.rs#L116-L124). #![cfg_attr(not(feature = "std"), no_std)] diff --git a/keetanetwork-client/src/lib.rs b/keetanetwork-client/src/lib.rs index 2af1ef9..6ba8329 100644 --- a/keetanetwork-client/src/lib.rs +++ b/keetanetwork-client/src/lib.rs @@ -36,6 +36,11 @@ //! # } //! ``` //! +//! A live harness cookbook lives in +//! [keetanetwork-client/tests/e2e.rs](https://github.com/KeetaNetwork/node-rs/blob/e34666e6693eca47d587b48172fd5058e607e019/keetanetwork-client/tests/e2e.rs#L164). +//! `UserClient` signing tests live in +//! [keetanetwork-client/tests/user_signing.rs](https://github.com/KeetaNetwork/node-rs/blob/e34666e6693eca47d587b48172fd5058e607e019/keetanetwork-client/tests/user_signing.rs#L15-L20). +//! //! ## `no_std` //! //! The orchestrator ([`KeetaClient`]) is `no_std`+`alloc`: it is written From 861cc10b959b7230a973cc76e4c4358c8119719a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:13:26 +0000 Subject: [PATCH 05/13] docs: cut Architecture inventory and edge Mermaid Replace the member roster and Cargo.toml-edge diagram with split forces, illegal states, SSOT homes, and rejected alternatives. Soften Overview so it does not become a second roster. Co-authored-by: Tanveer Wahid --- docs/ARCHITECTURE.md | 106 ++++++++++++++----------------------------- docs/README.md | 6 +-- 2 files changed, 37 insertions(+), 75 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6f2c17d..65a4f16 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,95 +2,57 @@ ## Abstract -This page names the crate boundaries of the `node-rs` Cargo workspace. It states the cross-file contracts that a single crate rustdoc page cannot hold. It also names the two empty stub crates and the alternatives this tree rejects. +This page states how the `node-rs` workspace is split and which states the tree forbids. Crate rustdoc and each `Cargo.toml` remain the field and dependency references. This page does not inventory members. ## Purpose -An engineer reads this page to name the crates in the workspace and the invariants that span them. After reading, the engineer can tell which crates are product surfaces, which crates are empty stubs, and which page or source file owns each contract. +An engineer reads this page to learn why crates exist as separate packages and which combinations are illegal. After reading, the engineer knows where a cross-cutting contract lives and which alternatives stay closed. ## Related documents - [Overview](README.md) for the cultural map and living index. - [Quickstart](QUICKSTART.md) for install, build, test, and first use. -- [Documentation Standard](STANDARD.md) for page shape and the inclusion test. +- [Documentation Standard](STANDARD.md) for the inclusion test and page shape. -## Workspace +## Why the workspace splits -This repository is a Cargo workspace. Root `Cargo.toml` lists the members under `[workspace].members`. The workspace resolver is `2`. The workspace excludes `keetanetwork-client-wasi/host-tests`. +The workspace separates four kinds of packages so each kind can change without forcing the others to move. -The member crates on this tip are `keetanetwork-account`, `keetanetwork-error`, `keetanetwork-crypto`, `keetanetwork-x509`, `keetanetwork-asn1`, `keetanetwork-utils`, `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-ledger`, `keetanetwork-node`, `keetanetwork-client`, `keetanetwork-bindings`, `keetanetwork-client-wasm`, and `keetanetwork-client-wasi`. - -Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. This page does not copy those export lists. Each member crate carries its own version in that crate `Cargo.toml`. - -## Crate-boundary map - -Account identities flow into block, vote, x509, client, and bindings. The client re-exports vote types for callers. Bindings project the same core into wasm and WASI. - -```mermaid -flowchart LR - crate_account[keetanetwork-account] - crate_block[keetanetwork-block] - crate_vote[keetanetwork-vote] - crate_x509[keetanetwork-x509] - crate_client[keetanetwork-client] - crate_bindings[keetanetwork-bindings] - crate_wasm[keetanetwork-client-wasm] - crate_wasi[keetanetwork-client-wasi] - crate_node[keetanetwork-node] - crate_ledger[keetanetwork-ledger] - crate_account --> crate_block - crate_account --> crate_vote - crate_account --> crate_x509 - crate_account --> crate_client - crate_account --> crate_bindings - crate_block --> crate_vote - crate_block --> crate_client - crate_vote --> crate_client - crate_client --> crate_wasm - crate_client --> crate_wasi - crate_bindings --> crate_wasm - crate_bindings --> crate_wasi -``` - -`crate_node` and `crate_ledger` sit in the workspace with no product types. The arrows follow member `Cargo.toml` dependencies on this tip. The `crate_client` to `crate_wasi` arrow is the `p2` feature. Feature `p1` stays on the pure surface. - -## Cross-file contracts - -These statements hold across crates. rustdoc on each type remains the field reference. - -### Identities - -`keetanetwork-account` owns `Account`, `GenericAccount`, `KeyPairType`, and identifier accounts. `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, `keetanetwork-client`, and `keetanetwork-bindings` consume those identities. `CertSigner` and `CertVerifier` live on the account crate. Certificate builders and stores live in `keetanetwork-x509`. - -### Feature gates - -Workspace crates share `std`, `alloc`, `der`, and `rasn` feature names. `keetanetwork-asn1/src/lib.rs` fails the build when neither `der` nor `rasn` is on. That `compile_error!` requires at least one of those features. Both features may be on together. - -`keetanetwork-client` feature `http` requires a runtime. Native builds enable `std`. Browser builds enable `wasm` on `wasm32-unknown-unknown`. The crate `compile_error!` states that pairing. - -### Blocks and votes - -`Block`, `BlockBuilder`, `Operation`, and `AccountRef` live in `keetanetwork-block`. Opening-hash and signing rules span that crate and the client builder. The rustdoc example in `keetanetwork-block/src/lib.rs` shows `as_opening` and `sign`. - -`Vote`, `VoteQuote`, `VoteStaple`, and `PossiblyExpiredVote` live in `keetanetwork-vote`. A quote is a non-binding vote used during fee negotiation. A staple is the compressed bundle of votes and the blocks they cover. `keetanetwork-client` re-exports `Vote`, `VoteQuote`, and `VoteStaple`. - -### Client transport +| Kind | Force that keeps it separate | Examples of the role | +| --- | --- | --- | +| Primitives and codecs | Shared encoding and crypto must stay usable under `no_std` / `alloc` feature matrices | `keetanetwork-crypto`, `keetanetwork-asn1`, `keetanetwork-error`, `keetanetwork-utils` | +| Domain identity and certificates | Account and X.509 rules are consumed by many higher crates | `keetanetwork-account`, `keetanetwork-x509` | +| Ledger domain objects | Block and vote rules are the signed objects the network exchanges | `keetanetwork-block`, `keetanetwork-vote` | +| Client and ABI projections | HTTP generation and host ABIs change on a different cadence than domain types | `keetanetwork-client`, `keetanetwork-bindings`, `keetanetwork-client-wasm`, `keetanetwork-client-wasi` | -`KeetaClient`, `UserClient`, and `TransactionBuilder` live in `keetanetwork-client`. HTTP transport is generated at build time from `keetanetwork-client/openapi/keetanet-node.yaml` through progenitor. The generated types are exposed as the `generated` module when the `codec` feature is on. +`keetanetwork-node` and `keetanetwork-ledger` keep reserved crate names in the workspace. Their `lib.rs` files export no types on this tip. They are placeholders, not product surfaces. -The rustdoc example in `keetanetwork-client/src/lib.rs` constructs `KeetaClient::new("http://localhost:8080/api")`. [Quickstart](QUICKSTART.md) cites that example. +Crate identity, versions, and dependency edges live in each member `Cargo.toml` and in rustdoc. This page does not restate those lists. -### Bindings +## Illegal states -`keetanetwork-bindings` is the shared, target-agnostic projection. `keetanetwork-client-wasm` is the browser ABI. Amounts are decimal strings. Errors carry `error.code`. `keetanetwork-client-wasi` selects exactly one of `p1` or `p2` on a WASI target. Both features on, or neither feature on, fail that crate `compile_error!`. +These combinations are forbidden on this tip. The build or the documentation contract rejects them. -## Stub crates +| Illegal state | Where it fails | Legal alternative | +| --- | --- | --- | +| Treat `keetanetwork-node` or `keetanetwork-ledger` as a product API | Those `lib.rs` files export no types. This page names them as stubs only | Implement types in those crates first, then document them | +| Build `keetanetwork-asn1` with neither `der` nor `rasn` | `compile_error!` in `keetanetwork-asn1/src/lib.rs` | Enable at least one of `der` or `rasn`. Both may be on together | +| Enable client feature `http` without a runtime | `compile_error!` in `keetanetwork-client/src/lib.rs` | Pair `http` with `std` on native targets, or with `wasm` on `wasm32-unknown-unknown` | +| Enable both or neither of WASI features `p1` and `p2` on `keetanetwork-client-wasi` | `compile_error!` in `keetanetwork-client-wasi/src/lib.rs` | Select exactly one of `p1` or `p2` per WASI build | +| Add a per-crate README that only restates `pub use` | Inclusion test on [Documentation Standard](STANDARD.md) | Keep identity in `Cargo.toml` description plus rustdoc | -`keetanetwork-node` is an empty stub. `keetanetwork-node/src/lib.rs` holds crate docs only. That file exports no types on this tip. +## SSOT homes for cross-cutting contracts -`keetanetwork-ledger` is an empty stub. `keetanetwork-ledger/src/lib.rs` holds crate docs only. That file exports no types on this tip. +Each row is one body of knowledge. Other pages link here or to the named source. They do not restate field lists. -This page names those crates as stubs only. +| Contract | Home | +| --- | --- | +| Account and identifier identity consumed across crates | `keetanetwork-account` rustdoc. Higher crates consume those types | +| Certificate signing and verification traits versus X.509 builders | Traits on `keetanetwork-account`. Builders and stores in `keetanetwork-x509` | +| Block opening-hash and signing rules | `keetanetwork-block` rustdoc and tests. The client builder uses the same rules | +| Vote versus quote versus staple | `keetanetwork-vote` rustdoc. The client re-exports the consumer-facing vote types | +| HTTP transport shape | `keetanetwork-client/openapi/keetanet-node.yaml` generated through progenitor into the client `generated` module | +| Browser and WASI ABIs | `keetanetwork-bindings` as the shared projection. Wasm amounts are decimal strings and errors carry `error.code`. WASI selects exactly one of `p1` or `p2` | ## Rejected alternatives @@ -102,8 +64,8 @@ These decisions stay closed. A later change that reopens one is a migration. | Examples stay in crate rustdoc and tests | An `examples/` directory | No such directory exists on this tip. Scope keeps examples in-crate | | Architecture names node and ledger as stubs | A node or ledger product page | Those `lib.rs` files export no types | | Quickstart holds the PAT and Packages fact | Revival of branch `docs/add_pat_instructions` | That branch is stale and still taught `make release` as a release build | -| License strings are cited as the files write them | A docs-only license reconcile | Overview cites the three file strings. This tree does not edit `LICENSE` | +| Architecture explains forces and illegal states | A member roster or a Mermaid copy of `Cargo.toml` edges | Rosters and edge copies go stale without teaching structure | ## Falsified by -A change to the workspace `members` or `exclude` lists in root `Cargo.toml`. A change that adds types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. A change to the `compile_error!` in `keetanetwork-asn1/src/lib.rs`, `keetanetwork-client/src/lib.rs` feature `http`, or `keetanetwork-client-wasi/src/lib.rs` `p1` / `p2`. A change to the OpenAPI path `keetanetwork-client/openapi/keetanet-node.yaml` or to the client `generated` module gate. +A change that adds product types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. A change to the `compile_error!` gates in `keetanetwork-asn1/src/lib.rs`, `keetanetwork-client/src/lib.rs` (`http` runtime pairing), or `keetanetwork-client-wasi/src/lib.rs` (`p1` / `p2`). A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml` as the HTTP transport source. A decision to add per-crate README barrels or an `examples/` directory. diff --git a/docs/README.md b/docs/README.md index 896e973..c5b657c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,7 @@ An engineer reads this guide in the first week on the workspace. After reading, ## What this workspace is -This repository is a Cargo workspace of Keeta Network node crates. Root `Cargo.toml` lists the fourteen members. Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. +This repository is a Cargo workspace of Keeta Network node crates. Root `Cargo.toml` lists the workspace members. Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. `keetanetwork-node` and `keetanetwork-ledger` are empty stubs on this tip. Those crates do not hold product types. [Architecture](ARCHITECTURE.md) names that boundary. @@ -30,7 +30,7 @@ Make owns the build. The [package README](../README.md) and the `Makefile` drive Crate rustdoc is the API reference. `make do-docs` generates it. This tree does not copy export lists. -[Architecture](ARCHITECTURE.md) holds the crate-boundary contracts. Feature gates, identity consumption, client generation, and binding ABIs live there. A `docs/concepts/` page lands only when it still holds a non-rustdoc invariant that Architecture does not already carry. +[Architecture](ARCHITECTURE.md) holds the crate-boundary contracts. Forces that split crates, illegal states, and SSOT homes for cross-cutting contracts live there. A `docs/concepts/` page lands only when it still holds a non-rustdoc invariant that Architecture does not already carry. ## Where the tree lives @@ -39,7 +39,7 @@ Crate rustdoc is the API reference. `make do-docs` generates it. This tree does | Root `README.md` | Thin pointer into this tree | | `docs/README.md` | This overview | | `docs/STANDARD.md` | Documentation contract | -| `docs/ARCHITECTURE.md` | Crate boundaries and cross-file contracts | +| `docs/ARCHITECTURE.md` | Workspace split, illegal states, and SSOT homes | | `docs/QUICKSTART.md` | Install, build, test, and first use | | `docs/concepts/*` | Single-topic pages that pass the inclusion test | From ce6baf3758d9f240559e62b385e18e53053411e8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:22:30 +0000 Subject: [PATCH 06/13] docs: restore positive Architecture and crate notes Replace the ban-list Architecture with a collaboration graph and signed-write interaction path. Add docs/crates notes for the twelve product crates and index them on Overview. Co-authored-by: Tanveer Wahid --- README.md | 1 + docs/ARCHITECTURE.md | 128 +++++++++++++++++++++++++------------ docs/README.md | 54 +++++++++++++--- docs/STANDARD.md | 4 +- docs/crates/account.md | 45 +++++++++++++ docs/crates/asn1.md | 31 +++++++++ docs/crates/bindings.md | 33 ++++++++++ docs/crates/block.md | 35 ++++++++++ docs/crates/client-wasi.md | 35 ++++++++++ docs/crates/client-wasm.md | 31 +++++++++ docs/crates/client.md | 37 +++++++++++ docs/crates/crypto.md | 42 ++++++++++++ docs/crates/error.md | 33 ++++++++++ docs/crates/utils.md | 33 ++++++++++ docs/crates/vote.md | 35 ++++++++++ docs/crates/x509.md | 35 ++++++++++ 16 files changed, 560 insertions(+), 52 deletions(-) create mode 100644 docs/crates/account.md create mode 100644 docs/crates/asn1.md create mode 100644 docs/crates/bindings.md create mode 100644 docs/crates/block.md create mode 100644 docs/crates/client-wasi.md create mode 100644 docs/crates/client-wasm.md create mode 100644 docs/crates/client.md create mode 100644 docs/crates/crypto.md create mode 100644 docs/crates/error.md create mode 100644 docs/crates/utils.md create mode 100644 docs/crates/vote.md create mode 100644 docs/crates/x509.md diff --git a/README.md b/README.md index 55d7680..54cf1bf 100644 --- a/README.md +++ b/README.md @@ -35,4 +35,5 @@ make check - [Overview](docs/README.md) - [Quickstart](docs/QUICKSTART.md) - [Architecture](docs/ARCHITECTURE.md) +- [Crate notes](docs/README.md#crate-notes) - [Documentation Standard](docs/STANDARD.md) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 65a4f16..7fac10d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,70 +2,114 @@ ## Abstract -This page states how the `node-rs` workspace is split and which states the tree forbids. Crate rustdoc and each `Cargo.toml` remain the field and dependency references. This page does not inventory members. +This page states how the `node-rs` workspace crates depend on each other and how they collaborate on a signed write. It holds the crate-boundary graph and the interaction path that no single crate rustdoc can show. Per-crate consumer contracts live under [Crate notes](crates/account.md) and the sibling pages listed on [Overview](README.md). ## Purpose -An engineer reads this page to learn why crates exist as separate packages and which combinations are illegal. After reading, the engineer knows where a cross-cutting contract lives and which alternatives stay closed. +An engineer reads this page to learn how work moves from an account identity through a block, a vote staple, the HTTP client, and the host ABIs. After reading, the engineer can name the crate that owns each step and open the crate note that holds that crate's consumer contract. ## Related documents -- [Overview](README.md) for the cultural map and living index. +- [Overview](README.md) for the cultural map and the crate-note table of contents. - [Quickstart](QUICKSTART.md) for install, build, test, and first use. - [Documentation Standard](STANDARD.md) for the inclusion test and page shape. -## Why the workspace splits +## Collaboration graph -The workspace separates four kinds of packages so each kind can change without forcing the others to move. +The workspace lists fourteen members in root `Cargo.toml`. Twelve of those members are product crates. `keetanetwork-node` and `keetanetwork-ledger` keep reserved names. Their `lib.rs` files export no types on this tip. -| Kind | Force that keeps it separate | Examples of the role | -| --- | --- | --- | -| Primitives and codecs | Shared encoding and crypto must stay usable under `no_std` / `alloc` feature matrices | `keetanetwork-crypto`, `keetanetwork-asn1`, `keetanetwork-error`, `keetanetwork-utils` | -| Domain identity and certificates | Account and X.509 rules are consumed by many higher crates | `keetanetwork-account`, `keetanetwork-x509` | -| Ledger domain objects | Block and vote rules are the signed objects the network exchanges | `keetanetwork-block`, `keetanetwork-vote` | -| Client and ABI projections | HTTP generation and host ABIs change on a different cadence than domain types | `keetanetwork-client`, `keetanetwork-bindings`, `keetanetwork-client-wasm`, `keetanetwork-client-wasi` | +The arrows follow member `Cargo.toml` path dependencies that the product path uses. Foundation crates feed identity. Identity feeds signed objects. Signed objects feed the client. The client and the shared bindings crate feed the browser and WASI ABIs. -`keetanetwork-node` and `keetanetwork-ledger` keep reserved crate names in the workspace. Their `lib.rs` files export no types on this tip. They are placeholders, not product surfaces. +```mermaid +flowchart TB + crate_error[keetanetwork-error] + crate_utils[keetanetwork-utils] + crate_crypto[keetanetwork-crypto] + crate_asn1[keetanetwork-asn1] + crate_account[keetanetwork-account] + crate_x509[keetanetwork-x509] + crate_block[keetanetwork-block] + crate_vote[keetanetwork-vote] + crate_client[keetanetwork-client] + crate_bindings[keetanetwork-bindings] + crate_wasm[keetanetwork-client-wasm] + crate_wasi[keetanetwork-client-wasi] + crate_node[keetanetwork-node] + crate_ledger[keetanetwork-ledger] + crate_error --> crate_account + crate_utils --> crate_account + crate_crypto --> crate_account + crate_asn1 --> crate_crypto + crate_account --> crate_x509 + crate_account --> crate_block + crate_account --> crate_vote + crate_account --> crate_client + crate_account --> crate_bindings + crate_x509 --> crate_block + crate_block --> crate_vote + crate_block --> crate_client + crate_vote --> crate_client + crate_client --> crate_wasm + crate_client --> crate_wasi + crate_bindings --> crate_wasm + crate_bindings --> crate_wasi +``` -Crate identity, versions, and dependency edges live in each member `Cargo.toml` and in rustdoc. This page does not restate those lists. +`crate_node` and `crate_ledger` sit in the workspace with no product types. The `crate_client` to `crate_wasi` arrow is the `p2` feature. Feature `p1` stays on the pure surface. -## Illegal states +Each crate note names the remaining `Cargo.toml` edges that this diagram omits, such as `keetanetwork-asn1` into `keetanetwork-block` and `keetanetwork-vote`. -These combinations are forbidden on this tip. The build or the documentation contract rejects them. +## How the crates interact -| Illegal state | Where it fails | Legal alternative | -| --- | --- | --- | -| Treat `keetanetwork-node` or `keetanetwork-ledger` as a product API | Those `lib.rs` files export no types. This page names them as stubs only | Implement types in those crates first, then document them | -| Build `keetanetwork-asn1` with neither `der` nor `rasn` | `compile_error!` in `keetanetwork-asn1/src/lib.rs` | Enable at least one of `der` or `rasn`. Both may be on together | -| Enable client feature `http` without a runtime | `compile_error!` in `keetanetwork-client/src/lib.rs` | Pair `http` with `std` on native targets, or with `wasm` on `wasm32-unknown-unknown` | -| Enable both or neither of WASI features `p1` and `p2` on `keetanetwork-client-wasi` | `compile_error!` in `keetanetwork-client-wasi/src/lib.rs` | Select exactly one of `p1` or `p2` per WASI build | -| Add a per-crate README that only restates `pub use` | Inclusion test on [Documentation Standard](STANDARD.md) | Keep identity in `Cargo.toml` description plus rustdoc | +A signed write walks one path. -## SSOT homes for cross-cutting contracts +An account crate identity starts the path. `keetanetwork-account` owns `Account`, `GenericAccount`, `KeyPairType`, and identifier accounts. Higher crates take those types. They do not invent a second identity model. `CertSigner` and `CertVerifier` live on the account crate. Certificate builders and stores live in `keetanetwork-x509`. -Each row is one body of knowledge. Other pages link here or to the named source. They do not restate field lists. +`keetanetwork-block` turns that identity into a signed object. `Block`, `BlockBuilder`, `Operation`, and `AccountRef` live there. Opening-hash and signing rules live in that crate. The client builder uses the same rules when it assembles a first block or a successor. -| Contract | Home | -| --- | --- | -| Account and identifier identity consumed across crates | `keetanetwork-account` rustdoc. Higher crates consume those types | -| Certificate signing and verification traits versus X.509 builders | Traits on `keetanetwork-account`. Builders and stores in `keetanetwork-x509` | -| Block opening-hash and signing rules | `keetanetwork-block` rustdoc and tests. The client builder uses the same rules | -| Vote versus quote versus staple | `keetanetwork-vote` rustdoc. The client re-exports the consumer-facing vote types | -| HTTP transport shape | `keetanetwork-client/openapi/keetanet-node.yaml` generated through progenitor into the client `generated` module | -| Browser and WASI ABIs | `keetanetwork-bindings` as the shared projection. Wasm amounts are decimal strings and errors carry `error.code`. WASI selects exactly one of `p1` or `p2` | +`keetanetwork-vote` commits those block hashes. A `Vote` is a representative's signed commitment. A `VoteQuote` is a non-binding vote used during fee negotiation. A `VoteStaple` is the compressed bundle of votes and the blocks they cover. `keetanetwork-client` re-exports `Vote`, `VoteQuote`, and `VoteStaple` for callers. + +`keetanetwork-client` is the orchestrator. `KeetaClient`, `UserClient`, and `TransactionBuilder` live there. HTTP transport is generated at build time from `keetanetwork-client/openapi/keetanet-node.yaml` through progenitor. The generated types are exposed as the `generated` module when the `codec` feature is on. The rustdoc example in `keetanetwork-client/src/lib.rs` constructs `KeetaClient::new("http://localhost:8080/api")`. + +`keetanetwork-bindings` is the shared, target-agnostic projection. It maps account algorithms, parses host input, and reduces core errors. `keetanetwork-client-wasm` is the browser ABI. Amounts are decimal strings. Errors carry `error.code`. `keetanetwork-client-wasi` selects exactly one of `p1` or `p2` on a WASI target. + +Foundation crates sit under that path. `keetanetwork-error` holds shared error types. `keetanetwork-crypto` holds algorithm-agnostic primitives. `keetanetwork-asn1` holds the encoding codecs. `keetanetwork-utils` holds test macros, the `build` helpers, and the `node-harness` feature that [Quickstart](QUICKSTART.md) names as the Packages gate. + +## Build contracts that span crates + +These statements are the positive feature contracts that more than one crate must honor. -## Rejected alternatives +`keetanetwork-asn1` enables at least one of `der` or `rasn`. Both features may be on together. The `compile_error!` in `keetanetwork-asn1/src/lib.rs` is the enforcement point. Higher crates that expose `der` or `rasn` forward those names to `keetanetwork-asn1`. -These decisions stay closed. A later change that reopens one is a migration. +`keetanetwork-client` feature `http` pairs with a runtime. Native builds enable `std`. Browser builds enable `wasm` on `wasm32-unknown-unknown`. The `compile_error!` in `keetanetwork-client/src/lib.rs` is the enforcement point. -| Decision | Rejected alternative | Why the alternative lost | -| --- | --- | --- | -| Crate identity lives in each `Cargo.toml` plus rustdoc | One README barrel per member crate | A barrel restates `pub use` and fails the inclusion test | -| Examples stay in crate rustdoc and tests | An `examples/` directory | No such directory exists on this tip. Scope keeps examples in-crate | -| Architecture names node and ledger as stubs | A node or ledger product page | Those `lib.rs` files export no types | -| Quickstart holds the PAT and Packages fact | Revival of branch `docs/add_pat_instructions` | That branch is stale and still taught `make release` as a release build | -| Architecture explains forces and illegal states | A member roster or a Mermaid copy of `Cargo.toml` edges | Rosters and edge copies go stale without teaching structure | +`keetanetwork-client-wasi` selects exactly one of `p1` or `p2` on a WASI target. Feature `p2` pulls `keetanetwork-client`. Feature `p1` stays on the pure surface. The `compile_error!` in `keetanetwork-client-wasi/src/lib.rs` is the enforcement point. + +Workspace crates share the `std` and `alloc` feature names so a `no_std` consumer can stay on `alloc` through the identity and object crates. + +## Crate-note homes + +Each product crate has one note. The note holds that crate's consumer contract and the crates that call it. This page does not copy those contracts. + +| Crate | Note | +| --- | --- | +| `keetanetwork-account` | [Account](crates/account.md) | +| `keetanetwork-error` | [Error](crates/error.md) | +| `keetanetwork-crypto` | [Crypto](crates/crypto.md) | +| `keetanetwork-x509` | [X.509](crates/x509.md) | +| `keetanetwork-asn1` | [ASN.1](crates/asn1.md) | +| `keetanetwork-utils` | [Utils](crates/utils.md) | +| `keetanetwork-block` | [Block](crates/block.md) | +| `keetanetwork-vote` | [Vote](crates/vote.md) | +| `keetanetwork-client` | [Client](crates/client.md) | +| `keetanetwork-bindings` | [Bindings](crates/bindings.md) | +| `keetanetwork-client-wasm` | [Client wasm](crates/client-wasm.md) | +| `keetanetwork-client-wasi` | [Client WASI](crates/client-wasi.md) | + +`keetanetwork-node` and `keetanetwork-ledger` have no crate note. Those `lib.rs` files export no types. This page is the home that names them as stubs. + +Crate identity, versions, and field lists live in each member `Cargo.toml` and in rustdoc. This tree does not copy those lists. ## Falsified by -A change that adds product types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. A change to the `compile_error!` gates in `keetanetwork-asn1/src/lib.rs`, `keetanetwork-client/src/lib.rs` (`http` runtime pairing), or `keetanetwork-client-wasi/src/lib.rs` (`p1` / `p2`). A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml` as the HTTP transport source. A decision to add per-crate README barrels or an `examples/` directory. +A change to the workspace `members` or `exclude` lists in root `Cargo.toml`. A change that adds product types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. A change to the `compile_error!` gates in `keetanetwork-asn1/src/lib.rs`, `keetanetwork-client/src/lib.rs` (`http` runtime pairing), or `keetanetwork-client-wasi/src/lib.rs` (`p1` / `p2`). A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml`. A change to the product-crate set that [Overview](README.md) indexes under `docs/crates/`. diff --git a/docs/README.md b/docs/README.md index c5b657c..0be5db7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ ## Abstract -This guide is the cultural map for the `node-rs` workspace. Invariant detail lives on [Architecture](ARCHITECTURE.md). Install, build, and test steps live on [Quickstart](QUICKSTART.md). +This guide is the cultural map for the `node-rs` workspace. Invariant detail lives on [Architecture](ARCHITECTURE.md) and the crate notes. Install, build, and test steps live on [Quickstart](QUICKSTART.md). ## Purpose @@ -10,15 +10,27 @@ An engineer reads this guide in the first week on the workspace. After reading, | Next question | The page | | --- | --- | -| What is always true across crate boundaries? | [Architecture](ARCHITECTURE.md) | +| How do the crates depend on and call each other? | [Architecture](ARCHITECTURE.md) | | How does a reader install, build, and test? | [Quickstart](QUICKSTART.md) | | How does a writer review a page in this tree? | [Documentation Standard](STANDARD.md) | +| Where do account identities live? | [Account](crates/account.md) | +| Where do shared errors live? | [Error](crates/error.md) | +| Where do signing primitives live? | [Crypto](crates/crypto.md) | +| Where do certificate builders live? | [X.509](crates/x509.md) | +| Where does the ASN.1 codec contract live? | [ASN.1](crates/asn1.md) | +| Where do test helpers and the harness live? | [Utils](crates/utils.md) | +| Where do opening-hash and block signing live? | [Block](crates/block.md) | +| Where do vote, quote, and staple live? | [Vote](crates/vote.md) | +| Where do `KeetaClient` and HTTP generation live? | [Client](crates/client.md) | +| Where does the shared host projection live? | [Bindings](crates/bindings.md) | +| Where does the browser ABI live? | [Client wasm](crates/client-wasm.md) | +| Where does the WASI `p1` / `p2` contract live? | [Client WASI](crates/client-wasi.md) | ## What this workspace is This repository is a Cargo workspace of Keeta Network node crates. Root `Cargo.toml` lists the workspace members. Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. -`keetanetwork-node` and `keetanetwork-ledger` are empty stubs on this tip. Those crates do not hold product types. [Architecture](ARCHITECTURE.md) names that boundary. +Twelve members are product crates. Each product crate has one note under `docs/crates/`. `keetanetwork-node` and `keetanetwork-ledger` are empty stubs on this tip. Those crates do not hold product types. [Architecture](ARCHITECTURE.md) names that boundary. Each member crate carries its own version in that crate `Cargo.toml`. This guide does not treat the unused workspace package version as the repository version. @@ -30,7 +42,28 @@ Make owns the build. The [package README](../README.md) and the `Makefile` drive Crate rustdoc is the API reference. `make do-docs` generates it. This tree does not copy export lists. -[Architecture](ARCHITECTURE.md) holds the crate-boundary contracts. Forces that split crates, illegal states, and SSOT homes for cross-cutting contracts live there. A `docs/concepts/` page lands only when it still holds a non-rustdoc invariant that Architecture does not already carry. +[Architecture](ARCHITECTURE.md) holds the collaboration graph and the signed-write path. Each crate note holds that crate's consumer contract. A `docs/concepts/` page lands only when it still holds a non-rustdoc invariant that Architecture and the crate notes do not already carry. + +## Crate notes + +These pages are the living table of contents for product crates. [Architecture](ARCHITECTURE.md) draws the graph. Each note names the crates that call that crate. + +| Crate | Version on this tip | Note | +| --- | --- | --- | +| `keetanetwork-account` | `0.4.0` | [Account](crates/account.md) | +| `keetanetwork-error` | `0.2.1` | [Error](crates/error.md) | +| `keetanetwork-crypto` | `0.3.0` | [Crypto](crates/crypto.md) | +| `keetanetwork-x509` | `0.4.0` | [X.509](crates/x509.md) | +| `keetanetwork-asn1` | `0.2.5` | [ASN.1](crates/asn1.md) | +| `keetanetwork-utils` | `0.2.1` | [Utils](crates/utils.md) | +| `keetanetwork-block` | `0.4.1` | [Block](crates/block.md) | +| `keetanetwork-vote` | `0.4.0` | [Vote](crates/vote.md) | +| `keetanetwork-client` | `0.5.1` | [Client](crates/client.md) | +| `keetanetwork-bindings` | `0.4.4` | [Bindings](crates/bindings.md) | +| `keetanetwork-client-wasm` | `0.5.1` | [Client wasm](crates/client-wasm.md) | +| `keetanetwork-client-wasi` | `0.6.1` | [Client WASI](crates/client-wasi.md) | + +`keetanetwork-node` `0.2.1` and `keetanetwork-ledger` `0.2.1` have no crate note. Those `lib.rs` files export no types. ## Where the tree lives @@ -39,8 +72,9 @@ Crate rustdoc is the API reference. `make do-docs` generates it. This tree does | Root `README.md` | Thin pointer into this tree | | `docs/README.md` | This overview | | `docs/STANDARD.md` | Documentation contract | -| `docs/ARCHITECTURE.md` | Workspace split, illegal states, and SSOT homes | +| `docs/ARCHITECTURE.md` | Collaboration graph and interaction path | | `docs/QUICKSTART.md` | Install, build, test, and first use | +| `docs/crates/*` | Per-crate consumer contracts | | `docs/concepts/*` | Single-topic pages that pass the inclusion test | GitHub issues and pull requests stay the history home. @@ -58,7 +92,7 @@ GitHub issues and pull requests stay the history home. | Change | Place | | --- | --- | -| A crate-boundary invariant | The crate source, then [Architecture](ARCHITECTURE.md) | +| A crate-boundary invariant | The crate source, then [Architecture](ARCHITECTURE.md) and the crate note | | An install or build step | `Makefile`, then [Quickstart](QUICKSTART.md) | | A documentation page | This tree, then the next-question table on this guide. Writers follow [Documentation Standard](STANDARD.md). | | A public type contract | rustdoc on that type | @@ -67,9 +101,10 @@ GitHub issues and pull requests stay the history home. 1. This guide. 2. [Architecture](ARCHITECTURE.md). -3. [Quickstart](QUICKSTART.md). -4. [Documentation Standard](STANDARD.md) before a docs edit. -5. The crate `lib.rs` rustdoc for the crate under change. +3. The crate note for the crate under change. +4. [Quickstart](QUICKSTART.md). +5. [Documentation Standard](STANDARD.md) before a docs edit. +6. The crate `lib.rs` rustdoc for the crate under change. ## Cultural one-liners @@ -85,4 +120,5 @@ GitHub issues and pull requests stay the history home. - A change to the living documentation map that the first-week links follow. - A change to the workspace `members` list in root `Cargo.toml`. - A change that adds product types to `keetanetwork-node` or `keetanetwork-ledger`. +- A change to a product-crate version in that crate `Cargo.toml`. - A change to the license strings in root `LICENSE`, workspace `Cargo.toml`, or `keetanetwork-utils/node-harness/package.json`. diff --git a/docs/STANDARD.md b/docs/STANDARD.md index 22b7706..878fd8f 100644 --- a/docs/STANDARD.md +++ b/docs/STANDARD.md @@ -33,7 +33,9 @@ A page MUST NOT carry the following. The source is the one correct home for each One body of knowledge takes one page as its home. A second page that needs it MUST link to that home rather than restate it. The [Overview](README.md) names the living pages. -A concept page under `docs/concepts/` lands only when it still holds a non-rustdoc invariant after the Architecture draft. A candidate that collapses to a field list MUST NOT land. +[Architecture](ARCHITECTURE.md) holds the workspace collaboration graph and the interaction path. A page under `docs/crates/` holds one product crate's consumer contract and the crates that call it. That page MUST add collaboration or feature-gate substance that rustdoc on a single type cannot hold. It MUST NOT restate that crate `pub use` list. + +A concept page under `docs/concepts/` lands only when it still holds a non-rustdoc invariant after the Architecture draft and the crate note. A candidate that collapses to a field list MUST NOT land. When a page must name a symbol, it cites that symbol as `Symbol` in `path/to/file`. The source carries its own detail. diff --git a/docs/crates/account.md b/docs/crates/account.md new file mode 100644 index 0000000..72fce8b --- /dev/null +++ b/docs/crates/account.md @@ -0,0 +1,45 @@ +# Account + +## Abstract + +This page is the consumer contract for `keetanetwork-account`. The crate owns typed and type-erased identities plus the certificate signing traits. Block, vote, x509, client, and bindings crates consume those identities. + +## Purpose + +An engineer reads this page before changing an identity type or adding a second account model in a higher crate. After reading, the engineer knows which types this crate owns and which crates must keep consuming them. + +## Ownership + +`keetanetwork-account` owns `Account`, `GenericAccount`, `KeyPairType`, and identifier accounts. `Account` is the typed identity bound to one `KeyPairType`. `GenericAccount` is the type-erased account used at crate boundaries. `KeyPairType` names signing algorithms and identifier accounts. + +`CertSigner` signs X.509-shaped artifacts in certificate mode. `CertVerifier` verifies those certificate-mode signatures. Certificate builders and stores stay in `keetanetwork-x509`. + +Crate rustdoc on `keetanetwork-account/src/lib.rs` names those types. Field lists stay in rustdoc. + +## Who consumes this crate + +| Consumer | How it uses the identities | +| --- | --- | +| `keetanetwork-block` | `AccountRef` wraps `GenericAccount`. Opening-hash and signing use the same account | +| `keetanetwork-vote` | A vote issuer is an `AccountRef` | +| `keetanetwork-x509` | Builders call `CertSigner` and `CertVerifier` | +| `keetanetwork-client` | `KeetaClient` and `UserClient` take an `AccountRef` | +| `keetanetwork-bindings` | Host ABIs map account algorithms through this crate | + +[Architecture](../ARCHITECTURE.md) holds the collaboration graph. This page does not redraw it. + +## Feature contract + +Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1` and `keetanetwork-crypto`. + +A `no_std` consumer enables `alloc` and at least one of `der` or `rasn` when it needs the ASN.1 path. [ASN.1](asn1.md) holds the at-least-one codec contract. + +This crate depends on `keetanetwork-crypto` with `signature` and `encryption`. It depends on `keetanetwork-error` and `keetanetwork-utils`. `keetanetwork-asn1` is optional behind `der` and `rasn`. + +## Seed and identifier tests + +Account seed, identifier, and signature cookbooks live in `keetanetwork-account/tests/account_creation.rs`, `keetanetwork-account/tests/seed_derivation.rs`, `keetanetwork-account/tests/identifier_accounts.rs`, and `keetanetwork-account/tests/signatures.rs`. + +## Falsified by + +A change that moves `Account`, `GenericAccount`, `KeyPairType`, `CertSigner`, or `CertVerifier` off this crate. A change that adds a second identity model in `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, `keetanetwork-client`, or `keetanetwork-bindings`. A change to the `der` / `rasn` forwarding in `keetanetwork-account/Cargo.toml`. diff --git a/docs/crates/asn1.md b/docs/crates/asn1.md new file mode 100644 index 0000000..d42df23 --- /dev/null +++ b/docs/crates/asn1.md @@ -0,0 +1,31 @@ +# ASN.1 + +## Abstract + +This page is the consumer contract for `keetanetwork-asn1`. The crate owns the encoding codecs that identity, certificate, block, and vote types share. A build enables at least one of `der` or `rasn`. + +## Purpose + +An engineer reads this page before changing a codec feature or adding a third ASN.1 stack. After reading, the engineer knows the at-least-one feature contract and which crates forward `der` and `rasn` into this crate. + +## Ownership + +`keetanetwork-asn1` owns ASN.1 structures and codec utilities used by certificates and related encodings. Crate rustdoc in `keetanetwork-asn1/src/lib.rs` lists the features and states the at-least-one contract. + +This crate depends on `keetanetwork-utils`. The `build` feature on that crate supplies generation helpers. [Utils](utils.md) holds that helper. + +## Feature contract + +A consumer enables at least one of `der` or `rasn`. Both features may be on together. The `compile_error!` in `keetanetwork-asn1/src/lib.rs` is the enforcement point. + +Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. + +Higher crates expose `der` and `rasn` under the same names and forward them here. Those crates include `keetanetwork-account`, `keetanetwork-crypto`, `keetanetwork-x509`, `keetanetwork-block`, and `keetanetwork-vote`. + +## Who consumes this crate + +Block, vote, x509, account, crypto, and bindings crates depend on this crate when they encode or decode shared structures. [Architecture](../ARCHITECTURE.md) holds the collaboration graph. + +## Falsified by + +A change to the `compile_error!` in `keetanetwork-asn1/src/lib.rs` that no longer requires at least one of `der` or `rasn`. A change that adds a third codec feature without updating this page and the rustdoc feature list. A change that stops `keetanetwork-account`, `keetanetwork-block`, or `keetanetwork-vote` from forwarding `der` and `rasn` here. diff --git a/docs/crates/bindings.md b/docs/crates/bindings.md new file mode 100644 index 0000000..4427b07 --- /dev/null +++ b/docs/crates/bindings.md @@ -0,0 +1,33 @@ +# Bindings + +## Abstract + +This page is the consumer contract for `keetanetwork-bindings`. The crate is the shared, target-agnostic projection used by the browser and WASI ABIs. It owns input parsing, account-algorithm mapping, and core-error reduction so those ABIs do not each grow a second copy. + +## Purpose + +An engineer reads this page before adding host-facing parsing in `keetanetwork-client-wasm` or `keetanetwork-client-wasi`. After reading, the engineer knows which work stays in this crate and which work stays in a target crate. + +## Ownership + +`keetanetwork-bindings` owns the shared projection. Crate rustdoc in `keetanetwork-bindings/src/lib.rs` states that each FFI boundary repeats the same input parsing, account-algorithm mapping, and core-error reduction. + +This crate depends on `keetanetwork-account`, `keetanetwork-crypto`, `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, and `keetanetwork-asn1` with `alloc` and `rasn`. Feature `client` pulls optional `keetanetwork-client`. + +Field lists stay in rustdoc. + +## Who consumes this crate + +`keetanetwork-client-wasm` depends on this crate with the `client` feature. `keetanetwork-client-wasi` depends on this crate on every build. Feature `p2` on the WASI crate also enables `keetanetwork-bindings/client`. + +[Client wasm](client-wasm.md) holds the browser ABI conventions. [Client WASI](client-wasi.md) holds the `p1` / `p2` contract. [Architecture](../ARCHITECTURE.md) holds the collaboration path. + +## Feature contract + +Default features include `std`. Feature `client` is opt-in and enables `keetanetwork-client`. + +A target crate that only needs the pure projection leaves `client` off. A target crate that needs the HTTP orchestrator enables `client`. + +## Falsified by + +A change that moves account-algorithm mapping or core-error reduction into `keetanetwork-client-wasm` or `keetanetwork-client-wasi` without this crate. A change to the `client` feature in `keetanetwork-bindings/Cargo.toml`. A change that drops this crate from either host ABI crate. diff --git a/docs/crates/block.md b/docs/crates/block.md new file mode 100644 index 0000000..d676e4f --- /dev/null +++ b/docs/crates/block.md @@ -0,0 +1,35 @@ +# Block + +## Abstract + +This page is the consumer contract for `keetanetwork-block`. The crate owns `Block`, `BlockBuilder`, `Operation`, and `AccountRef`. Opening-hash and signing rules live here. The client builder uses the same rules. + +## Purpose + +An engineer reads this page before changing how a first block or a successor is signed. After reading, the engineer knows which types this crate owns and which crates must keep using them. + +## Ownership + +`keetanetwork-block` owns the signed block and the operations it carries. `AccountRef` wraps a `GenericAccount` from `keetanetwork-account`. Opening-hash calculation and `sign` live on the block types. + +The rustdoc example in `keetanetwork-block/src/lib.rs` builds a signed opening block through `BlockBuilder::default()`, `as_opening`, and `sign`. A live harness cookbook lives in `keetanetwork-block/tests/e2e.rs`. TypeScript compatibility tests live in `keetanetwork-block/tests/typescript_compat.rs`. + +Field lists stay in rustdoc. + +## Who consumes this crate + +`keetanetwork-vote` covers block hashes. `keetanetwork-client` assembles blocks through `TransactionBuilder` and transmits them inside a staple. `keetanetwork-bindings` and the host ABI crates project the same block types. + +[Account](account.md) holds the identity types. [Vote](vote.md) holds the commitment that covers those hashes. [Architecture](../ARCHITECTURE.md) holds the collaboration path. + +## Feature contract + +Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`, `keetanetwork-account`, `keetanetwork-crypto`, and `keetanetwork-x509`. + +This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork-crypto` with `signature`, `keetanetwork-account`, `keetanetwork-asn1`, and `keetanetwork-x509`. + +A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](asn1.md) holds the codec contract. + +## Falsified by + +A change to `Block`, `BlockBuilder`, `Operation`, or `AccountRef` ownership. A change that lets `keetanetwork-client` compute an opening hash without this crate. A change to the rustdoc example in `keetanetwork-block/src/lib.rs`. A change to the `der` / `rasn` forwarding in `keetanetwork-block/Cargo.toml`. diff --git a/docs/crates/client-wasi.md b/docs/crates/client-wasi.md new file mode 100644 index 0000000..6893eba --- /dev/null +++ b/docs/crates/client-wasi.md @@ -0,0 +1,35 @@ +# Client WASI + +## Abstract + +This page is the consumer contract for `keetanetwork-client-wasi`. The crate is the WASI ABI over a shared `pure` module. A WASI build selects exactly one of `p1` or `p2`. Feature `p2` pulls `keetanetwork-client`. Feature `p1` stays on the pure surface. + +## Purpose + +An engineer reads this page before changing a WASI feature or adding a second networking path on `p1`. After reading, the engineer knows which feature a P1 or P2 build enables and which crate supplies HTTP. + +## Ownership + +`keetanetwork-client-wasi` owns two feature-selected flavors over one shared `pure` module in `keetanetwork-client-wasi/src/lib.rs`. + +Feature `p2` on `wasm32-wasip2` is a `wit-bindgen` component. It networks over `wasi:http` and exposes the pure surface. That feature pulls `keetanetwork-client` with the `wasi` feature and enables `keetanetwork-bindings/client`. + +Feature `p1` on `wasm32-wasip1` is a core module. It exposes the pure surface over a flat ABI. P1 has no outbound `connect`. The host dials. + +A WASI build enables exactly one of `p1` or `p2`. The `compile_error!` in `keetanetwork-client-wasi/src/lib.rs` is the enforcement point. Off a WASI target both features compile out and leave `pure`. + +Host tests live under `keetanetwork-client-wasi/host-tests/`. [Quickstart](../QUICKSTART.md) names `make build-wasi` and `make test-wasi`. Those targets select `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. + +## Who this crate projects + +This crate always depends on `keetanetwork-account`, `keetanetwork-block`, `keetanetwork-crypto`, `keetanetwork-vote`, `keetanetwork-x509`, and `keetanetwork-bindings`. Feature `p2` adds `keetanetwork-client`. + +[Client](client.md) holds the `wasi` feature that supplies codec types without Tokio. [Bindings](bindings.md) holds the shared projection. [Architecture](../ARCHITECTURE.md) holds the collaboration path. + +## Feature contract + +Select exactly one of `p1` or `p2` per WASI build. Feature `p2` is the only edge from this crate to `keetanetwork-client`. Feature `p1` stays on the pure surface. + +## Falsified by + +A change to the `compile_error!` in `keetanetwork-client-wasi/src/lib.rs`. A change that lets a WASI build enable both `p1` and `p2`, or neither. A change that pulls `keetanetwork-client` on feature `p1`. A change to the `p1` / `p2` selection in the `Makefile` `build-wasi` or `test-wasi` targets. diff --git a/docs/crates/client-wasm.md b/docs/crates/client-wasm.md new file mode 100644 index 0000000..e7e7f1c --- /dev/null +++ b/docs/crates/client-wasm.md @@ -0,0 +1,31 @@ +# Client wasm + +## Abstract + +This page is the consumer contract for `keetanetwork-client-wasm`. The crate is the browser ABI over `keetanetwork-client` and `keetanetwork-bindings`. Amounts are decimal strings. Errors carry `error.code`. + +## Purpose + +An engineer reads this page before changing the browser ABI or adding a JavaScript number amount. After reading, the engineer knows the conventions this crate guarantees and which crates it projects. + +## Ownership + +`keetanetwork-client-wasm` projects `KeetaClient`, `UserClient`, and account helpers into JavaScript. Crate rustdoc in `keetanetwork-client-wasm/src/lib.rs` holds the conventions and the JavaScript example. + +Amounts are decimal strings such as `"1000"`. They are not JavaScript `number` values. Cryptographic bytes are `Uint8Array`. Hashes and keys are hex strings. Errors are JavaScript `Error` objects that carry a stable `error.code`. + +`make build-wasm` runs `wasm-pack build` for this crate. Playwright cookbooks live in `keetanetwork-client-wasm/tests/roundtrip.spec.ts` and `keetanetwork-client-wasm/tests/fee.spec.ts`. [Quickstart](../QUICKSTART.md) names the Make targets and the Packages gate. + +## Who this crate projects + +This crate depends on `keetanetwork-client` with the `wasm` feature. It depends on `keetanetwork-bindings` with the `client` feature. It also depends on `keetanetwork-account`, `keetanetwork-block`, `keetanetwork-crypto`, `keetanetwork-x509`, and `keetanetwork-asn1`. + +[Client](client.md) holds the orchestrator and the `http` plus `wasm` pairing. [Bindings](bindings.md) holds the shared projection. [Architecture](../ARCHITECTURE.md) holds the collaboration path. + +## Feature contract + +The client `wasm` feature enables `http` on `wasm32-unknown-unknown`. That pairing satisfies the `compile_error!` in `keetanetwork-client/src/lib.rs`. + +## Falsified by + +A change that accepts a JavaScript `number` as an amount. A change that drops `error.code` from thrown errors. A change that builds this crate without `keetanetwork-client` feature `wasm` or `keetanetwork-bindings` feature `client`. A change to the rustdoc example in `keetanetwork-client-wasm/src/lib.rs`. diff --git a/docs/crates/client.md b/docs/crates/client.md new file mode 100644 index 0000000..b6a9728 --- /dev/null +++ b/docs/crates/client.md @@ -0,0 +1,37 @@ +# Client + +## Abstract + +This page is the consumer contract for `keetanetwork-client`. The crate owns `KeetaClient`, `UserClient`, and `TransactionBuilder`. HTTP transport is generated from the committed OpenAPI document. The crate re-exports the consumer-facing vote types. + +## Purpose + +An engineer reads this page before changing client construction, HTTP generation, or the `http` runtime pairing. After reading, the engineer knows which types this crate owns and which features a native or browser build enables. + +## Ownership + +`KeetaClient` is the orchestrator. `UserClient` signs and transmits on behalf of an account. `TransactionBuilder` assembles blocks with the same opening-hash and signing rules as `keetanetwork-block`. + +HTTP transport is generated at build time from `keetanetwork-client/openapi/keetanet-node.yaml` through progenitor. The generated types are exposed as the `generated` module when the `codec` feature is on. + +The rustdoc example in `keetanetwork-client/src/lib.rs` constructs `KeetaClient::new("http://localhost:8080/api")` and `.with_network(0u8)`. A live harness cookbook lives in `keetanetwork-client/tests/e2e.rs`. `UserClient` signing tests live in `keetanetwork-client/tests/user_signing.rs`. [Quickstart](../QUICKSTART.md) cites those examples. + +The crate re-exports `Vote`, `VoteQuote`, `VoteStaple`, and `VoteBlockHash` from `keetanetwork-vote`. It also re-exports `KeetaNetError` and `NodeErrorType` from `keetanetwork-error`. + +## Feature contract + +Default features include `std`. Feature `std` enables `http` and a native Tokio runtime. Feature `wasm` enables `http` on `wasm32-unknown-unknown`. Feature `wasi` enables `codec` without pulling Tokio. + +Feature `http` pairs with a runtime. Native builds enable `std`. Browser builds enable `wasm` on `wasm32-unknown-unknown`. The `compile_error!` in `keetanetwork-client/src/lib.rs` is the enforcement point. + +The orchestrator is `no_std` plus `alloc` when `std`, `http`, and `wasi` are off. A `no_std` consumer supplies a `Runtime` and a `NodeTransport` through `KeetaClient::with_parts`. + +## Who consumes this crate + +`keetanetwork-client-wasm` enables the `wasm` feature. `keetanetwork-client-wasi` enables this crate only on feature `p2`. `keetanetwork-bindings` takes this crate behind its `client` feature. + +[Block](block.md) and [Vote](vote.md) hold the signed objects. [Bindings](bindings.md) holds the shared host projection. [Architecture](../ARCHITECTURE.md) holds the collaboration path. + +## Falsified by + +A change to `KeetaClient`, `UserClient`, or `TransactionBuilder` ownership. A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml`. A change to the `compile_error!` that pairs `http` with a runtime. A change that drops the vote or error re-exports from `keetanetwork-client/src/lib.rs`. diff --git a/docs/crates/crypto.md b/docs/crates/crypto.md new file mode 100644 index 0000000..40490b3 --- /dev/null +++ b/docs/crates/crypto.md @@ -0,0 +1,42 @@ +# Crypto + +## Abstract + +This page is the consumer contract for `keetanetwork-crypto`. The crate owns algorithm-agnostic primitives for keys, hashes, signatures, and encryption. Account, block, vote, client, and bindings crates call those primitives. They do not embed a second crypto stack. + +## Purpose + +An engineer reads this page before adding a signing or hashing path in a higher crate. After reading, the engineer knows which features this crate exposes and which crates must keep depending on it. + +## Ownership + +`keetanetwork-crypto` owns key generation, derivation, public-key formatting, hashing, signatures, and encryption. The crate rustdoc in `keetanetwork-crypto/src/lib.rs` names support for `secp256k1` and `Ed25519`. + +`Hashable` and the signing prelude live in this crate. `keetanetwork-block` and `keetanetwork-vote` hash and sign through those types. + +Field lists stay in rustdoc. + +## Who consumes this crate + +| Consumer | How it uses this crate | +| --- | --- | +| `keetanetwork-account` | Enables `signature` and `encryption` for account keys | +| `keetanetwork-block` | Enables `signature` for block signing | +| `keetanetwork-vote` | Enables `signature` for vote signing | +| `keetanetwork-x509` | Uses the same primitives for certificate material | +| `keetanetwork-client` | Depends on `alloc` for client-side hashing | +| `keetanetwork-bindings` | Depends on `alloc` and `signature` for host ABIs | + +[Architecture](../ARCHITECTURE.md) holds the collaboration graph. + +## Feature contract + +Default features are `std`, `signature`, `encryption`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to optional `keetanetwork-asn1`. + +`keetanetwork-error` is optional and comes on with `std`. `keetanetwork-utils` is a path dependency. + +A `no_std` consumer enables `alloc` plus `signature` or `encryption` as the call site needs. [ASN.1](asn1.md) holds the codec contract when `der` or `rasn` is on. + +## Falsified by + +A change that moves hashing or signing primitives out of `keetanetwork-crypto`. A change that lets `keetanetwork-account`, `keetanetwork-block`, or `keetanetwork-vote` sign without this crate. A change to the `signature`, `encryption`, `der`, or `rasn` features in `keetanetwork-crypto/Cargo.toml`. diff --git a/docs/crates/error.md b/docs/crates/error.md new file mode 100644 index 0000000..a6eead6 --- /dev/null +++ b/docs/crates/error.md @@ -0,0 +1,33 @@ +# Error + +## Abstract + +This page is the consumer contract for `keetanetwork-error`. The crate owns shared error types that higher crates return and that the client re-exports. It also names the node error categories that a decoded envelope can carry. + +## Purpose + +An engineer reads this page before introducing a crate-local error envelope that callers must learn twice. After reading, the engineer knows which types this crate owns and which crate re-exports them to HTTP callers. + +## Ownership + +`keetanetwork-error` owns `KeetaNetError` and `NodeErrorType` in `keetanetwork-error/src/lib.rs`. `NodeErrorType` is the category taken from the `type` field of a node error envelope. The known categories are `Account`, `Api`, `Block`, `Certificate`, `Client`, `Kv`, `Ledger`, `Permissions`, `Vote`, and `Generic`. + +Field lists and variant payloads stay in rustdoc. + +## Who consumes this crate + +`keetanetwork-account`, `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, and `keetanetwork-client` depend on this crate. `keetanetwork-client` re-exports `KeetaNetError` and `NodeErrorType` from `keetanetwork-client/src/lib.rs`. + +`keetanetwork-crypto` takes this crate only when the `std` feature is on. + +[Architecture](../ARCHITECTURE.md) holds the collaboration graph. + +## Feature contract + +Default features include `std`. `std` implies `alloc`. The crate builds under `no_std` with `alloc`. + +A higher crate that needs formatted errors on native targets enables `keetanetwork-error/std`. A `no_std` consumer enables `alloc` only. + +## Falsified by + +A change to `KeetaNetError` or `NodeErrorType` in `keetanetwork-error/src/lib.rs`. A change that drops the client re-export of those two types from `keetanetwork-client/src/lib.rs`. A change to the `std` / `alloc` features in `keetanetwork-error/Cargo.toml`. diff --git a/docs/crates/utils.md b/docs/crates/utils.md new file mode 100644 index 0000000..f746587 --- /dev/null +++ b/docs/crates/utils.md @@ -0,0 +1,33 @@ +# Utils + +## Abstract + +This page is the consumer contract for `keetanetwork-utils`. The crate owns shared test macros, optional ASN.1 build helpers, and the `node-harness` feature that talks to the private GitHub Packages package. [Quickstart](../QUICKSTART.md) holds the operator steps for that gate. + +## Purpose + +An engineer reads this page before adding a workspace-wide test helper or changing the harness feature. After reading, the engineer knows which features this crate owns and which pages hold the install steps. + +## Ownership + +`keetanetwork-utils` owns reusable `macro_rules!` macros, a `testing` module, an optional `build` module, and an optional `node_harness` module. Crate rustdoc in `keetanetwork-utils/src/lib.rs` is the module reference. + +Feature `build` enables `rasn-compiler` and the `build` module. `keetanetwork-asn1` and `keetanetwork-x509` use that feature from their build scripts. + +Feature `node-harness` enables the harness client. `keetanetwork-utils/node-harness/.npmrc` sets `@keetanetwork:registry=https://npm.pkg.github.com`. [Quickstart](../QUICKSTART.md) holds the Packages token steps and the cargo-only path. + +## Who consumes this crate + +Account, crypto, asn1, x509, block, and vote crates depend on this crate for shared helpers. Test binaries enable `std` and `node-harness` when they talk to a live node. + +This crate is not on the signed-write collaboration path in [Architecture](../ARCHITECTURE.md). It is the shared tooling under that path. + +## Feature contract + +Default features include `std`. Feature `build` is opt-in. Feature `node-harness` is opt-in and pulls `serde_json` and `snafu`. + +A docs or compile-only change does not need `node-harness`. `make test`, `make test-wasm`, and `make test-wasi` do. + +## Falsified by + +A change to the `build` or `node-harness` features in `keetanetwork-utils/Cargo.toml`. A change to the registry line in `keetanetwork-utils/node-harness/.npmrc`. A change that moves workspace test macros out of `keetanetwork-utils/src/lib.rs`. diff --git a/docs/crates/vote.md b/docs/crates/vote.md new file mode 100644 index 0000000..4085933 --- /dev/null +++ b/docs/crates/vote.md @@ -0,0 +1,35 @@ +# Vote + +## Abstract + +This page is the consumer contract for `keetanetwork-vote`. The crate owns `Vote`, `VoteQuote`, `VoteStaple`, and `PossiblyExpiredVote`. The client re-exports the consumer-facing vote types. A quote is for fee negotiation. A staple is the bundle that operators transmit. + +## Purpose + +An engineer reads this page before changing vote construction or adding a second staple type in the client. After reading, the engineer knows which vote kinds this crate owns and which crate re-exports them. + +## Ownership + +A `Vote` is a representative's signed commitment that named block hashes should enter the ledger. A `VoteQuote` is a non-binding vote whose fees field has `quote = true`. A quote cannot be stapled or used to confirm blocks. A `PossiblyExpiredVote` is a parsed and signature-verified vote whose validity window may have ended. A `VoteStaple` is the compressed bundle of votes and the blocks they cover. + +`VoteBuilder`, `VoteQuoteBuilder`, and `VoteStapleBuilder` assemble those types. Crate rustdoc in `keetanetwork-vote/src/lib.rs` holds the rustdoc example and the verification contract. This crate denies missing docs. + +Cookbooks live in `keetanetwork-vote/tests/e2e_node.rs`, `keetanetwork-vote/tests/typescript_compat.rs`, and `keetanetwork-vote/tests/wire_corruption.rs`. + +## Who consumes this crate + +`keetanetwork-client` depends on this crate and re-exports `Vote`, `VoteQuote`, `VoteStaple`, and `VoteBlockHash` from `keetanetwork-client/src/lib.rs`. `keetanetwork-bindings` and `keetanetwork-client-wasi` depend on this crate so host ABIs can project vote types. + +[Block](block.md) holds the hashes a vote covers. [Client](client.md) holds the transmit path. [Architecture](../ARCHITECTURE.md) holds the collaboration path. + +## Feature contract + +Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`, `keetanetwork-account`, `keetanetwork-crypto`, and `keetanetwork-block`. + +This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork-crypto` with `signature`, `keetanetwork-account`, `keetanetwork-asn1`, and `keetanetwork-block`. + +A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](asn1.md) holds the codec contract. + +## Falsified by + +A change to `Vote`, `VoteQuote`, `VoteStaple`, or `PossiblyExpiredVote` ownership. A change that drops the client re-export of `Vote`, `VoteQuote`, or `VoteStaple` from `keetanetwork-client/src/lib.rs`. A change to the rustdoc example in `keetanetwork-vote/src/lib.rs`. diff --git a/docs/crates/x509.md b/docs/crates/x509.md new file mode 100644 index 0000000..ce7eb77 --- /dev/null +++ b/docs/crates/x509.md @@ -0,0 +1,35 @@ +# X.509 + +## Abstract + +This page is the consumer contract for `keetanetwork-x509`. The crate owns certificate builders and stores. Account crate traits sign and verify those artifacts. Block, bindings, and the host ABI crates consume the resulting certificates. + +## Purpose + +An engineer reads this page before adding a certificate builder in another crate. After reading, the engineer knows the split between account traits and x509 builders, and which crates consume the builders. + +## Ownership + +`keetanetwork-x509` owns builders, parsers, stores, and validation for X.509 certificates. Crate rustdoc in `keetanetwork-x509/src/lib.rs` is the field reference. + +`CertSigner` and `CertVerifier` live on `keetanetwork-account`. This crate calls those traits. It does not grow a second signer trait. + +Builder, bundle, and validation cookbooks live in `keetanetwork-x509/tests/builders.rs`, `keetanetwork-x509/tests/bundles.rs`, and `keetanetwork-x509/tests/validation.rs`. + +## Who consumes this crate + +`keetanetwork-block` depends on this crate so a block can carry certificate material. `keetanetwork-bindings`, `keetanetwork-client-wasm`, and `keetanetwork-client-wasi` depend on this crate so host ABIs can project certificates. + +[Account](account.md) holds the signer and verifier traits. [Architecture](../ARCHITECTURE.md) holds the collaboration graph. + +## Feature contract + +Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`, `keetanetwork-crypto`, and `keetanetwork-account`. + +The crate build depends on `keetanetwork-utils` with the `build` feature. [Utils](utils.md) holds that helper. + +A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](asn1.md) holds the at-least-one codec contract. + +## Falsified by + +A change that moves certificate builders or stores off `keetanetwork-x509`. A change that adds a signer trait on this crate that duplicates `CertSigner` or `CertVerifier`. A change to the `der` / `rasn` forwarding in `keetanetwork-x509/Cargo.toml`. From 10c134d09f75b8b2666016c9b33f93bb0ceb06fd Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:30:46 +0000 Subject: [PATCH 07/13] docs: drop tip-frozen member counts and versions Point Architecture and Overview at Cargo.toml members and the crate note TOC. Drop the Overview version column so crate versions stay in each Cargo.toml. Co-authored-by: Tanveer Wahid --- docs/ARCHITECTURE.md | 2 +- docs/README.md | 41 ++++++++++++++++++++--------------------- 2 files changed, 21 insertions(+), 22 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7fac10d..abff37a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -16,7 +16,7 @@ An engineer reads this page to learn how work moves from an account identity thr ## Collaboration graph -The workspace lists fourteen members in root `Cargo.toml`. Twelve of those members are product crates. `keetanetwork-node` and `keetanetwork-ledger` keep reserved names. Their `lib.rs` files export no types on this tip. +Root `Cargo.toml` `[workspace].members` lists the workspace crates. Each product crate listed on [Overview](README.md) has a crate note. `keetanetwork-node` and `keetanetwork-ledger` keep reserved names. Their `lib.rs` files export no types. The arrows follow member `Cargo.toml` path dependencies that the product path uses. Foundation crates feed identity. Identity feeds signed objects. Signed objects feed the client. The client and the shared bindings crate feed the browser and WASI ABIs. diff --git a/docs/README.md b/docs/README.md index 0be5db7..1e165d9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -28,11 +28,11 @@ An engineer reads this guide in the first week on the workspace. After reading, ## What this workspace is -This repository is a Cargo workspace of Keeta Network node crates. Root `Cargo.toml` lists the workspace members. Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. +This repository is a Cargo workspace of Keeta Network node crates. Root `Cargo.toml` `[workspace].members` is the member list. Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. -Twelve members are product crates. Each product crate has one note under `docs/crates/`. `keetanetwork-node` and `keetanetwork-ledger` are empty stubs on this tip. Those crates do not hold product types. [Architecture](ARCHITECTURE.md) names that boundary. +Each product crate listed on this guide has one note under `docs/crates/`. `keetanetwork-node` and `keetanetwork-ledger` are empty stubs. Those crates do not hold product types. [Architecture](ARCHITECTURE.md) names that boundary. -Each member crate carries its own version in that crate `Cargo.toml`. This guide does not treat the unused workspace package version as the repository version. +Each member crate carries its own version in that crate `Cargo.toml`. This guide does not treat the unused workspace package version as the repository version. This table of contents does not stamp versions. The files state three license strings. Root `LICENSE` is the Keeta Token Network Community License (v1.0). Workspace `Cargo.toml` `license` is `MIT`. `keetanetwork-utils/node-harness/package.json` `license` is `Keeta Token Network Community License`. This guide cites those files as written. @@ -48,22 +48,22 @@ Crate rustdoc is the API reference. `make do-docs` generates it. This tree does These pages are the living table of contents for product crates. [Architecture](ARCHITECTURE.md) draws the graph. Each note names the crates that call that crate. -| Crate | Version on this tip | Note | -| --- | --- | --- | -| `keetanetwork-account` | `0.4.0` | [Account](crates/account.md) | -| `keetanetwork-error` | `0.2.1` | [Error](crates/error.md) | -| `keetanetwork-crypto` | `0.3.0` | [Crypto](crates/crypto.md) | -| `keetanetwork-x509` | `0.4.0` | [X.509](crates/x509.md) | -| `keetanetwork-asn1` | `0.2.5` | [ASN.1](crates/asn1.md) | -| `keetanetwork-utils` | `0.2.1` | [Utils](crates/utils.md) | -| `keetanetwork-block` | `0.4.1` | [Block](crates/block.md) | -| `keetanetwork-vote` | `0.4.0` | [Vote](crates/vote.md) | -| `keetanetwork-client` | `0.5.1` | [Client](crates/client.md) | -| `keetanetwork-bindings` | `0.4.4` | [Bindings](crates/bindings.md) | -| `keetanetwork-client-wasm` | `0.5.1` | [Client wasm](crates/client-wasm.md) | -| `keetanetwork-client-wasi` | `0.6.1` | [Client WASI](crates/client-wasi.md) | - -`keetanetwork-node` `0.2.1` and `keetanetwork-ledger` `0.2.1` have no crate note. Those `lib.rs` files export no types. +| Crate | Note | +| --- | --- | +| `keetanetwork-account` | [Account](crates/account.md) | +| `keetanetwork-error` | [Error](crates/error.md) | +| `keetanetwork-crypto` | [Crypto](crates/crypto.md) | +| `keetanetwork-x509` | [X.509](crates/x509.md) | +| `keetanetwork-asn1` | [ASN.1](crates/asn1.md) | +| `keetanetwork-utils` | [Utils](crates/utils.md) | +| `keetanetwork-block` | [Block](crates/block.md) | +| `keetanetwork-vote` | [Vote](crates/vote.md) | +| `keetanetwork-client` | [Client](crates/client.md) | +| `keetanetwork-bindings` | [Bindings](crates/bindings.md) | +| `keetanetwork-client-wasm` | [Client wasm](crates/client-wasm.md) | +| `keetanetwork-client-wasi` | [Client WASI](crates/client-wasi.md) | + +`keetanetwork-node` and `keetanetwork-ledger` have no crate note. Those `lib.rs` files export no types. ## Where the tree lives @@ -111,7 +111,7 @@ GitHub issues and pull requests stay the history home. - **Make owns the build.** Prefer the `Makefile` targets over raw tool invocations. - **The toolchain file wins after clone.** `rust-toolchain.toml` selects Rust `1.94.0`. - **Release build is `make build release=1`.** That target is not `make release`. -- **Stubs stay stubs.** `keetanetwork-node` and `keetanetwork-ledger` have no product types on this tip. +- **Stubs stay stubs.** `keetanetwork-node` and `keetanetwork-ledger` have no product types. - **rustdoc is the API reference.** This tree holds cross-file contracts. - **Packages read is a test gate.** `cargo check` and `cargo build` stay open without it. @@ -120,5 +120,4 @@ GitHub issues and pull requests stay the history home. - A change to the living documentation map that the first-week links follow. - A change to the workspace `members` list in root `Cargo.toml`. - A change that adds product types to `keetanetwork-node` or `keetanetwork-ledger`. -- A change to a product-crate version in that crate `Cargo.toml`. - A change to the license strings in root `LICENSE`, workspace `Cargo.toml`, or `keetanetwork-utils/node-harness/package.json`. From b7cc45bf2c944995ce43f483abcfec6df150bdbd Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:32:09 +0000 Subject: [PATCH 08/13] docs: drop remaining this-tip stamps Point Quickstart at the repository Makefile. Point STANDARD prose and rustdoc example links at Makefile, Cargo.toml, rust-toolchain.toml, or the cited source files in the repository. Co-authored-by: Tanveer Wahid --- docs/QUICKSTART.md | 2 +- docs/STANDARD.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index d60111a..deca61a 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -2,7 +2,7 @@ ## Abstract -This page is the install, build, test, and first-use path for the `node-rs` workspace. It records the Makefile targets that are true on this tip. It also states the GitHub Packages gate and the cargo-only path. +This page is the install, build, test, and first-use path for the `node-rs` workspace. It records the Makefile targets from the repository Makefile. It also states the GitHub Packages gate and the cargo-only path. ## Purpose diff --git a/docs/STANDARD.md b/docs/STANDARD.md index 878fd8f..af2a44c 100644 --- a/docs/STANDARD.md +++ b/docs/STANDARD.md @@ -45,7 +45,7 @@ A page uses full sentences and keeps their articles. A sentence holds one topic. A page uses the exact technical noun, in code font, on every mention of the same thing. A page uses the ASCII hyphen only and writes each relation as words. A page prefers a table, a list, or a diagram when that form reorganizes substance. -A page states contracts in the positive. A page names the command or path that is true on this tip. +A page states contracts in the positive. A page names the command or path that Makefile, Cargo.toml, rust-toolchain.toml, or the cited source file states. Each register addresses its reader differently. A page MUST hold one register throughout. @@ -80,7 +80,7 @@ A Mermaid diagram, when used, MUST give every node and participant an id that is A `///` comment MUST add signal that the signature cannot carry. It MUST NOT narrate the next line. It MUST NOT add a historical aside. Happy-path comments MUST state the contract in the positive. -Public surfaces that already have rustdoc examples MUST keep a short snippet. Full flows belong as GitHub line links into tests on the branch tip. This tree MUST NOT invent an `examples/` directory. +Public surfaces that already have rustdoc examples MUST keep a short snippet. Full flows belong as GitHub line links into tests in the repository. This tree MUST NOT invent an `examples/` directory. ## Falsified by From c8571811c863ade8b58f9b3ff90767d3c83871bb Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:37:03 +0000 Subject: [PATCH 09/13] docs: move crate architecture into each crate docs/ Place product-crate architecture under keetanetwork-*/docs/ARCHITECTURE.md with a thin docs/README.md entry. Stub node and ledger get a minimal README only. Overview is the TOC into those paths. Delete docs/crates/. Co-authored-by: Tanveer Wahid --- README.md | 2 +- docs/ARCHITECTURE.md | 46 +++++------ docs/README.md | 82 +++++++++---------- docs/STANDARD.md | 14 ++-- .../docs/ARCHITECTURE.md | 4 +- keetanetwork-account/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 4 +- keetanetwork-asn1/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 2 +- keetanetwork-bindings/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 4 +- keetanetwork-block/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 4 +- keetanetwork-client-wasi/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 4 +- keetanetwork-client-wasm/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 4 +- keetanetwork-client/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 4 +- keetanetwork-crypto/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 2 +- keetanetwork-error/docs/README.md | 5 ++ keetanetwork-ledger/docs/README.md | 5 ++ keetanetwork-node/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 6 +- keetanetwork-utils/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 4 +- keetanetwork-vote/docs/README.md | 5 ++ .../docs/ARCHITECTURE.md | 6 +- keetanetwork-x509/docs/README.md | 5 ++ 30 files changed, 164 insertions(+), 98 deletions(-) rename docs/crates/account.md => keetanetwork-account/docs/ARCHITECTURE.md (91%) create mode 100644 keetanetwork-account/docs/README.md rename docs/crates/asn1.md => keetanetwork-asn1/docs/ARCHITECTURE.md (90%) create mode 100644 keetanetwork-asn1/docs/README.md rename docs/crates/bindings.md => keetanetwork-bindings/docs/ARCHITECTURE.md (87%) create mode 100644 keetanetwork-bindings/docs/README.md rename docs/crates/block.md => keetanetwork-block/docs/ARCHITECTURE.md (85%) create mode 100644 keetanetwork-block/docs/README.md rename docs/crates/client-wasi.md => keetanetwork-client-wasi/docs/ARCHITECTURE.md (82%) create mode 100644 keetanetwork-client-wasi/docs/README.md rename docs/crates/client-wasm.md => keetanetwork-client-wasm/docs/ARCHITECTURE.md (84%) create mode 100644 keetanetwork-client-wasm/docs/README.md rename docs/crates/client.md => keetanetwork-client/docs/ARCHITECTURE.md (86%) create mode 100644 keetanetwork-client/docs/README.md rename docs/crates/crypto.md => keetanetwork-crypto/docs/ARCHITECTURE.md (90%) create mode 100644 keetanetwork-crypto/docs/README.md rename docs/crates/error.md => keetanetwork-error/docs/ARCHITECTURE.md (95%) create mode 100644 keetanetwork-error/docs/README.md create mode 100644 keetanetwork-ledger/docs/README.md create mode 100644 keetanetwork-node/docs/README.md rename docs/crates/utils.md => keetanetwork-utils/docs/ARCHITECTURE.md (85%) create mode 100644 keetanetwork-utils/docs/README.md rename docs/crates/vote.md => keetanetwork-vote/docs/ARCHITECTURE.md (87%) create mode 100644 keetanetwork-vote/docs/README.md rename docs/crates/x509.md => keetanetwork-x509/docs/ARCHITECTURE.md (83%) create mode 100644 keetanetwork-x509/docs/README.md diff --git a/README.md b/README.md index 54cf1bf..1a2b58c 100644 --- a/README.md +++ b/README.md @@ -35,5 +35,5 @@ make check - [Overview](docs/README.md) - [Quickstart](docs/QUICKSTART.md) - [Architecture](docs/ARCHITECTURE.md) -- [Crate notes](docs/README.md#crate-notes) +- [Crate docs](docs/README.md#crate-docs) - [Documentation Standard](docs/STANDARD.md) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index abff37a..7215c70 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,21 +2,21 @@ ## Abstract -This page states how the `node-rs` workspace crates depend on each other and how they collaborate on a signed write. It holds the crate-boundary graph and the interaction path that no single crate rustdoc can show. Per-crate consumer contracts live under [Crate notes](crates/account.md) and the sibling pages listed on [Overview](README.md). +This page states how the `node-rs` workspace crates depend on each other and how they collaborate on a signed write. It holds the crate-boundary graph and the interaction path that no single crate rustdoc can show. Per-crate architecture lives under each product crate `docs/ARCHITECTURE.md` listed on [Overview](README.md). ## Purpose -An engineer reads this page to learn how work moves from an account identity through a block, a vote staple, the HTTP client, and the host ABIs. After reading, the engineer can name the crate that owns each step and open the crate note that holds that crate's consumer contract. +An engineer reads this page to learn how work moves from an account identity through a block, a vote staple, the HTTP client, and the host ABIs. After reading, the engineer can name the crate that owns each step and open that crate `docs/ARCHITECTURE.md`. ## Related documents -- [Overview](README.md) for the cultural map and the crate-note table of contents. +- [Overview](README.md) for the table of contents into crate `docs/` entries. - [Quickstart](QUICKSTART.md) for install, build, test, and first use. - [Documentation Standard](STANDARD.md) for the inclusion test and page shape. ## Collaboration graph -Root `Cargo.toml` `[workspace].members` lists the workspace crates. Each product crate listed on [Overview](README.md) has a crate note. `keetanetwork-node` and `keetanetwork-ledger` keep reserved names. Their `lib.rs` files export no types. +Root `Cargo.toml` `[workspace].members` lists the workspace crates. Each product crate listed on [Overview](README.md) holds architecture under that crate `docs/ARCHITECTURE.md`. `keetanetwork-node` and `keetanetwork-ledger` keep reserved names. Their `lib.rs` files export no types. Those crates hold a minimal `docs/README.md` only. The arrows follow member `Cargo.toml` path dependencies that the product path uses. Foundation crates feed identity. Identity feeds signed objects. Signed objects feed the client. The client and the shared bindings crate feed the browser and WASI ABIs. @@ -57,7 +57,7 @@ flowchart TB `crate_node` and `crate_ledger` sit in the workspace with no product types. The `crate_client` to `crate_wasi` arrow is the `p2` feature. Feature `p1` stays on the pure surface. -Each crate note names the remaining `Cargo.toml` edges that this diagram omits, such as `keetanetwork-asn1` into `keetanetwork-block` and `keetanetwork-vote`. +Each crate architecture names the remaining `Cargo.toml` edges that this diagram omits, such as `keetanetwork-asn1` into `keetanetwork-block` and `keetanetwork-vote`. ## How the crates interact @@ -87,29 +87,29 @@ These statements are the positive feature contracts that more than one crate mus Workspace crates share the `std` and `alloc` feature names so a `no_std` consumer can stay on `alloc` through the identity and object crates. -## Crate-note homes +## Crate architecture homes -Each product crate has one note. The note holds that crate's consumer contract and the crates that call it. This page does not copy those contracts. +Each product crate holds architecture under that crate `docs/ARCHITECTURE.md`. That page holds the crate's consumer contract and the crates that call it. This page does not copy those contracts. -| Crate | Note | +| Crate | Architecture | | --- | --- | -| `keetanetwork-account` | [Account](crates/account.md) | -| `keetanetwork-error` | [Error](crates/error.md) | -| `keetanetwork-crypto` | [Crypto](crates/crypto.md) | -| `keetanetwork-x509` | [X.509](crates/x509.md) | -| `keetanetwork-asn1` | [ASN.1](crates/asn1.md) | -| `keetanetwork-utils` | [Utils](crates/utils.md) | -| `keetanetwork-block` | [Block](crates/block.md) | -| `keetanetwork-vote` | [Vote](crates/vote.md) | -| `keetanetwork-client` | [Client](crates/client.md) | -| `keetanetwork-bindings` | [Bindings](crates/bindings.md) | -| `keetanetwork-client-wasm` | [Client wasm](crates/client-wasm.md) | -| `keetanetwork-client-wasi` | [Client WASI](crates/client-wasi.md) | - -`keetanetwork-node` and `keetanetwork-ledger` have no crate note. Those `lib.rs` files export no types. This page is the home that names them as stubs. +| `keetanetwork-account` | [Account](../keetanetwork-account/docs/ARCHITECTURE.md) | +| `keetanetwork-error` | [Error](../keetanetwork-error/docs/ARCHITECTURE.md) | +| `keetanetwork-crypto` | [Crypto](../keetanetwork-crypto/docs/ARCHITECTURE.md) | +| `keetanetwork-x509` | [X.509](../keetanetwork-x509/docs/ARCHITECTURE.md) | +| `keetanetwork-asn1` | [ASN.1](../keetanetwork-asn1/docs/ARCHITECTURE.md) | +| `keetanetwork-utils` | [Utils](../keetanetwork-utils/docs/ARCHITECTURE.md) | +| `keetanetwork-block` | [Block](../keetanetwork-block/docs/ARCHITECTURE.md) | +| `keetanetwork-vote` | [Vote](../keetanetwork-vote/docs/ARCHITECTURE.md) | +| `keetanetwork-client` | [Client](../keetanetwork-client/docs/ARCHITECTURE.md) | +| `keetanetwork-bindings` | [Bindings](../keetanetwork-bindings/docs/ARCHITECTURE.md) | +| `keetanetwork-client-wasm` | [Client wasm](../keetanetwork-client-wasm/docs/ARCHITECTURE.md) | +| `keetanetwork-client-wasi` | [Client WASI](../keetanetwork-client-wasi/docs/ARCHITECTURE.md) | +| `keetanetwork-node` | [Node](../keetanetwork-node/docs/README.md) | +| `keetanetwork-ledger` | [Ledger](../keetanetwork-ledger/docs/README.md) | Crate identity, versions, and field lists live in each member `Cargo.toml` and in rustdoc. This tree does not copy those lists. ## Falsified by -A change to the workspace `members` or `exclude` lists in root `Cargo.toml`. A change that adds product types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. A change to the `compile_error!` gates in `keetanetwork-asn1/src/lib.rs`, `keetanetwork-client/src/lib.rs` (`http` runtime pairing), or `keetanetwork-client-wasi/src/lib.rs` (`p1` / `p2`). A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml`. A change to the product-crate set that [Overview](README.md) indexes under `docs/crates/`. +A change to the workspace `members` or `exclude` lists in root `Cargo.toml`. A change that adds product types to `keetanetwork-node/src/lib.rs` or `keetanetwork-ledger/src/lib.rs`. A change to the `compile_error!` gates in `keetanetwork-asn1/src/lib.rs`, `keetanetwork-client/src/lib.rs` (`http` runtime pairing), or `keetanetwork-client-wasi/src/lib.rs` (`p1` / `p2`). A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml`. A change to the product-crate set that [Overview](README.md) indexes under each crate `docs/` directory. diff --git a/docs/README.md b/docs/README.md index 1e165d9..874b6fb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,68 +2,61 @@ ## Abstract -This guide is the cultural map for the `node-rs` workspace. Invariant detail lives on [Architecture](ARCHITECTURE.md) and the crate notes. Install, build, and test steps live on [Quickstart](QUICKSTART.md). +This guide is the table of contents for the `node-rs` workspace documentation. Workspace contracts live on [Architecture](ARCHITECTURE.md), [Quickstart](QUICKSTART.md), and [Documentation Standard](STANDARD.md). Each product crate holds its architecture under that crate `docs/` directory. ## Purpose -An engineer reads this guide in the first week on the workspace. After reading, the engineer can name the page that holds each inbound question. The engineer can also find the living documentation map. +An engineer reads this guide to find the page that holds each inbound question. After reading, the engineer can open the workspace page or the crate `docs/` entry that owns that question. | Next question | The page | | --- | --- | | How do the crates depend on and call each other? | [Architecture](ARCHITECTURE.md) | | How does a reader install, build, and test? | [Quickstart](QUICKSTART.md) | | How does a writer review a page in this tree? | [Documentation Standard](STANDARD.md) | -| Where do account identities live? | [Account](crates/account.md) | -| Where do shared errors live? | [Error](crates/error.md) | -| Where do signing primitives live? | [Crypto](crates/crypto.md) | -| Where do certificate builders live? | [X.509](crates/x509.md) | -| Where does the ASN.1 codec contract live? | [ASN.1](crates/asn1.md) | -| Where do test helpers and the harness live? | [Utils](crates/utils.md) | -| Where do opening-hash and block signing live? | [Block](crates/block.md) | -| Where do vote, quote, and staple live? | [Vote](crates/vote.md) | -| Where do `KeetaClient` and HTTP generation live? | [Client](crates/client.md) | -| Where does the shared host projection live? | [Bindings](crates/bindings.md) | -| Where does the browser ABI live? | [Client wasm](crates/client-wasm.md) | -| Where does the WASI `p1` / `p2` contract live? | [Client WASI](crates/client-wasi.md) | +| Where do account identities live? | [Account](../keetanetwork-account/docs/README.md) | +| Where do shared errors live? | [Error](../keetanetwork-error/docs/README.md) | +| Where do signing primitives live? | [Crypto](../keetanetwork-crypto/docs/README.md) | +| Where do certificate builders live? | [X.509](../keetanetwork-x509/docs/README.md) | +| Where does the ASN.1 codec contract live? | [ASN.1](../keetanetwork-asn1/docs/README.md) | +| Where do test helpers and the harness live? | [Utils](../keetanetwork-utils/docs/README.md) | +| Where do opening-hash and block signing live? | [Block](../keetanetwork-block/docs/README.md) | +| Where do vote, quote, and staple live? | [Vote](../keetanetwork-vote/docs/README.md) | +| Where do `KeetaClient` and HTTP generation live? | [Client](../keetanetwork-client/docs/README.md) | +| Where does the shared host projection live? | [Bindings](../keetanetwork-bindings/docs/README.md) | +| Where does the browser ABI live? | [Client wasm](../keetanetwork-client-wasm/docs/README.md) | +| Where does the WASI `p1` / `p2` contract live? | [Client WASI](../keetanetwork-client-wasi/docs/README.md) | +| Where are the reserved stub crates named? | [Node](../keetanetwork-node/docs/README.md) and [Ledger](../keetanetwork-ledger/docs/README.md) | ## What this workspace is This repository is a Cargo workspace of Keeta Network node crates. Root `Cargo.toml` `[workspace].members` is the member list. Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. -Each product crate listed on this guide has one note under `docs/crates/`. `keetanetwork-node` and `keetanetwork-ledger` are empty stubs. Those crates do not hold product types. [Architecture](ARCHITECTURE.md) names that boundary. +Each product crate listed on this guide holds architecture on that crate `docs/ARCHITECTURE.md`. The crate `docs/README.md` is the thin entry. `keetanetwork-node` and `keetanetwork-ledger` are empty stubs. Those crates hold a minimal `docs/README.md` only. [Architecture](ARCHITECTURE.md) names that boundary. Each member crate carries its own version in that crate `Cargo.toml`. This guide does not treat the unused workspace package version as the repository version. This table of contents does not stamp versions. The files state three license strings. Root `LICENSE` is the Keeta Token Network Community License (v1.0). Workspace `Cargo.toml` `license` is `MIT`. `keetanetwork-utils/node-harness/package.json` `license` is `Keeta Token Network Community License`. This guide cites those files as written. -## How the pieces fit together +## Crate docs -Make owns the build. The [package README](../README.md) and the `Makefile` drive setup, build, check, test, and publish. [Quickstart](QUICKSTART.md) holds the commands. +These entries are the living table of contents for crate documentation. [Architecture](ARCHITECTURE.md) draws the collaboration graph. Each crate architecture names the crates that call that crate. -Crate rustdoc is the API reference. `make do-docs` generates it. This tree does not copy export lists. - -[Architecture](ARCHITECTURE.md) holds the collaboration graph and the signed-write path. Each crate note holds that crate's consumer contract. A `docs/concepts/` page lands only when it still holds a non-rustdoc invariant that Architecture and the crate notes do not already carry. - -## Crate notes - -These pages are the living table of contents for product crates. [Architecture](ARCHITECTURE.md) draws the graph. Each note names the crates that call that crate. - -| Crate | Note | +| Crate | Entry | | --- | --- | -| `keetanetwork-account` | [Account](crates/account.md) | -| `keetanetwork-error` | [Error](crates/error.md) | -| `keetanetwork-crypto` | [Crypto](crates/crypto.md) | -| `keetanetwork-x509` | [X.509](crates/x509.md) | -| `keetanetwork-asn1` | [ASN.1](crates/asn1.md) | -| `keetanetwork-utils` | [Utils](crates/utils.md) | -| `keetanetwork-block` | [Block](crates/block.md) | -| `keetanetwork-vote` | [Vote](crates/vote.md) | -| `keetanetwork-client` | [Client](crates/client.md) | -| `keetanetwork-bindings` | [Bindings](crates/bindings.md) | -| `keetanetwork-client-wasm` | [Client wasm](crates/client-wasm.md) | -| `keetanetwork-client-wasi` | [Client WASI](crates/client-wasi.md) | - -`keetanetwork-node` and `keetanetwork-ledger` have no crate note. Those `lib.rs` files export no types. +| `keetanetwork-account` | [Account](../keetanetwork-account/docs/README.md) | +| `keetanetwork-error` | [Error](../keetanetwork-error/docs/README.md) | +| `keetanetwork-crypto` | [Crypto](../keetanetwork-crypto/docs/README.md) | +| `keetanetwork-x509` | [X.509](../keetanetwork-x509/docs/README.md) | +| `keetanetwork-asn1` | [ASN.1](../keetanetwork-asn1/docs/README.md) | +| `keetanetwork-utils` | [Utils](../keetanetwork-utils/docs/README.md) | +| `keetanetwork-block` | [Block](../keetanetwork-block/docs/README.md) | +| `keetanetwork-vote` | [Vote](../keetanetwork-vote/docs/README.md) | +| `keetanetwork-client` | [Client](../keetanetwork-client/docs/README.md) | +| `keetanetwork-bindings` | [Bindings](../keetanetwork-bindings/docs/README.md) | +| `keetanetwork-client-wasm` | [Client wasm](../keetanetwork-client-wasm/docs/README.md) | +| `keetanetwork-client-wasi` | [Client WASI](../keetanetwork-client-wasi/docs/README.md) | +| `keetanetwork-node` | [Node](../keetanetwork-node/docs/README.md) | +| `keetanetwork-ledger` | [Ledger](../keetanetwork-ledger/docs/README.md) | ## Where the tree lives @@ -74,7 +67,8 @@ These pages are the living table of contents for product crates. [Architecture]( | `docs/STANDARD.md` | Documentation contract | | `docs/ARCHITECTURE.md` | Collaboration graph and interaction path | | `docs/QUICKSTART.md` | Install, build, test, and first use | -| `docs/crates/*` | Per-crate consumer contracts | +| `keetanetwork-*/docs/README.md` | Thin crate docs entry | +| `keetanetwork-*/docs/ARCHITECTURE.md` | Product-crate architecture | | `docs/concepts/*` | Single-topic pages that pass the inclusion test | GitHub issues and pull requests stay the history home. @@ -92,16 +86,16 @@ GitHub issues and pull requests stay the history home. | Change | Place | | --- | --- | -| A crate-boundary invariant | The crate source, then [Architecture](ARCHITECTURE.md) and the crate note | +| A crate-boundary invariant | The crate source, then [Architecture](ARCHITECTURE.md) and that crate `docs/ARCHITECTURE.md` | | An install or build step | `Makefile`, then [Quickstart](QUICKSTART.md) | -| A documentation page | This tree, then the next-question table on this guide. Writers follow [Documentation Standard](STANDARD.md). | +| A documentation page | This tree or the crate `docs/` directory, then the next-question table on this guide. Writers follow [Documentation Standard](STANDARD.md). | | A public type contract | rustdoc on that type | ### First-week reading order 1. This guide. 2. [Architecture](ARCHITECTURE.md). -3. The crate note for the crate under change. +3. The crate `docs/ARCHITECTURE.md` for the crate under change. 4. [Quickstart](QUICKSTART.md). 5. [Documentation Standard](STANDARD.md) before a docs edit. 6. The crate `lib.rs` rustdoc for the crate under change. diff --git a/docs/STANDARD.md b/docs/STANDARD.md index af2a44c..f6d7d3e 100644 --- a/docs/STANDARD.md +++ b/docs/STANDARD.md @@ -27,15 +27,17 @@ A page MUST NOT carry the following. The source is the one correct home for each - Barrel maps, export lists, or directory listings. - Field tables that repeat crate rustdoc without adding operator semantics. -- One README per workspace crate that only restates that crate `Cargo.toml` and `pub use`. -- A product page for `keetanetwork-node` or `keetanetwork-ledger` while those crates remain empty stubs. +- One crate-root README that only restates that crate `Cargo.toml` and `pub use`. +- A product Architecture page for `keetanetwork-node` or `keetanetwork-ledger` while those crates remain empty stubs. - A decision log, a changelog of past reviews, or a ticket or phase diary. One body of knowledge takes one page as its home. A second page that needs it MUST link to that home rather than restate it. The [Overview](README.md) names the living pages. -[Architecture](ARCHITECTURE.md) holds the workspace collaboration graph and the interaction path. A page under `docs/crates/` holds one product crate's consumer contract and the crates that call it. That page MUST add collaboration or feature-gate substance that rustdoc on a single type cannot hold. It MUST NOT restate that crate `pub use` list. +[Architecture](ARCHITECTURE.md) holds the workspace collaboration graph and the interaction path. Product-crate architecture lives under that crate `docs/ARCHITECTURE.md`. That page MUST add collaboration or feature-gate substance that rustdoc on a single type cannot hold. It MUST NOT restate that crate `pub use` list. The [Overview](README.md) is the table of contents into those paths. -A concept page under `docs/concepts/` lands only when it still holds a non-rustdoc invariant after the Architecture draft and the crate note. A candidate that collapses to a field list MUST NOT land. +A crate `docs/README.md` MAY stay a thin pointer into that crate `docs/ARCHITECTURE.md`. A stub crate MAY carry a minimal `docs/README.md` that names the reserved crate. It MUST NOT carry a product Architecture page. + +A concept page under `docs/concepts/` lands only when it still holds a non-rustdoc invariant after the workspace Architecture draft and the crate architecture. A candidate that collapses to a field list MUST NOT land. When a page must name a symbol, it cites that symbol as `Symbol` in `path/to/file`. The source carries its own detail. @@ -58,7 +60,7 @@ Each register addresses its reader differently. A page MUST hold one register th ## Page shape -Every page under `docs/**` MUST carry the following sections, in the following order. +Every shaped page under workspace `docs/` and every crate `docs/ARCHITECTURE.md` MUST carry the following sections, in the following order. 1. **Title.** The subject of the page, as a noun phrase. 2. **Abstract.** Two or three sentences on what the page holds. @@ -70,7 +72,7 @@ The closing section is the maintenance contract. It MUST name the code or tree c A page SHOULD cite the test or rustdoc example that encodes an invariant when that file is the enforcement point. One citation replaces a prose argument that the guarantee holds. -The root `README.md` MAY stay a thin pointer. It does not use this page shape. It MUST NOT redeclare Requirements Language. +The root `README.md` and each crate `docs/README.md` MAY stay a thin pointer. Those pages do not use this page shape. They MUST NOT redeclare Requirements Language. Navigation and audience live on the [Overview](README.md). This page MUST NOT carry a page index. diff --git a/docs/crates/account.md b/keetanetwork-account/docs/ARCHITECTURE.md similarity index 91% rename from docs/crates/account.md rename to keetanetwork-account/docs/ARCHITECTURE.md index 72fce8b..af6e6cf 100644 --- a/docs/crates/account.md +++ b/keetanetwork-account/docs/ARCHITECTURE.md @@ -26,13 +26,13 @@ Crate rustdoc on `keetanetwork-account/src/lib.rs` names those types. Field list | `keetanetwork-client` | `KeetaClient` and `UserClient` take an `AccountRef` | | `keetanetwork-bindings` | Host ABIs map account algorithms through this crate | -[Architecture](../ARCHITECTURE.md) holds the collaboration graph. This page does not redraw it. +[Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. This page does not redraw it. ## Feature contract Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1` and `keetanetwork-crypto`. -A `no_std` consumer enables `alloc` and at least one of `der` or `rasn` when it needs the ASN.1 path. [ASN.1](asn1.md) holds the at-least-one codec contract. +A `no_std` consumer enables `alloc` and at least one of `der` or `rasn` when it needs the ASN.1 path. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the at-least-one codec contract. This crate depends on `keetanetwork-crypto` with `signature` and `encryption`. It depends on `keetanetwork-error` and `keetanetwork-utils`. `keetanetwork-asn1` is optional behind `der` and `rasn`. diff --git a/keetanetwork-account/docs/README.md b/keetanetwork-account/docs/README.md new file mode 100644 index 0000000..c3b2dbb --- /dev/null +++ b/keetanetwork-account/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-account + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/asn1.md b/keetanetwork-asn1/docs/ARCHITECTURE.md similarity index 90% rename from docs/crates/asn1.md rename to keetanetwork-asn1/docs/ARCHITECTURE.md index d42df23..eea6812 100644 --- a/docs/crates/asn1.md +++ b/keetanetwork-asn1/docs/ARCHITECTURE.md @@ -12,7 +12,7 @@ An engineer reads this page before changing a codec feature or adding a third AS `keetanetwork-asn1` owns ASN.1 structures and codec utilities used by certificates and related encodings. Crate rustdoc in `keetanetwork-asn1/src/lib.rs` lists the features and states the at-least-one contract. -This crate depends on `keetanetwork-utils`. The `build` feature on that crate supplies generation helpers. [Utils](utils.md) holds that helper. +This crate depends on `keetanetwork-utils`. The `build` feature on that crate supplies generation helpers. [Utils](../../keetanetwork-utils/docs/ARCHITECTURE.md) holds that helper. ## Feature contract @@ -24,7 +24,7 @@ Higher crates expose `der` and `rasn` under the same names and forward them here ## Who consumes this crate -Block, vote, x509, account, crypto, and bindings crates depend on this crate when they encode or decode shared structures. [Architecture](../ARCHITECTURE.md) holds the collaboration graph. +Block, vote, x509, account, crypto, and bindings crates depend on this crate when they encode or decode shared structures. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. ## Falsified by diff --git a/keetanetwork-asn1/docs/README.md b/keetanetwork-asn1/docs/README.md new file mode 100644 index 0000000..4543d09 --- /dev/null +++ b/keetanetwork-asn1/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-asn1 + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/bindings.md b/keetanetwork-bindings/docs/ARCHITECTURE.md similarity index 87% rename from docs/crates/bindings.md rename to keetanetwork-bindings/docs/ARCHITECTURE.md index 4427b07..4c0b401 100644 --- a/docs/crates/bindings.md +++ b/keetanetwork-bindings/docs/ARCHITECTURE.md @@ -20,7 +20,7 @@ Field lists stay in rustdoc. `keetanetwork-client-wasm` depends on this crate with the `client` feature. `keetanetwork-client-wasi` depends on this crate on every build. Feature `p2` on the WASI crate also enables `keetanetwork-bindings/client`. -[Client wasm](client-wasm.md) holds the browser ABI conventions. [Client WASI](client-wasi.md) holds the `p1` / `p2` contract. [Architecture](../ARCHITECTURE.md) holds the collaboration path. +[Client wasm](../../keetanetwork-client-wasm/docs/ARCHITECTURE.md) holds the browser ABI conventions. [Client WASI](../../keetanetwork-client-wasi/docs/ARCHITECTURE.md) holds the `p1` / `p2` contract. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. ## Feature contract diff --git a/keetanetwork-bindings/docs/README.md b/keetanetwork-bindings/docs/README.md new file mode 100644 index 0000000..e5eab16 --- /dev/null +++ b/keetanetwork-bindings/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-bindings + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/block.md b/keetanetwork-block/docs/ARCHITECTURE.md similarity index 85% rename from docs/crates/block.md rename to keetanetwork-block/docs/ARCHITECTURE.md index d676e4f..0d1fda7 100644 --- a/docs/crates/block.md +++ b/keetanetwork-block/docs/ARCHITECTURE.md @@ -20,7 +20,7 @@ Field lists stay in rustdoc. `keetanetwork-vote` covers block hashes. `keetanetwork-client` assembles blocks through `TransactionBuilder` and transmits them inside a staple. `keetanetwork-bindings` and the host ABI crates project the same block types. -[Account](account.md) holds the identity types. [Vote](vote.md) holds the commitment that covers those hashes. [Architecture](../ARCHITECTURE.md) holds the collaboration path. +[Account](../../keetanetwork-account/docs/ARCHITECTURE.md) holds the identity types. [Vote](../../keetanetwork-vote/docs/ARCHITECTURE.md) holds the commitment that covers those hashes. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. ## Feature contract @@ -28,7 +28,7 @@ Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork-crypto` with `signature`, `keetanetwork-account`, `keetanetwork-asn1`, and `keetanetwork-x509`. -A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](asn1.md) holds the codec contract. +A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract. ## Falsified by diff --git a/keetanetwork-block/docs/README.md b/keetanetwork-block/docs/README.md new file mode 100644 index 0000000..130a0de --- /dev/null +++ b/keetanetwork-block/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-block + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/client-wasi.md b/keetanetwork-client-wasi/docs/ARCHITECTURE.md similarity index 82% rename from docs/crates/client-wasi.md rename to keetanetwork-client-wasi/docs/ARCHITECTURE.md index 6893eba..77c049d 100644 --- a/docs/crates/client-wasi.md +++ b/keetanetwork-client-wasi/docs/ARCHITECTURE.md @@ -18,13 +18,13 @@ Feature `p1` on `wasm32-wasip1` is a core module. It exposes the pure surface ov A WASI build enables exactly one of `p1` or `p2`. The `compile_error!` in `keetanetwork-client-wasi/src/lib.rs` is the enforcement point. Off a WASI target both features compile out and leave `pure`. -Host tests live under `keetanetwork-client-wasi/host-tests/`. [Quickstart](../QUICKSTART.md) names `make build-wasi` and `make test-wasi`. Those targets select `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. +Host tests live under `keetanetwork-client-wasi/host-tests/`. [Quickstart](../../docs/QUICKSTART.md) names `make build-wasi` and `make test-wasi`. Those targets select `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. ## Who this crate projects This crate always depends on `keetanetwork-account`, `keetanetwork-block`, `keetanetwork-crypto`, `keetanetwork-vote`, `keetanetwork-x509`, and `keetanetwork-bindings`. Feature `p2` adds `keetanetwork-client`. -[Client](client.md) holds the `wasi` feature that supplies codec types without Tokio. [Bindings](bindings.md) holds the shared projection. [Architecture](../ARCHITECTURE.md) holds the collaboration path. +[Client](../../keetanetwork-client/docs/ARCHITECTURE.md) holds the `wasi` feature that supplies codec types without Tokio. [Bindings](../../keetanetwork-bindings/docs/ARCHITECTURE.md) holds the shared projection. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. ## Feature contract diff --git a/keetanetwork-client-wasi/docs/README.md b/keetanetwork-client-wasi/docs/README.md new file mode 100644 index 0000000..864f9b3 --- /dev/null +++ b/keetanetwork-client-wasi/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-client-wasi + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/client-wasm.md b/keetanetwork-client-wasm/docs/ARCHITECTURE.md similarity index 84% rename from docs/crates/client-wasm.md rename to keetanetwork-client-wasm/docs/ARCHITECTURE.md index e7e7f1c..97f8b74 100644 --- a/docs/crates/client-wasm.md +++ b/keetanetwork-client-wasm/docs/ARCHITECTURE.md @@ -14,13 +14,13 @@ An engineer reads this page before changing the browser ABI or adding a JavaScri Amounts are decimal strings such as `"1000"`. They are not JavaScript `number` values. Cryptographic bytes are `Uint8Array`. Hashes and keys are hex strings. Errors are JavaScript `Error` objects that carry a stable `error.code`. -`make build-wasm` runs `wasm-pack build` for this crate. Playwright cookbooks live in `keetanetwork-client-wasm/tests/roundtrip.spec.ts` and `keetanetwork-client-wasm/tests/fee.spec.ts`. [Quickstart](../QUICKSTART.md) names the Make targets and the Packages gate. +`make build-wasm` runs `wasm-pack build` for this crate. Playwright cookbooks live in `keetanetwork-client-wasm/tests/roundtrip.spec.ts` and `keetanetwork-client-wasm/tests/fee.spec.ts`. [Quickstart](../../docs/QUICKSTART.md) names the Make targets and the Packages gate. ## Who this crate projects This crate depends on `keetanetwork-client` with the `wasm` feature. It depends on `keetanetwork-bindings` with the `client` feature. It also depends on `keetanetwork-account`, `keetanetwork-block`, `keetanetwork-crypto`, `keetanetwork-x509`, and `keetanetwork-asn1`. -[Client](client.md) holds the orchestrator and the `http` plus `wasm` pairing. [Bindings](bindings.md) holds the shared projection. [Architecture](../ARCHITECTURE.md) holds the collaboration path. +[Client](../../keetanetwork-client/docs/ARCHITECTURE.md) holds the orchestrator and the `http` plus `wasm` pairing. [Bindings](../../keetanetwork-bindings/docs/ARCHITECTURE.md) holds the shared projection. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. ## Feature contract diff --git a/keetanetwork-client-wasm/docs/README.md b/keetanetwork-client-wasm/docs/README.md new file mode 100644 index 0000000..d87e23b --- /dev/null +++ b/keetanetwork-client-wasm/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-client-wasm + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/client.md b/keetanetwork-client/docs/ARCHITECTURE.md similarity index 86% rename from docs/crates/client.md rename to keetanetwork-client/docs/ARCHITECTURE.md index b6a9728..5f7a577 100644 --- a/docs/crates/client.md +++ b/keetanetwork-client/docs/ARCHITECTURE.md @@ -14,7 +14,7 @@ An engineer reads this page before changing client construction, HTTP generation HTTP transport is generated at build time from `keetanetwork-client/openapi/keetanet-node.yaml` through progenitor. The generated types are exposed as the `generated` module when the `codec` feature is on. -The rustdoc example in `keetanetwork-client/src/lib.rs` constructs `KeetaClient::new("http://localhost:8080/api")` and `.with_network(0u8)`. A live harness cookbook lives in `keetanetwork-client/tests/e2e.rs`. `UserClient` signing tests live in `keetanetwork-client/tests/user_signing.rs`. [Quickstart](../QUICKSTART.md) cites those examples. +The rustdoc example in `keetanetwork-client/src/lib.rs` constructs `KeetaClient::new("http://localhost:8080/api")` and `.with_network(0u8)`. A live harness cookbook lives in `keetanetwork-client/tests/e2e.rs`. `UserClient` signing tests live in `keetanetwork-client/tests/user_signing.rs`. [Quickstart](../../docs/QUICKSTART.md) cites those examples. The crate re-exports `Vote`, `VoteQuote`, `VoteStaple`, and `VoteBlockHash` from `keetanetwork-vote`. It also re-exports `KeetaNetError` and `NodeErrorType` from `keetanetwork-error`. @@ -30,7 +30,7 @@ The orchestrator is `no_std` plus `alloc` when `std`, `http`, and `wasi` are off `keetanetwork-client-wasm` enables the `wasm` feature. `keetanetwork-client-wasi` enables this crate only on feature `p2`. `keetanetwork-bindings` takes this crate behind its `client` feature. -[Block](block.md) and [Vote](vote.md) hold the signed objects. [Bindings](bindings.md) holds the shared host projection. [Architecture](../ARCHITECTURE.md) holds the collaboration path. +[Block](../../keetanetwork-block/docs/ARCHITECTURE.md) and [Vote](../../keetanetwork-vote/docs/ARCHITECTURE.md) hold the signed objects. [Bindings](../../keetanetwork-bindings/docs/ARCHITECTURE.md) holds the shared host projection. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. ## Falsified by diff --git a/keetanetwork-client/docs/README.md b/keetanetwork-client/docs/README.md new file mode 100644 index 0000000..494fd2d --- /dev/null +++ b/keetanetwork-client/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-client + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/crypto.md b/keetanetwork-crypto/docs/ARCHITECTURE.md similarity index 90% rename from docs/crates/crypto.md rename to keetanetwork-crypto/docs/ARCHITECTURE.md index 40490b3..25178bc 100644 --- a/docs/crates/crypto.md +++ b/keetanetwork-crypto/docs/ARCHITECTURE.md @@ -27,7 +27,7 @@ Field lists stay in rustdoc. | `keetanetwork-client` | Depends on `alloc` for client-side hashing | | `keetanetwork-bindings` | Depends on `alloc` and `signature` for host ABIs | -[Architecture](../ARCHITECTURE.md) holds the collaboration graph. +[Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. ## Feature contract @@ -35,7 +35,7 @@ Default features are `std`, `signature`, `encryption`, and `rasn`. `std` implies `keetanetwork-error` is optional and comes on with `std`. `keetanetwork-utils` is a path dependency. -A `no_std` consumer enables `alloc` plus `signature` or `encryption` as the call site needs. [ASN.1](asn1.md) holds the codec contract when `der` or `rasn` is on. +A `no_std` consumer enables `alloc` plus `signature` or `encryption` as the call site needs. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract when `der` or `rasn` is on. ## Falsified by diff --git a/keetanetwork-crypto/docs/README.md b/keetanetwork-crypto/docs/README.md new file mode 100644 index 0000000..7075e4b --- /dev/null +++ b/keetanetwork-crypto/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-crypto + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/error.md b/keetanetwork-error/docs/ARCHITECTURE.md similarity index 95% rename from docs/crates/error.md rename to keetanetwork-error/docs/ARCHITECTURE.md index a6eead6..b830ae8 100644 --- a/docs/crates/error.md +++ b/keetanetwork-error/docs/ARCHITECTURE.md @@ -20,7 +20,7 @@ Field lists and variant payloads stay in rustdoc. `keetanetwork-crypto` takes this crate only when the `std` feature is on. -[Architecture](../ARCHITECTURE.md) holds the collaboration graph. +[Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. ## Feature contract diff --git a/keetanetwork-error/docs/README.md b/keetanetwork-error/docs/README.md new file mode 100644 index 0000000..8593917 --- /dev/null +++ b/keetanetwork-error/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-error + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/keetanetwork-ledger/docs/README.md b/keetanetwork-ledger/docs/README.md new file mode 100644 index 0000000..6e337d8 --- /dev/null +++ b/keetanetwork-ledger/docs/README.md @@ -0,0 +1,5 @@ +# Ledger + +`keetanetwork-ledger` is a reserved crate name. `keetanetwork-ledger/src/lib.rs` exports no types. + +[Workspace architecture](../../docs/ARCHITECTURE.md) names that boundary. diff --git a/keetanetwork-node/docs/README.md b/keetanetwork-node/docs/README.md new file mode 100644 index 0000000..3a0bc88 --- /dev/null +++ b/keetanetwork-node/docs/README.md @@ -0,0 +1,5 @@ +# Node + +`keetanetwork-node` is a reserved crate name. `keetanetwork-node/src/lib.rs` exports no types. + +[Workspace architecture](../../docs/ARCHITECTURE.md) names that boundary. diff --git a/docs/crates/utils.md b/keetanetwork-utils/docs/ARCHITECTURE.md similarity index 85% rename from docs/crates/utils.md rename to keetanetwork-utils/docs/ARCHITECTURE.md index f746587..7204234 100644 --- a/docs/crates/utils.md +++ b/keetanetwork-utils/docs/ARCHITECTURE.md @@ -2,7 +2,7 @@ ## Abstract -This page is the consumer contract for `keetanetwork-utils`. The crate owns shared test macros, optional ASN.1 build helpers, and the `node-harness` feature that talks to the private GitHub Packages package. [Quickstart](../QUICKSTART.md) holds the operator steps for that gate. +This page is the consumer contract for `keetanetwork-utils`. The crate owns shared test macros, optional ASN.1 build helpers, and the `node-harness` feature that talks to the private GitHub Packages package. [Quickstart](../../docs/QUICKSTART.md) holds the operator steps for that gate. ## Purpose @@ -14,13 +14,13 @@ An engineer reads this page before adding a workspace-wide test helper or changi Feature `build` enables `rasn-compiler` and the `build` module. `keetanetwork-asn1` and `keetanetwork-x509` use that feature from their build scripts. -Feature `node-harness` enables the harness client. `keetanetwork-utils/node-harness/.npmrc` sets `@keetanetwork:registry=https://npm.pkg.github.com`. [Quickstart](../QUICKSTART.md) holds the Packages token steps and the cargo-only path. +Feature `node-harness` enables the harness client. `keetanetwork-utils/node-harness/.npmrc` sets `@keetanetwork:registry=https://npm.pkg.github.com`. [Quickstart](../../docs/QUICKSTART.md) holds the Packages token steps and the cargo-only path. ## Who consumes this crate Account, crypto, asn1, x509, block, and vote crates depend on this crate for shared helpers. Test binaries enable `std` and `node-harness` when they talk to a live node. -This crate is not on the signed-write collaboration path in [Architecture](../ARCHITECTURE.md). It is the shared tooling under that path. +This crate is not on the signed-write collaboration path in [Architecture](../../docs/ARCHITECTURE.md). It is the shared tooling under that path. ## Feature contract diff --git a/keetanetwork-utils/docs/README.md b/keetanetwork-utils/docs/README.md new file mode 100644 index 0000000..2db532e --- /dev/null +++ b/keetanetwork-utils/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-utils + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/vote.md b/keetanetwork-vote/docs/ARCHITECTURE.md similarity index 87% rename from docs/crates/vote.md rename to keetanetwork-vote/docs/ARCHITECTURE.md index 4085933..ba0f251 100644 --- a/docs/crates/vote.md +++ b/keetanetwork-vote/docs/ARCHITECTURE.md @@ -20,7 +20,7 @@ Cookbooks live in `keetanetwork-vote/tests/e2e_node.rs`, `keetanetwork-vote/test `keetanetwork-client` depends on this crate and re-exports `Vote`, `VoteQuote`, `VoteStaple`, and `VoteBlockHash` from `keetanetwork-client/src/lib.rs`. `keetanetwork-bindings` and `keetanetwork-client-wasi` depend on this crate so host ABIs can project vote types. -[Block](block.md) holds the hashes a vote covers. [Client](client.md) holds the transmit path. [Architecture](../ARCHITECTURE.md) holds the collaboration path. +[Block](../../keetanetwork-block/docs/ARCHITECTURE.md) holds the hashes a vote covers. [Client](../../keetanetwork-client/docs/ARCHITECTURE.md) holds the transmit path. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. ## Feature contract @@ -28,7 +28,7 @@ Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork-crypto` with `signature`, `keetanetwork-account`, `keetanetwork-asn1`, and `keetanetwork-block`. -A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](asn1.md) holds the codec contract. +A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract. ## Falsified by diff --git a/keetanetwork-vote/docs/README.md b/keetanetwork-vote/docs/README.md new file mode 100644 index 0000000..4c24ee5 --- /dev/null +++ b/keetanetwork-vote/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-vote + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). diff --git a/docs/crates/x509.md b/keetanetwork-x509/docs/ARCHITECTURE.md similarity index 83% rename from docs/crates/x509.md rename to keetanetwork-x509/docs/ARCHITECTURE.md index ce7eb77..4bf61e7 100644 --- a/docs/crates/x509.md +++ b/keetanetwork-x509/docs/ARCHITECTURE.md @@ -20,15 +20,15 @@ Builder, bundle, and validation cookbooks live in `keetanetwork-x509/tests/build `keetanetwork-block` depends on this crate so a block can carry certificate material. `keetanetwork-bindings`, `keetanetwork-client-wasm`, and `keetanetwork-client-wasi` depend on this crate so host ABIs can project certificates. -[Account](account.md) holds the signer and verifier traits. [Architecture](../ARCHITECTURE.md) holds the collaboration graph. +[Account](../../keetanetwork-account/docs/ARCHITECTURE.md) holds the signer and verifier traits. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. ## Feature contract Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`, `keetanetwork-crypto`, and `keetanetwork-account`. -The crate build depends on `keetanetwork-utils` with the `build` feature. [Utils](utils.md) holds that helper. +The crate build depends on `keetanetwork-utils` with the `build` feature. [Utils](../../keetanetwork-utils/docs/ARCHITECTURE.md) holds that helper. -A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](asn1.md) holds the at-least-one codec contract. +A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the at-least-one codec contract. ## Falsified by diff --git a/keetanetwork-x509/docs/README.md b/keetanetwork-x509/docs/README.md new file mode 100644 index 0000000..4f9d9c7 --- /dev/null +++ b/keetanetwork-x509/docs/README.md @@ -0,0 +1,5 @@ +# keetanetwork-x509 + +Crate architecture lives on [Architecture](ARCHITECTURE.md). + +Workspace map: [Overview](../../docs/README.md). From 026e4bfdd77b12c874dd8317359e0abcffd9e31f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:40:28 +0000 Subject: [PATCH 10/13] docs: drop concepts path from Overview tree table The living map lists only pages that exist. STANDARD still states when a future concept page may land. Co-authored-by: Tanveer Wahid --- docs/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 874b6fb..f679c7f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -69,7 +69,6 @@ These entries are the living table of contents for crate documentation. [Archite | `docs/QUICKSTART.md` | Install, build, test, and first use | | `keetanetwork-*/docs/README.md` | Thin crate docs entry | | `keetanetwork-*/docs/ARCHITECTURE.md` | Product-crate architecture | -| `docs/concepts/*` | Single-topic pages that pass the inclusion test | GitHub issues and pull requests stay the history home. From 53283e7b3986803078cb15400c7b11026b25c410 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:44:51 +0000 Subject: [PATCH 11/13] docs: give product crate READMEs purpose, tests, examples Replace three-line crate docs entries with purpose, feature and test commands, and an inline rustdoc or test example. Keep node and ledger stub READMEs minimal. Co-authored-by: Tanveer Wahid --- docs/README.md | 2 +- docs/STANDARD.md | 4 +- keetanetwork-account/docs/ARCHITECTURE.md | 18 +++++++ keetanetwork-account/docs/README.md | 38 ++++++++++++- keetanetwork-asn1/docs/ARCHITECTURE.md | 12 +++++ keetanetwork-asn1/docs/README.md | 32 ++++++++++- keetanetwork-bindings/docs/ARCHITECTURE.md | 11 ++++ keetanetwork-bindings/docs/README.md | 26 ++++++++- keetanetwork-block/docs/ARCHITECTURE.md | 25 +++++++++ keetanetwork-block/docs/README.md | 54 ++++++++++++++++++- keetanetwork-client-wasi/docs/ARCHITECTURE.md | 14 +++++ keetanetwork-client-wasi/docs/README.md | 33 +++++++++++- keetanetwork-client-wasm/docs/ARCHITECTURE.md | 12 +++++ keetanetwork-client-wasm/docs/README.md | 40 +++++++++++++- keetanetwork-client/docs/ARCHITECTURE.md | 10 ++++ keetanetwork-client/docs/README.md | 45 +++++++++++++++- keetanetwork-crypto/docs/ARCHITECTURE.md | 11 ++++ keetanetwork-crypto/docs/README.md | 34 +++++++++++- keetanetwork-error/docs/ARCHITECTURE.md | 17 ++++++ keetanetwork-error/docs/README.md | 32 ++++++++++- keetanetwork-utils/docs/ARCHITECTURE.md | 23 ++++++++ keetanetwork-utils/docs/README.md | 47 +++++++++++++++- keetanetwork-vote/docs/ARCHITECTURE.md | 25 +++++++++ keetanetwork-vote/docs/README.md | 44 ++++++++++++++- keetanetwork-x509/docs/ARCHITECTURE.md | 30 +++++++++++ keetanetwork-x509/docs/README.md | 34 +++++++++++- 26 files changed, 646 insertions(+), 27 deletions(-) diff --git a/docs/README.md b/docs/README.md index f679c7f..b92d622 100644 --- a/docs/README.md +++ b/docs/README.md @@ -67,7 +67,7 @@ These entries are the living table of contents for crate documentation. [Archite | `docs/STANDARD.md` | Documentation contract | | `docs/ARCHITECTURE.md` | Collaboration graph and interaction path | | `docs/QUICKSTART.md` | Install, build, test, and first use | -| `keetanetwork-*/docs/README.md` | Thin crate docs entry | +| `keetanetwork-*/docs/README.md` | Crate purpose, quickstart, and example | | `keetanetwork-*/docs/ARCHITECTURE.md` | Product-crate architecture | GitHub issues and pull requests stay the history home. diff --git a/docs/STANDARD.md b/docs/STANDARD.md index f6d7d3e..0d23814 100644 --- a/docs/STANDARD.md +++ b/docs/STANDARD.md @@ -35,7 +35,7 @@ One body of knowledge takes one page as its home. A second page that needs it MU [Architecture](ARCHITECTURE.md) holds the workspace collaboration graph and the interaction path. Product-crate architecture lives under that crate `docs/ARCHITECTURE.md`. That page MUST add collaboration or feature-gate substance that rustdoc on a single type cannot hold. It MUST NOT restate that crate `pub use` list. The [Overview](README.md) is the table of contents into those paths. -A crate `docs/README.md` MAY stay a thin pointer into that crate `docs/ARCHITECTURE.md`. A stub crate MAY carry a minimal `docs/README.md` that names the reserved crate. It MUST NOT carry a product Architecture page. +A product-crate `docs/README.md` MUST state what the crate is for. It MUST name the features and the `cargo test -p` command or Make target. It MUST include at least one fenced code example copied from crate rustdoc or a test. It MUST link to that crate `docs/ARCHITECTURE.md` and the workspace [Overview](README.md). A stub crate MAY carry a minimal `docs/README.md` that names the reserved crate. It MUST NOT carry a product Architecture page. A concept page under `docs/concepts/` lands only when it still holds a non-rustdoc invariant after the workspace Architecture draft and the crate architecture. A candidate that collapses to a field list MUST NOT land. @@ -72,7 +72,7 @@ The closing section is the maintenance contract. It MUST name the code or tree c A page SHOULD cite the test or rustdoc example that encodes an invariant when that file is the enforcement point. One citation replaces a prose argument that the guarantee holds. -The root `README.md` and each crate `docs/README.md` MAY stay a thin pointer. Those pages do not use this page shape. They MUST NOT redeclare Requirements Language. +The root `README.md` MAY stay a thin pointer. A stub crate `docs/README.md` MAY stay a thin pointer. Those pages do not use this page shape. They MUST NOT redeclare Requirements Language. A product-crate `docs/README.md` uses the crate-entry sections above instead of this page shape. Navigation and audience live on the [Overview](README.md). This page MUST NOT carry a page index. diff --git a/keetanetwork-account/docs/ARCHITECTURE.md b/keetanetwork-account/docs/ARCHITECTURE.md index af6e6cf..5e241aa 100644 --- a/keetanetwork-account/docs/ARCHITECTURE.md +++ b/keetanetwork-account/docs/ARCHITECTURE.md @@ -40,6 +40,24 @@ This crate depends on `keetanetwork-crypto` with `signature` and `encryption`. I Account seed, identifier, and signature cookbooks live in `keetanetwork-account/tests/account_creation.rs`, `keetanetwork-account/tests/seed_derivation.rs`, `keetanetwork-account/tests/identifier_accounts.rs`, and `keetanetwork-account/tests/signatures.rs`. +## Example + +From `keetanetwork-account/src/account.rs` rustdoc. + +```rust +use keetanetwork_account::{Account, KeyED25519}; +use keetanetwork_crypto::algorithms::ed25519::Ed25519Derivation; +use keetanetwork_crypto::prelude::KeyDerivation; +use keetanetwork_crypto::utils::generate_random_seed; + +let seed = generate_random_seed()?; +let private_key = Ed25519Derivation::derive_from_seed(seed)?; +let account = Account::::from(private_key); +let signature = account.sign(b"hello", None)?; +assert!(account.verify(b"hello", &signature, None).is_ok()); +# Ok::<(), Box>(()) +``` + ## Falsified by A change that moves `Account`, `GenericAccount`, `KeyPairType`, `CertSigner`, or `CertVerifier` off this crate. A change that adds a second identity model in `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, `keetanetwork-client`, or `keetanetwork-bindings`. A change to the `der` / `rasn` forwarding in `keetanetwork-account/Cargo.toml`. diff --git a/keetanetwork-account/docs/README.md b/keetanetwork-account/docs/README.md index c3b2dbb..d2043bb 100644 --- a/keetanetwork-account/docs/README.md +++ b/keetanetwork-account/docs/README.md @@ -1,5 +1,39 @@ # keetanetwork-account -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns typed and type-erased identities for the workspace. `Account` is bound to one `KeyPairType`. `GenericAccount` is the type-erased account used at crate boundaries. `CertSigner` and `CertVerifier` sign and verify X.509-shaped artifacts. Block, vote, x509, client, and bindings crates consume these identities. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`. + +```bash +cargo test -p keetanetwork-account +``` + +`make test-feat` also runs this crate with `std,der` and `std,rasn`. + +## Example + +From `keetanetwork-account/src/account.rs` rustdoc. + +```rust +use keetanetwork_account::{Account, KeyED25519}; +use keetanetwork_crypto::algorithms::ed25519::Ed25519Derivation; +use keetanetwork_crypto::prelude::KeyDerivation; +use keetanetwork_crypto::utils::generate_random_seed; + +let seed = generate_random_seed()?; +let private_key = Ed25519Derivation::derive_from_seed(seed)?; +let account = Account::::from(private_key); + +let message = b"Hello, Keeta Network!"; +let signature = account.sign(message, None)?; +let is_valid = account.verify(message, &signature, None); +assert!(is_valid.is_ok()); +# Ok::<(), Box>(()) +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-asn1/docs/ARCHITECTURE.md b/keetanetwork-asn1/docs/ARCHITECTURE.md index eea6812..7c97a87 100644 --- a/keetanetwork-asn1/docs/ARCHITECTURE.md +++ b/keetanetwork-asn1/docs/ARCHITECTURE.md @@ -26,6 +26,18 @@ Higher crates expose `der` and `rasn` under the same names and forward them here Block, vote, x509, account, crypto, and bindings crates depend on this crate when they encode or decode shared structures. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. +## Example + +From `keetanetwork-asn1/tests/vote_codec_vectors.rs` `test_vote_staple_reference_bytes`. + +```rust +use keetanetwork_asn1::vote::{codec, VoteStapleBundle}; + +let bundle = VoteStapleBundle { blocks: vec![vec![1, 2, 3]], votes: vec![vec![4, 5, 6]] }; +let encoded = codec::encode_vote_staple(&bundle).expect("encode staple"); +assert!(!encoded.is_empty()); +``` + ## Falsified by A change to the `compile_error!` in `keetanetwork-asn1/src/lib.rs` that no longer requires at least one of `der` or `rasn`. A change that adds a third codec feature without updating this page and the rustdoc feature list. A change that stops `keetanetwork-account`, `keetanetwork-block`, or `keetanetwork-vote` from forwarding `der` and `rasn` here. diff --git a/keetanetwork-asn1/docs/README.md b/keetanetwork-asn1/docs/README.md index 4543d09..d2bd020 100644 --- a/keetanetwork-asn1/docs/README.md +++ b/keetanetwork-asn1/docs/README.md @@ -1,5 +1,33 @@ # keetanetwork-asn1 -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns the encoding codecs that identity, certificate, block, and vote types share. A build enables at least one of `der` or `rasn`. Both features may be on together. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features are `std`, `serde`, and `rasn`. Enable at least one of `der` or `rasn`. + +```bash +cargo test -p keetanetwork-asn1 +``` + +`make test-feat` also runs this crate with `std,der` and `std,rasn`. + +## Example + +From `keetanetwork-asn1/tests/vote_codec_vectors.rs` `staple` and `test_vote_staple_reference_bytes`. + +```rust +use keetanetwork_asn1::vote::{codec, VoteStapleBundle}; + +let bundle = VoteStapleBundle { + blocks: vec![vec![1, 2, 3]], + votes: vec![vec![4, 5, 6]], +}; +let encoded = codec::encode_vote_staple(&bundle).expect("encode staple"); +assert!(!encoded.is_empty()); +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-bindings/docs/ARCHITECTURE.md b/keetanetwork-bindings/docs/ARCHITECTURE.md index 4c0b401..85e9a66 100644 --- a/keetanetwork-bindings/docs/ARCHITECTURE.md +++ b/keetanetwork-bindings/docs/ARCHITECTURE.md @@ -28,6 +28,17 @@ Default features include `std`. Feature `client` is opt-in and enables `keetanet A target crate that only needs the pure projection leaves `client` off. A target crate that needs the HTTP orchestrator enables `client`. +## Example + +From `keetanetwork-bindings/src/parse.rs` `amount_round_trips_decimal_strings`. + +```rust +use keetanetwork_bindings::parse::{amount, amount_to_string}; + +let parsed = amount("1000").expect("a decimal string must parse"); +assert_eq!(amount_to_string(parsed), "1000"); +``` + ## Falsified by A change that moves account-algorithm mapping or core-error reduction into `keetanetwork-client-wasm` or `keetanetwork-client-wasi` without this crate. A change to the `client` feature in `keetanetwork-bindings/Cargo.toml`. A change that drops this crate from either host ABI crate. diff --git a/keetanetwork-bindings/docs/README.md b/keetanetwork-bindings/docs/README.md index e5eab16..173bc39 100644 --- a/keetanetwork-bindings/docs/README.md +++ b/keetanetwork-bindings/docs/README.md @@ -1,5 +1,27 @@ # keetanetwork-bindings -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate is the shared, target-agnostic projection used by the browser and WASI ABIs. It owns input parsing, account-algorithm mapping, and core-error reduction so those ABIs do not each grow a second copy. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features include `std`. Feature `client` is opt-in and enables `keetanetwork-client`. + +```bash +cargo test -p keetanetwork-bindings +``` + +## Example + +From `keetanetwork-bindings/src/parse.rs` `amount_round_trips_decimal_strings`. + +```rust +use keetanetwork_bindings::parse::{amount, amount_to_string}; + +let parsed = amount("1000").expect("a decimal string must parse"); +assert_eq!(amount_to_string(parsed), "1000"); +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-block/docs/ARCHITECTURE.md b/keetanetwork-block/docs/ARCHITECTURE.md index 0d1fda7..e98d751 100644 --- a/keetanetwork-block/docs/ARCHITECTURE.md +++ b/keetanetwork-block/docs/ARCHITECTURE.md @@ -30,6 +30,31 @@ This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork- A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract. +## Example + +From `keetanetwork-block/src/lib.rs` rustdoc. + +```rust +use keetanetwork_account::{Account, Accountable, GenericAccount, KeyED25519, KeyPairType, Keyable}; +use keetanetwork_block::{AccountRef, BlockBuilder}; +use keetanetwork_crypto::prelude::IntoSecret; + +let seed = [7u8; 32].into_secret(); +let account = Account::::try_from(Accountable::KeyAndType( + Keyable::Seed((seed, 0)), + KeyPairType::ED25519, +))?; +let account = AccountRef::from(GenericAccount::Ed25519(account)); +let unsigned = BlockBuilder::default() + .with_network(0u8) + .with_account(account) + .as_opening() + .build()?; +let block = unsigned.sign()?; +assert!(!block.to_bytes().is_empty()); +# Ok::<(), keetanetwork_block::BlockError>(()) +``` + ## Falsified by A change to `Block`, `BlockBuilder`, `Operation`, or `AccountRef` ownership. A change that lets `keetanetwork-client` compute an opening hash without this crate. A change to the rustdoc example in `keetanetwork-block/src/lib.rs`. A change to the `der` / `rasn` forwarding in `keetanetwork-block/Cargo.toml`. diff --git a/keetanetwork-block/docs/README.md b/keetanetwork-block/docs/README.md index 130a0de..5882648 100644 --- a/keetanetwork-block/docs/README.md +++ b/keetanetwork-block/docs/README.md @@ -1,5 +1,55 @@ # keetanetwork-block -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns `Block`, `BlockBuilder`, `Operation`, and `AccountRef`. Opening-hash and signing rules live here. The client builder uses the same rules when it assembles a first block or a successor. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features are `std` and `rasn`. `std` implies `alloc`. + +```bash +cargo test -p keetanetwork-block +``` + +`make test-feat` also runs this crate with `std,der` and `std,rasn`. + +## Example + +From `keetanetwork-block/src/lib.rs` rustdoc. + +```rust +use keetanetwork_account::{Account, Accountable, GenericAccount, KeyED25519, KeyPairType, Keyable}; +use keetanetwork_block::{AccountRef, Block, BlockBuilder, Receive}; +use keetanetwork_crypto::hash::Hashable; +use keetanetwork_crypto::prelude::IntoSecret; + +let seed = [7u8; 32].into_secret(); +let account = Account::::try_from(Accountable::KeyAndType( + Keyable::Seed((seed, 0)), + KeyPairType::ED25519, +))?; +let token = account.generate_identifier(KeyPairType::TOKEN, None, 0)?; +let account = AccountRef::from(GenericAccount::Ed25519(account)); + +let unsigned = BlockBuilder::default() + .with_network(0u8) + .with_account(account.clone()) + .as_opening() + .with_operation(Receive { + amount: 10u64.into(), + token: token.into(), + from: account.clone(), + exact: false, + forward: None, + }) + .build()?; + +let block = unsigned.sign()?; +let decoded = Block::try_from(block.to_bytes())?; +assert_eq!(decoded.hash(), block.hash()); +# Ok::<(), keetanetwork_block::BlockError>(()) +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-client-wasi/docs/ARCHITECTURE.md b/keetanetwork-client-wasi/docs/ARCHITECTURE.md index 77c049d..e1f5a95 100644 --- a/keetanetwork-client-wasi/docs/ARCHITECTURE.md +++ b/keetanetwork-client-wasi/docs/ARCHITECTURE.md @@ -30,6 +30,20 @@ This crate always depends on `keetanetwork-account`, `keetanetwork-block`, `keet Select exactly one of `p1` or `p2` per WASI build. Feature `p2` is the only edge from this crate to `keetanetwork-client`. Feature `p1` stays on the pure surface. +## Example + +From `keetanetwork-bindings/src/account.rs` `account_round_trips_through_seed_and_public_key_string`, re-exported by `keetanetwork-client-wasi/src/pure.rs`. + +```rust +use keetanetwork_client_wasi::pure; + +let seed = pure::generate_seed().expect("seed generation must succeed"); +let account = pure::account_from_seed(&seed, 0, pure::DEFAULT_ALGORITHM) + .expect("account derivation must succeed"); +let public_key_string = pure::account_public_key_string(&account); +assert!(!public_key_string.is_empty()); +``` + ## Falsified by A change to the `compile_error!` in `keetanetwork-client-wasi/src/lib.rs`. A change that lets a WASI build enable both `p1` and `p2`, or neither. A change that pulls `keetanetwork-client` on feature `p1`. A change to the `p1` / `p2` selection in the `Makefile` `build-wasi` or `test-wasi` targets. diff --git a/keetanetwork-client-wasi/docs/README.md b/keetanetwork-client-wasi/docs/README.md index 864f9b3..7e85d79 100644 --- a/keetanetwork-client-wasi/docs/README.md +++ b/keetanetwork-client-wasi/docs/README.md @@ -1,5 +1,34 @@ # keetanetwork-client-wasi -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate is the WASI ABI over a shared `pure` module. A WASI build selects exactly one of `p1` or `p2`. Feature `p2` pulls `keetanetwork-client`. Feature `p1` stays on the pure surface. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Select exactly one of `p1` or `p2` per WASI build. + +```bash +make build-wasi +make test-wasi +``` + +Those Make targets select `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. They need GitHub Packages read. Off a WASI target both features compile out and leave `pure`. + +```bash +cargo test -p keetanetwork-client-wasi +``` + +## Example + +From `keetanetwork-client-wasi/src/pure.rs` re-export of `keetanetwork-bindings/src/account.rs` `generated_seed_is_32_byte_hex`. + +```rust +use keetanetwork_client_wasi::pure; + +let seed = pure::generate_seed().expect("seed generation must succeed"); +assert_eq!(seed.len(), 64); +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-client-wasm/docs/ARCHITECTURE.md b/keetanetwork-client-wasm/docs/ARCHITECTURE.md index 97f8b74..e81b346 100644 --- a/keetanetwork-client-wasm/docs/ARCHITECTURE.md +++ b/keetanetwork-client-wasm/docs/ARCHITECTURE.md @@ -26,6 +26,18 @@ This crate depends on `keetanetwork-client` with the `wasm` feature. It depends The client `wasm` feature enables `http` on `wasm32-unknown-unknown`. That pairing satisfies the `compile_error!` in `keetanetwork-client/src/lib.rs`. +## Example + +From `keetanetwork-client-wasm/src/lib.rs` rustdoc. + +```js +import init, { KeetaClient, Account } from './pkg/keetanetwork_client_wasm.js'; + +await init(); +const client = KeetaClient.forNetwork('test'); +const me = Account.fromSeed(Account.generateSeed(), 0); +``` + ## Falsified by A change that accepts a JavaScript `number` as an amount. A change that drops `error.code` from thrown errors. A change that builds this crate without `keetanetwork-client` feature `wasm` or `keetanetwork-bindings` feature `client`. A change to the rustdoc example in `keetanetwork-client-wasm/src/lib.rs`. diff --git a/keetanetwork-client-wasm/docs/README.md b/keetanetwork-client-wasm/docs/README.md index d87e23b..14ea9ce 100644 --- a/keetanetwork-client-wasm/docs/README.md +++ b/keetanetwork-client-wasm/docs/README.md @@ -1,5 +1,41 @@ # keetanetwork-client-wasm -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate is the browser ABI over `keetanetwork-client` and `keetanetwork-bindings`. Amounts are decimal strings. Errors carry `error.code`. Cryptographic bytes are `Uint8Array`. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +This crate depends on `keetanetwork-client` with the `wasm` feature and `keetanetwork-bindings` with the `client` feature. + +```bash +make build-wasm +make test-wasm +``` + +Those Make targets need GitHub Packages read. [Workspace Quickstart](../../docs/QUICKSTART.md) holds the Packages gate. + +## Example + +From `keetanetwork-client-wasm/src/lib.rs` rustdoc. + +```js +import init, { KeetaClient, UserClient, Account, TransmitOptions } from './pkg/keetanetwork_client_wasm.js'; + +await init(); + +const client = KeetaClient.forNetwork('test'); +const me = Account.fromSeed(Account.generateSeed(), 0); +const token = Account.fromPublicKeyString('keeta_...token...'); +const to = Account.fromPublicKeyString('keeta_...recipient...'); + +const user = UserClient.fromClient(client, me); +await user.send(to, '1000', token); + +const builder = user.initBuilder(); +builder.send(to, '250', token); +await user.transmit(await builder.build(), new TransmitOptions()); +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-client/docs/ARCHITECTURE.md b/keetanetwork-client/docs/ARCHITECTURE.md index 5f7a577..860eca3 100644 --- a/keetanetwork-client/docs/ARCHITECTURE.md +++ b/keetanetwork-client/docs/ARCHITECTURE.md @@ -32,6 +32,16 @@ The orchestrator is `no_std` plus `alloc` when `std`, `http`, and `wasi` are off [Block](../../keetanetwork-block/docs/ARCHITECTURE.md) and [Vote](../../keetanetwork-vote/docs/ARCHITECTURE.md) hold the signed objects. [Bindings](../../keetanetwork-bindings/docs/ARCHITECTURE.md) holds the shared host projection. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. +## Example + +From `keetanetwork-client/src/lib.rs` rustdoc. + +```rust +use keetanetwork_client::KeetaClient; + +let client = KeetaClient::new("http://localhost:8080/api").with_network(0u8); +``` + ## Falsified by A change to `KeetaClient`, `UserClient`, or `TransactionBuilder` ownership. A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml`. A change to the `compile_error!` that pairs `http` with a runtime. A change that drops the vote or error re-exports from `keetanetwork-client/src/lib.rs`. diff --git a/keetanetwork-client/docs/README.md b/keetanetwork-client/docs/README.md index 494fd2d..6b5cb45 100644 --- a/keetanetwork-client/docs/README.md +++ b/keetanetwork-client/docs/README.md @@ -1,5 +1,46 @@ # keetanetwork-client -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns `KeetaClient`, `UserClient`, and `TransactionBuilder`. HTTP transport is generated from `keetanetwork-client/openapi/keetanet-node.yaml`. The crate re-exports the consumer-facing vote types. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features include `std`. Feature `std` enables `http` and a native Tokio runtime. Feature `wasm` enables `http` on `wasm32-unknown-unknown`. Feature `http` pairs with a runtime. + +```bash +cargo test -p keetanetwork-client --test user_signing +``` + +`make test` runs the workspace tests after the node harness. That path needs GitHub Packages read. [Workspace Quickstart](../../docs/QUICKSTART.md) holds the cargo-only path. + +## Example + +From `keetanetwork-client/src/lib.rs` rustdoc. + +```rust +use std::sync::Arc; + +use keetanetwork_account::GenericAccount; +use keetanetwork_account::doc_utils::create_ed25519_test_keys; +use keetanetwork_block::AccountRef; +use keetanetwork_client::KeetaClient; + +let client = KeetaClient::new("http://localhost:8080/api").with_network(0u8); + +let (_, _, signer) = create_ed25519_test_keys(None); +let account: AccountRef = Arc::new(GenericAccount::Ed25519(signer)); + +let blocks = client + .builder(&account) + .with_previous(account.to_opening_hash()) + .set_rep(&account) + .build() + .await?; + +assert_eq!(blocks.len(), 1); +# Ok::<(), keetanetwork_client::ClientError>(()) +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-crypto/docs/ARCHITECTURE.md b/keetanetwork-crypto/docs/ARCHITECTURE.md index 25178bc..8435706 100644 --- a/keetanetwork-crypto/docs/ARCHITECTURE.md +++ b/keetanetwork-crypto/docs/ARCHITECTURE.md @@ -37,6 +37,17 @@ Default features are `std`, `signature`, `encryption`, and `rasn`. `std` implies A `no_std` consumer enables `alloc` plus `signature` or `encryption` as the call site needs. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract when `der` or `rasn` is on. +## Example + +From `keetanetwork-crypto/src/hash.rs` `hash_default`. + +```rust +use keetanetwork_crypto::hash::hash_default; + +let digest = hash_default(b"hello world"); +assert_eq!(digest.len(), 32); +``` + ## Falsified by A change that moves hashing or signing primitives out of `keetanetwork-crypto`. A change that lets `keetanetwork-account`, `keetanetwork-block`, or `keetanetwork-vote` sign without this crate. A change to the `signature`, `encryption`, `der`, or `rasn` features in `keetanetwork-crypto/Cargo.toml`. diff --git a/keetanetwork-crypto/docs/README.md b/keetanetwork-crypto/docs/README.md index 7075e4b..c77ceb2 100644 --- a/keetanetwork-crypto/docs/README.md +++ b/keetanetwork-crypto/docs/README.md @@ -1,5 +1,35 @@ # keetanetwork-crypto -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns algorithm-agnostic primitives for keys, hashes, signatures, and encryption. Account, block, and vote crates sign through these types. They do not embed a second crypto stack. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features are `std`, `signature`, `encryption`, and `rasn`. `std` implies `alloc`. + +```bash +cargo test -p keetanetwork-crypto +``` + +`make test-feat` also runs this crate with `std,signature`, `std,encryption`, `std,der`, and `std`. + +## Example + +From `keetanetwork-crypto/src/hash.rs` `hash_default` and `keetanetwork-crypto/src/utils.rs` `test_generate_random_seed`. + +```rust +use keetanetwork_crypto::hash::hash_default; +use keetanetwork_crypto::prelude::ExposeSecret; +use keetanetwork_crypto::utils::generate_random_seed; + +let seed = generate_random_seed()?; +assert_eq!(seed.expose_secret().len(), 32); + +let digest = hash_default(b"hello world"); +assert_eq!(digest.len(), 32); +# Ok::<(), keetanetwork_crypto::error::CryptoError>(()) +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-error/docs/ARCHITECTURE.md b/keetanetwork-error/docs/ARCHITECTURE.md index b830ae8..c513937 100644 --- a/keetanetwork-error/docs/ARCHITECTURE.md +++ b/keetanetwork-error/docs/ARCHITECTURE.md @@ -28,6 +28,23 @@ Default features include `std`. `std` implies `alloc`. The crate builds under `n A higher crate that needs formatted errors on native targets enables `keetanetwork-error/std`. A `no_std` consumer enables `alloc` only. +## Example + +From `keetanetwork-error/src/lib.rs` `non_ledger_collapses_to_code`. + +```rust +use keetanetwork_error::{KeetaNetError, NodeErrorParts, NodeErrorType}; + +let parts = NodeErrorParts { + kind: NodeErrorType::Api, + code: "API_INVALID_SIDE".into(), + message: "boom".into(), + ..Default::default() +}; +let error = KeetaNetError::from(parts); +assert!(matches!(error, KeetaNetError::Code { code, .. } if code == "API_INVALID_SIDE")); +``` + ## Falsified by A change to `KeetaNetError` or `NodeErrorType` in `keetanetwork-error/src/lib.rs`. A change that drops the client re-export of those two types from `keetanetwork-client/src/lib.rs`. A change to the `std` / `alloc` features in `keetanetwork-error/Cargo.toml`. diff --git a/keetanetwork-error/docs/README.md b/keetanetwork-error/docs/README.md index 8593917..2624269 100644 --- a/keetanetwork-error/docs/README.md +++ b/keetanetwork-error/docs/README.md @@ -1,5 +1,33 @@ # keetanetwork-error -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns shared error types that higher crates return. `KeetaNetError` carries an internal failure or a node-emitted coded error. `NodeErrorType` is the category taken from the `type` field of a node error envelope. `keetanetwork-client` re-exports both types. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features include `std`. `std` implies `alloc`. The crate builds under `no_std` with `alloc`. + +```bash +cargo test -p keetanetwork-error +``` + +## Example + +From `keetanetwork-error/src/lib.rs` `non_ledger_collapses_to_code`. + +```rust +use keetanetwork_error::{KeetaNetError, NodeErrorParts, NodeErrorType}; + +let parts = NodeErrorParts { + kind: NodeErrorType::Api, + code: "API_INVALID_SIDE".into(), + message: "boom".into(), + ..Default::default() +}; +let error = KeetaNetError::from(parts); +assert!(matches!(error, KeetaNetError::Code { code, .. } if code == "API_INVALID_SIDE")); +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-utils/docs/ARCHITECTURE.md b/keetanetwork-utils/docs/ARCHITECTURE.md index 7204234..71da55e 100644 --- a/keetanetwork-utils/docs/ARCHITECTURE.md +++ b/keetanetwork-utils/docs/ARCHITECTURE.md @@ -28,6 +28,29 @@ Default features include `std`. Feature `build` is opt-in. Feature `node-harness A docs or compile-only change does not need `node-harness`. `make test`, `make test-wasm`, and `make test-wasi` do. +## Example + +From `keetanetwork-utils/src/testing.rs` `test_error_variants`. + +```rust +use keetanetwork_utils::test_error_variants; + +#[derive(Debug, PartialEq, Eq)] +enum TestError { + Simple, +} + +impl std::fmt::Display for TestError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "Simple error") + } +} + +test_error_variants! { + test_error_formatting, [TestError::Simple] +} +``` + ## Falsified by A change to the `build` or `node-harness` features in `keetanetwork-utils/Cargo.toml`. A change to the registry line in `keetanetwork-utils/node-harness/.npmrc`. A change that moves workspace test macros out of `keetanetwork-utils/src/lib.rs`. diff --git a/keetanetwork-utils/docs/README.md b/keetanetwork-utils/docs/README.md index 2db532e..aba3118 100644 --- a/keetanetwork-utils/docs/README.md +++ b/keetanetwork-utils/docs/README.md @@ -1,5 +1,48 @@ # keetanetwork-utils -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns shared test macros, optional ASN.1 build helpers, and the `node-harness` feature that talks to the private GitHub Packages package. Workspace crates use the macros in tests. `keetanetwork-asn1` and `keetanetwork-x509` use the `build` feature from their build scripts. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features include `std`. Feature `build` is opt-in. Feature `node-harness` is opt-in. + +```bash +cargo test -p keetanetwork-utils +``` + +[Workspace Quickstart](../../docs/QUICKSTART.md) holds the Packages token steps for `node-harness`. + +## Example + +From `keetanetwork-utils/src/testing.rs` `test_error_variants`. + +```rust +use keetanetwork_utils::test_error_variants; + +#[derive(Debug, PartialEq, Eq)] +enum TestError { + Simple, + WithData { message: String }, +} + +impl std::fmt::Display for TestError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + TestError::Simple => write!(f, "Simple error"), + TestError::WithData { message } => write!(f, "Error: {message}"), + } + } +} + +test_error_variants! { + test_error_formatting, [ + TestError::Simple, + TestError::WithData { message: "test".to_string() }, + ] +} +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-vote/docs/ARCHITECTURE.md b/keetanetwork-vote/docs/ARCHITECTURE.md index ba0f251..1e66f3f 100644 --- a/keetanetwork-vote/docs/ARCHITECTURE.md +++ b/keetanetwork-vote/docs/ARCHITECTURE.md @@ -30,6 +30,31 @@ This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork- A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract. +## Example + +From `keetanetwork-vote/src/lib.rs` rustdoc. + +```rust +use std::sync::Arc; +use keetanetwork_account::GenericAccount; +use keetanetwork_account::doc_utils::create_ed25519_test_keys; +use keetanetwork_block::{AccountRef, BlockTime}; +use keetanetwork_vote::VoteBuilder; + +let (_, _, signer) = create_ed25519_test_keys(None); +let issuer: AccountRef = Arc::new(GenericAccount::Ed25519(signer)); +let from = BlockTime::from_unix_millis(1_000_000).expect("moment in range"); +let to = BlockTime::from_unix_millis(2_000_000).expect("moment in range"); +let vote = VoteBuilder::new() + .serial(1u64) + .issuer(issuer.clone()) + .validity(from, to) + .add_block(issuer.to_opening_hash()) + .build_signed(issuer.as_ref())?; +assert!(!vote.as_bytes().is_empty()); +# Ok::<(), keetanetwork_vote::VoteError>(()) +``` + ## Falsified by A change to `Vote`, `VoteQuote`, `VoteStaple`, or `PossiblyExpiredVote` ownership. A change that drops the client re-export of `Vote`, `VoteQuote`, or `VoteStaple` from `keetanetwork-client/src/lib.rs`. A change to the rustdoc example in `keetanetwork-vote/src/lib.rs`. diff --git a/keetanetwork-vote/docs/README.md b/keetanetwork-vote/docs/README.md index 4c24ee5..da98957 100644 --- a/keetanetwork-vote/docs/README.md +++ b/keetanetwork-vote/docs/README.md @@ -1,5 +1,45 @@ # keetanetwork-vote -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns `Vote`, `VoteQuote`, `VoteStaple`, and `PossiblyExpiredVote`. A quote is for fee negotiation. A staple is the bundle that operators transmit. The client re-exports the consumer-facing vote types. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features are `std` and `rasn`. `std` implies `alloc`. + +```bash +cargo test -p keetanetwork-vote +``` + +## Example + +From `keetanetwork-vote/src/lib.rs` rustdoc. + +```rust +use std::sync::Arc; + +use keetanetwork_account::GenericAccount; +use keetanetwork_account::doc_utils::create_ed25519_test_keys; +use keetanetwork_block::{AccountRef, BlockTime}; +use keetanetwork_vote::VoteBuilder; + +let (_, _, signer) = create_ed25519_test_keys(None); +let issuer: AccountRef = Arc::new(GenericAccount::Ed25519(signer)); + +let from = BlockTime::from_unix_millis(1_000_000).expect("moment in range"); +let to = BlockTime::from_unix_millis(2_000_000).expect("moment in range"); + +let vote = VoteBuilder::new() + .serial(1u64) + .issuer(issuer.clone()) + .validity(from, to) + .add_block(issuer.to_opening_hash()) + .build_signed(issuer.as_ref())?; + +assert!(!vote.as_bytes().is_empty()); +# Ok::<(), keetanetwork_vote::VoteError>(()) +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) diff --git a/keetanetwork-x509/docs/ARCHITECTURE.md b/keetanetwork-x509/docs/ARCHITECTURE.md index 4bf61e7..8d4253d 100644 --- a/keetanetwork-x509/docs/ARCHITECTURE.md +++ b/keetanetwork-x509/docs/ARCHITECTURE.md @@ -30,6 +30,36 @@ The crate build depends on `keetanetwork-utils` with the `build` feature. [Utils A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the at-least-one codec contract. +## Example + +From `keetanetwork-x509/src/builder.rs` rustdoc. + +```rust +use keetanetwork_account::{Account, KeyED25519}; +use keetanetwork_asn1::SubjectPublicKeyInfo; +use keetanetwork_crypto::algorithms::ed25519::Ed25519Derivation; +use keetanetwork_crypto::prelude::KeyDerivation; +use keetanetwork_crypto::utils::generate_random_seed; +use keetanetwork_x509::builder::CertificateBuilder; +use keetanetwork_x509::{oids, utils, SerialNumber}; + +let seed = generate_random_seed()?; +let private_key = Ed25519Derivation::derive_from_seed(seed)?; +let account = Account::::from(private_key); +let public_key_info = SubjectPublicKeyInfo::from(account.keypair.to_public_key()); +let subject_dn = utils::create_dn(&[(oids::CN, "Example Certificate")])?; + +let certificate = CertificateBuilder::new() + .with_subject_public_key(public_key_info.clone()) + .with_subject_dn(subject_dn.clone()) + .with_issuer_dn(subject_dn) + .with_serial_number(SerialNumber::from(1u64)) + .with_validity_days(365) + .build(&account)?; +assert!(certificate.verify_signature(&public_key_info).is_ok()); +# Ok::<(), Box>(()) +``` + ## Falsified by A change that moves certificate builders or stores off `keetanetwork-x509`. A change that adds a signer trait on this crate that duplicates `CertSigner` or `CertVerifier`. A change to the `der` / `rasn` forwarding in `keetanetwork-x509/Cargo.toml`. diff --git a/keetanetwork-x509/docs/README.md b/keetanetwork-x509/docs/README.md index 4f9d9c7..008ac46 100644 --- a/keetanetwork-x509/docs/README.md +++ b/keetanetwork-x509/docs/README.md @@ -1,5 +1,35 @@ # keetanetwork-x509 -Crate architecture lives on [Architecture](ARCHITECTURE.md). +This crate owns X.509 certificate builders, stores, and validation. Account crate traits `CertSigner` and `CertVerifier` sign and verify those artifacts. Block, bindings, and the host ABI crates consume the resulting certificates. -Workspace map: [Overview](../../docs/README.md). +## Quickstart + +Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`. + +```bash +cargo test -p keetanetwork-x509 +``` + +`make test-feat` also runs this crate with `std,der` and `std,rasn`. + +## Example + +From `keetanetwork-x509/src/utils.rs` rustdoc on `create_dn`. + +```rust +use keetanetwork_asn1::oids; +use keetanetwork_x509::utils::create_dn; + +let pairs = &[ + (oids::CN, "example.com"), + (oids::O, "Example Organization"), +]; + +let dn = create_dn(pairs)?; +# Ok::<(), Box>(()) +``` + +## Related documents + +- [Architecture](ARCHITECTURE.md) +- [Workspace overview](../../docs/README.md) From f2c8842f732850603841381b039e6c517694fd16 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:47:56 +0000 Subject: [PATCH 12/13] docs: keep examples on crate READMEs only Remove Architecture Example sections and fenced code. Move the stronger x509 builder and WASI seed-to-account snippets onto those crate READMEs. Co-authored-by: Tanveer Wahid --- keetanetwork-account/docs/ARCHITECTURE.md | 18 ---------- keetanetwork-asn1/docs/ARCHITECTURE.md | 12 ------- keetanetwork-bindings/docs/ARCHITECTURE.md | 11 ------- keetanetwork-block/docs/ARCHITECTURE.md | 25 -------------- keetanetwork-client-wasi/docs/ARCHITECTURE.md | 14 -------- keetanetwork-client-wasi/docs/README.md | 7 ++-- keetanetwork-client-wasm/docs/ARCHITECTURE.md | 12 ------- keetanetwork-client/docs/ARCHITECTURE.md | 10 ------ keetanetwork-crypto/docs/ARCHITECTURE.md | 11 ------- keetanetwork-error/docs/ARCHITECTURE.md | 17 ---------- keetanetwork-utils/docs/ARCHITECTURE.md | 23 ------------- keetanetwork-vote/docs/ARCHITECTURE.md | 25 -------------- keetanetwork-x509/docs/ARCHITECTURE.md | 30 ----------------- keetanetwork-x509/docs/README.md | 33 +++++++++++++------ 14 files changed, 28 insertions(+), 220 deletions(-) diff --git a/keetanetwork-account/docs/ARCHITECTURE.md b/keetanetwork-account/docs/ARCHITECTURE.md index 5e241aa..af6e6cf 100644 --- a/keetanetwork-account/docs/ARCHITECTURE.md +++ b/keetanetwork-account/docs/ARCHITECTURE.md @@ -40,24 +40,6 @@ This crate depends on `keetanetwork-crypto` with `signature` and `encryption`. I Account seed, identifier, and signature cookbooks live in `keetanetwork-account/tests/account_creation.rs`, `keetanetwork-account/tests/seed_derivation.rs`, `keetanetwork-account/tests/identifier_accounts.rs`, and `keetanetwork-account/tests/signatures.rs`. -## Example - -From `keetanetwork-account/src/account.rs` rustdoc. - -```rust -use keetanetwork_account::{Account, KeyED25519}; -use keetanetwork_crypto::algorithms::ed25519::Ed25519Derivation; -use keetanetwork_crypto::prelude::KeyDerivation; -use keetanetwork_crypto::utils::generate_random_seed; - -let seed = generate_random_seed()?; -let private_key = Ed25519Derivation::derive_from_seed(seed)?; -let account = Account::::from(private_key); -let signature = account.sign(b"hello", None)?; -assert!(account.verify(b"hello", &signature, None).is_ok()); -# Ok::<(), Box>(()) -``` - ## Falsified by A change that moves `Account`, `GenericAccount`, `KeyPairType`, `CertSigner`, or `CertVerifier` off this crate. A change that adds a second identity model in `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, `keetanetwork-client`, or `keetanetwork-bindings`. A change to the `der` / `rasn` forwarding in `keetanetwork-account/Cargo.toml`. diff --git a/keetanetwork-asn1/docs/ARCHITECTURE.md b/keetanetwork-asn1/docs/ARCHITECTURE.md index 7c97a87..eea6812 100644 --- a/keetanetwork-asn1/docs/ARCHITECTURE.md +++ b/keetanetwork-asn1/docs/ARCHITECTURE.md @@ -26,18 +26,6 @@ Higher crates expose `der` and `rasn` under the same names and forward them here Block, vote, x509, account, crypto, and bindings crates depend on this crate when they encode or decode shared structures. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. -## Example - -From `keetanetwork-asn1/tests/vote_codec_vectors.rs` `test_vote_staple_reference_bytes`. - -```rust -use keetanetwork_asn1::vote::{codec, VoteStapleBundle}; - -let bundle = VoteStapleBundle { blocks: vec![vec![1, 2, 3]], votes: vec![vec![4, 5, 6]] }; -let encoded = codec::encode_vote_staple(&bundle).expect("encode staple"); -assert!(!encoded.is_empty()); -``` - ## Falsified by A change to the `compile_error!` in `keetanetwork-asn1/src/lib.rs` that no longer requires at least one of `der` or `rasn`. A change that adds a third codec feature without updating this page and the rustdoc feature list. A change that stops `keetanetwork-account`, `keetanetwork-block`, or `keetanetwork-vote` from forwarding `der` and `rasn` here. diff --git a/keetanetwork-bindings/docs/ARCHITECTURE.md b/keetanetwork-bindings/docs/ARCHITECTURE.md index 85e9a66..4c0b401 100644 --- a/keetanetwork-bindings/docs/ARCHITECTURE.md +++ b/keetanetwork-bindings/docs/ARCHITECTURE.md @@ -28,17 +28,6 @@ Default features include `std`. Feature `client` is opt-in and enables `keetanet A target crate that only needs the pure projection leaves `client` off. A target crate that needs the HTTP orchestrator enables `client`. -## Example - -From `keetanetwork-bindings/src/parse.rs` `amount_round_trips_decimal_strings`. - -```rust -use keetanetwork_bindings::parse::{amount, amount_to_string}; - -let parsed = amount("1000").expect("a decimal string must parse"); -assert_eq!(amount_to_string(parsed), "1000"); -``` - ## Falsified by A change that moves account-algorithm mapping or core-error reduction into `keetanetwork-client-wasm` or `keetanetwork-client-wasi` without this crate. A change to the `client` feature in `keetanetwork-bindings/Cargo.toml`. A change that drops this crate from either host ABI crate. diff --git a/keetanetwork-block/docs/ARCHITECTURE.md b/keetanetwork-block/docs/ARCHITECTURE.md index e98d751..0d1fda7 100644 --- a/keetanetwork-block/docs/ARCHITECTURE.md +++ b/keetanetwork-block/docs/ARCHITECTURE.md @@ -30,31 +30,6 @@ This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork- A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract. -## Example - -From `keetanetwork-block/src/lib.rs` rustdoc. - -```rust -use keetanetwork_account::{Account, Accountable, GenericAccount, KeyED25519, KeyPairType, Keyable}; -use keetanetwork_block::{AccountRef, BlockBuilder}; -use keetanetwork_crypto::prelude::IntoSecret; - -let seed = [7u8; 32].into_secret(); -let account = Account::::try_from(Accountable::KeyAndType( - Keyable::Seed((seed, 0)), - KeyPairType::ED25519, -))?; -let account = AccountRef::from(GenericAccount::Ed25519(account)); -let unsigned = BlockBuilder::default() - .with_network(0u8) - .with_account(account) - .as_opening() - .build()?; -let block = unsigned.sign()?; -assert!(!block.to_bytes().is_empty()); -# Ok::<(), keetanetwork_block::BlockError>(()) -``` - ## Falsified by A change to `Block`, `BlockBuilder`, `Operation`, or `AccountRef` ownership. A change that lets `keetanetwork-client` compute an opening hash without this crate. A change to the rustdoc example in `keetanetwork-block/src/lib.rs`. A change to the `der` / `rasn` forwarding in `keetanetwork-block/Cargo.toml`. diff --git a/keetanetwork-client-wasi/docs/ARCHITECTURE.md b/keetanetwork-client-wasi/docs/ARCHITECTURE.md index e1f5a95..77c049d 100644 --- a/keetanetwork-client-wasi/docs/ARCHITECTURE.md +++ b/keetanetwork-client-wasi/docs/ARCHITECTURE.md @@ -30,20 +30,6 @@ This crate always depends on `keetanetwork-account`, `keetanetwork-block`, `keet Select exactly one of `p1` or `p2` per WASI build. Feature `p2` is the only edge from this crate to `keetanetwork-client`. Feature `p1` stays on the pure surface. -## Example - -From `keetanetwork-bindings/src/account.rs` `account_round_trips_through_seed_and_public_key_string`, re-exported by `keetanetwork-client-wasi/src/pure.rs`. - -```rust -use keetanetwork_client_wasi::pure; - -let seed = pure::generate_seed().expect("seed generation must succeed"); -let account = pure::account_from_seed(&seed, 0, pure::DEFAULT_ALGORITHM) - .expect("account derivation must succeed"); -let public_key_string = pure::account_public_key_string(&account); -assert!(!public_key_string.is_empty()); -``` - ## Falsified by A change to the `compile_error!` in `keetanetwork-client-wasi/src/lib.rs`. A change that lets a WASI build enable both `p1` and `p2`, or neither. A change that pulls `keetanetwork-client` on feature `p1`. A change to the `p1` / `p2` selection in the `Makefile` `build-wasi` or `test-wasi` targets. diff --git a/keetanetwork-client-wasi/docs/README.md b/keetanetwork-client-wasi/docs/README.md index 7e85d79..5d7a55c 100644 --- a/keetanetwork-client-wasi/docs/README.md +++ b/keetanetwork-client-wasi/docs/README.md @@ -19,13 +19,16 @@ cargo test -p keetanetwork-client-wasi ## Example -From `keetanetwork-client-wasi/src/pure.rs` re-export of `keetanetwork-bindings/src/account.rs` `generated_seed_is_32_byte_hex`. +From `keetanetwork-bindings/src/account.rs` `account_round_trips_through_seed_and_public_key_string`, re-exported by `keetanetwork-client-wasi/src/pure.rs`. ```rust use keetanetwork_client_wasi::pure; let seed = pure::generate_seed().expect("seed generation must succeed"); -assert_eq!(seed.len(), 64); +let account = pure::account_from_seed(&seed, 0, pure::DEFAULT_ALGORITHM) + .expect("account derivation must succeed"); +let public_key_string = pure::account_public_key_string(&account); +assert!(!public_key_string.is_empty()); ``` ## Related documents diff --git a/keetanetwork-client-wasm/docs/ARCHITECTURE.md b/keetanetwork-client-wasm/docs/ARCHITECTURE.md index e81b346..97f8b74 100644 --- a/keetanetwork-client-wasm/docs/ARCHITECTURE.md +++ b/keetanetwork-client-wasm/docs/ARCHITECTURE.md @@ -26,18 +26,6 @@ This crate depends on `keetanetwork-client` with the `wasm` feature. It depends The client `wasm` feature enables `http` on `wasm32-unknown-unknown`. That pairing satisfies the `compile_error!` in `keetanetwork-client/src/lib.rs`. -## Example - -From `keetanetwork-client-wasm/src/lib.rs` rustdoc. - -```js -import init, { KeetaClient, Account } from './pkg/keetanetwork_client_wasm.js'; - -await init(); -const client = KeetaClient.forNetwork('test'); -const me = Account.fromSeed(Account.generateSeed(), 0); -``` - ## Falsified by A change that accepts a JavaScript `number` as an amount. A change that drops `error.code` from thrown errors. A change that builds this crate without `keetanetwork-client` feature `wasm` or `keetanetwork-bindings` feature `client`. A change to the rustdoc example in `keetanetwork-client-wasm/src/lib.rs`. diff --git a/keetanetwork-client/docs/ARCHITECTURE.md b/keetanetwork-client/docs/ARCHITECTURE.md index 860eca3..5f7a577 100644 --- a/keetanetwork-client/docs/ARCHITECTURE.md +++ b/keetanetwork-client/docs/ARCHITECTURE.md @@ -32,16 +32,6 @@ The orchestrator is `no_std` plus `alloc` when `std`, `http`, and `wasi` are off [Block](../../keetanetwork-block/docs/ARCHITECTURE.md) and [Vote](../../keetanetwork-vote/docs/ARCHITECTURE.md) hold the signed objects. [Bindings](../../keetanetwork-bindings/docs/ARCHITECTURE.md) holds the shared host projection. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. -## Example - -From `keetanetwork-client/src/lib.rs` rustdoc. - -```rust -use keetanetwork_client::KeetaClient; - -let client = KeetaClient::new("http://localhost:8080/api").with_network(0u8); -``` - ## Falsified by A change to `KeetaClient`, `UserClient`, or `TransactionBuilder` ownership. A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml`. A change to the `compile_error!` that pairs `http` with a runtime. A change that drops the vote or error re-exports from `keetanetwork-client/src/lib.rs`. diff --git a/keetanetwork-crypto/docs/ARCHITECTURE.md b/keetanetwork-crypto/docs/ARCHITECTURE.md index 8435706..25178bc 100644 --- a/keetanetwork-crypto/docs/ARCHITECTURE.md +++ b/keetanetwork-crypto/docs/ARCHITECTURE.md @@ -37,17 +37,6 @@ Default features are `std`, `signature`, `encryption`, and `rasn`. `std` implies A `no_std` consumer enables `alloc` plus `signature` or `encryption` as the call site needs. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract when `der` or `rasn` is on. -## Example - -From `keetanetwork-crypto/src/hash.rs` `hash_default`. - -```rust -use keetanetwork_crypto::hash::hash_default; - -let digest = hash_default(b"hello world"); -assert_eq!(digest.len(), 32); -``` - ## Falsified by A change that moves hashing or signing primitives out of `keetanetwork-crypto`. A change that lets `keetanetwork-account`, `keetanetwork-block`, or `keetanetwork-vote` sign without this crate. A change to the `signature`, `encryption`, `der`, or `rasn` features in `keetanetwork-crypto/Cargo.toml`. diff --git a/keetanetwork-error/docs/ARCHITECTURE.md b/keetanetwork-error/docs/ARCHITECTURE.md index c513937..b830ae8 100644 --- a/keetanetwork-error/docs/ARCHITECTURE.md +++ b/keetanetwork-error/docs/ARCHITECTURE.md @@ -28,23 +28,6 @@ Default features include `std`. `std` implies `alloc`. The crate builds under `n A higher crate that needs formatted errors on native targets enables `keetanetwork-error/std`. A `no_std` consumer enables `alloc` only. -## Example - -From `keetanetwork-error/src/lib.rs` `non_ledger_collapses_to_code`. - -```rust -use keetanetwork_error::{KeetaNetError, NodeErrorParts, NodeErrorType}; - -let parts = NodeErrorParts { - kind: NodeErrorType::Api, - code: "API_INVALID_SIDE".into(), - message: "boom".into(), - ..Default::default() -}; -let error = KeetaNetError::from(parts); -assert!(matches!(error, KeetaNetError::Code { code, .. } if code == "API_INVALID_SIDE")); -``` - ## Falsified by A change to `KeetaNetError` or `NodeErrorType` in `keetanetwork-error/src/lib.rs`. A change that drops the client re-export of those two types from `keetanetwork-client/src/lib.rs`. A change to the `std` / `alloc` features in `keetanetwork-error/Cargo.toml`. diff --git a/keetanetwork-utils/docs/ARCHITECTURE.md b/keetanetwork-utils/docs/ARCHITECTURE.md index 71da55e..7204234 100644 --- a/keetanetwork-utils/docs/ARCHITECTURE.md +++ b/keetanetwork-utils/docs/ARCHITECTURE.md @@ -28,29 +28,6 @@ Default features include `std`. Feature `build` is opt-in. Feature `node-harness A docs or compile-only change does not need `node-harness`. `make test`, `make test-wasm`, and `make test-wasi` do. -## Example - -From `keetanetwork-utils/src/testing.rs` `test_error_variants`. - -```rust -use keetanetwork_utils::test_error_variants; - -#[derive(Debug, PartialEq, Eq)] -enum TestError { - Simple, -} - -impl std::fmt::Display for TestError { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - write!(f, "Simple error") - } -} - -test_error_variants! { - test_error_formatting, [TestError::Simple] -} -``` - ## Falsified by A change to the `build` or `node-harness` features in `keetanetwork-utils/Cargo.toml`. A change to the registry line in `keetanetwork-utils/node-harness/.npmrc`. A change that moves workspace test macros out of `keetanetwork-utils/src/lib.rs`. diff --git a/keetanetwork-vote/docs/ARCHITECTURE.md b/keetanetwork-vote/docs/ARCHITECTURE.md index 1e66f3f..ba0f251 100644 --- a/keetanetwork-vote/docs/ARCHITECTURE.md +++ b/keetanetwork-vote/docs/ARCHITECTURE.md @@ -30,31 +30,6 @@ This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork- A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract. -## Example - -From `keetanetwork-vote/src/lib.rs` rustdoc. - -```rust -use std::sync::Arc; -use keetanetwork_account::GenericAccount; -use keetanetwork_account::doc_utils::create_ed25519_test_keys; -use keetanetwork_block::{AccountRef, BlockTime}; -use keetanetwork_vote::VoteBuilder; - -let (_, _, signer) = create_ed25519_test_keys(None); -let issuer: AccountRef = Arc::new(GenericAccount::Ed25519(signer)); -let from = BlockTime::from_unix_millis(1_000_000).expect("moment in range"); -let to = BlockTime::from_unix_millis(2_000_000).expect("moment in range"); -let vote = VoteBuilder::new() - .serial(1u64) - .issuer(issuer.clone()) - .validity(from, to) - .add_block(issuer.to_opening_hash()) - .build_signed(issuer.as_ref())?; -assert!(!vote.as_bytes().is_empty()); -# Ok::<(), keetanetwork_vote::VoteError>(()) -``` - ## Falsified by A change to `Vote`, `VoteQuote`, `VoteStaple`, or `PossiblyExpiredVote` ownership. A change that drops the client re-export of `Vote`, `VoteQuote`, or `VoteStaple` from `keetanetwork-client/src/lib.rs`. A change to the rustdoc example in `keetanetwork-vote/src/lib.rs`. diff --git a/keetanetwork-x509/docs/ARCHITECTURE.md b/keetanetwork-x509/docs/ARCHITECTURE.md index 8d4253d..4bf61e7 100644 --- a/keetanetwork-x509/docs/ARCHITECTURE.md +++ b/keetanetwork-x509/docs/ARCHITECTURE.md @@ -30,36 +30,6 @@ The crate build depends on `keetanetwork-utils` with the `build` feature. [Utils A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the at-least-one codec contract. -## Example - -From `keetanetwork-x509/src/builder.rs` rustdoc. - -```rust -use keetanetwork_account::{Account, KeyED25519}; -use keetanetwork_asn1::SubjectPublicKeyInfo; -use keetanetwork_crypto::algorithms::ed25519::Ed25519Derivation; -use keetanetwork_crypto::prelude::KeyDerivation; -use keetanetwork_crypto::utils::generate_random_seed; -use keetanetwork_x509::builder::CertificateBuilder; -use keetanetwork_x509::{oids, utils, SerialNumber}; - -let seed = generate_random_seed()?; -let private_key = Ed25519Derivation::derive_from_seed(seed)?; -let account = Account::::from(private_key); -let public_key_info = SubjectPublicKeyInfo::from(account.keypair.to_public_key()); -let subject_dn = utils::create_dn(&[(oids::CN, "Example Certificate")])?; - -let certificate = CertificateBuilder::new() - .with_subject_public_key(public_key_info.clone()) - .with_subject_dn(subject_dn.clone()) - .with_issuer_dn(subject_dn) - .with_serial_number(SerialNumber::from(1u64)) - .with_validity_days(365) - .build(&account)?; -assert!(certificate.verify_signature(&public_key_info).is_ok()); -# Ok::<(), Box>(()) -``` - ## Falsified by A change that moves certificate builders or stores off `keetanetwork-x509`. A change that adds a signer trait on this crate that duplicates `CertSigner` or `CertVerifier`. A change to the `der` / `rasn` forwarding in `keetanetwork-x509/Cargo.toml`. diff --git a/keetanetwork-x509/docs/README.md b/keetanetwork-x509/docs/README.md index 008ac46..4328467 100644 --- a/keetanetwork-x509/docs/README.md +++ b/keetanetwork-x509/docs/README.md @@ -14,18 +14,31 @@ cargo test -p keetanetwork-x509 ## Example -From `keetanetwork-x509/src/utils.rs` rustdoc on `create_dn`. +From `keetanetwork-x509/src/builder.rs` rustdoc. ```rust -use keetanetwork_asn1::oids; -use keetanetwork_x509::utils::create_dn; - -let pairs = &[ - (oids::CN, "example.com"), - (oids::O, "Example Organization"), -]; - -let dn = create_dn(pairs)?; +use keetanetwork_account::{Account, KeyED25519}; +use keetanetwork_asn1::SubjectPublicKeyInfo; +use keetanetwork_crypto::algorithms::ed25519::Ed25519Derivation; +use keetanetwork_crypto::prelude::KeyDerivation; +use keetanetwork_crypto::utils::generate_random_seed; +use keetanetwork_x509::builder::CertificateBuilder; +use keetanetwork_x509::{oids, utils, SerialNumber}; + +let seed = generate_random_seed()?; +let private_key = Ed25519Derivation::derive_from_seed(seed)?; +let account = Account::::from(private_key); +let public_key_info = SubjectPublicKeyInfo::from(account.keypair.to_public_key()); +let subject_dn = utils::create_dn(&[(oids::CN, "Example Certificate")])?; + +let certificate = CertificateBuilder::new() + .with_subject_public_key(public_key_info.clone()) + .with_subject_dn(subject_dn.clone()) + .with_issuer_dn(subject_dn) + .with_serial_number(SerialNumber::from(1u64)) + .with_validity_days(365) + .build(&account)?; +assert!(certificate.verify_signature(&public_key_info).is_ok()); # Ok::<(), Box>(()) ``` From c85b298468215172d6c1c3890befbc55527f6a3a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 21 Sep 2026 22:57:16 +0000 Subject: [PATCH 13/13] docs: real crate architecture diagrams and plural README examples Rewrite every product crate Architecture as internal design plus a Mermaid collaboration diagram. Add at least two labeled rustdoc or test examples to each product README. Co-authored-by: Tanveer Wahid --- docs/README.md | 4 +- docs/STANDARD.md | 4 +- keetanetwork-account/docs/ARCHITECTURE.md | 57 +++++++++++-------- keetanetwork-account/docs/README.md | 21 +++++-- keetanetwork-asn1/docs/ARCHITECTURE.md | 46 +++++++++++---- keetanetwork-asn1/docs/README.md | 22 ++++++- keetanetwork-bindings/docs/ARCHITECTURE.md | 43 +++++++++----- keetanetwork-bindings/docs/README.md | 21 ++++++- keetanetwork-block/docs/ARCHITECTURE.md | 45 ++++++++++----- keetanetwork-block/docs/README.md | 56 +++++++++++++++++- keetanetwork-client-wasi/docs/ARCHITECTURE.md | 33 +++++++---- keetanetwork-client-wasi/docs/README.md | 22 ++++++- keetanetwork-client-wasm/docs/ARCHITECTURE.md | 37 ++++++++---- keetanetwork-client-wasm/docs/README.md | 32 ++++++++++- keetanetwork-client/docs/ARCHITECTURE.md | 48 ++++++++++------ keetanetwork-client/docs/README.md | 36 ++++++++++-- keetanetwork-crypto/docs/ARCHITECTURE.md | 50 +++++++++------- keetanetwork-crypto/docs/README.md | 22 +++++-- keetanetwork-error/docs/ARCHITECTURE.md | 40 +++++++++---- keetanetwork-error/docs/README.md | 19 ++++++- keetanetwork-utils/docs/ARCHITECTURE.md | 38 +++++++++---- keetanetwork-utils/docs/README.md | 25 +++++++- keetanetwork-vote/docs/ARCHITECTURE.md | 46 ++++++++++----- keetanetwork-vote/docs/README.md | 41 +++++++++++-- keetanetwork-x509/docs/ARCHITECTURE.md | 43 +++++++++----- keetanetwork-x509/docs/README.md | 24 +++++++- 26 files changed, 652 insertions(+), 223 deletions(-) diff --git a/docs/README.md b/docs/README.md index b92d622..bdc578b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,7 +31,7 @@ An engineer reads this guide to find the page that holds each inbound question. This repository is a Cargo workspace of Keeta Network node crates. Root `Cargo.toml` `[workspace].members` is the member list. Crate identity lives in each member `Cargo.toml` `description` plus rustdoc on that crate `lib.rs`. -Each product crate listed on this guide holds architecture on that crate `docs/ARCHITECTURE.md`. The crate `docs/README.md` is the thin entry. `keetanetwork-node` and `keetanetwork-ledger` are empty stubs. Those crates hold a minimal `docs/README.md` only. [Architecture](ARCHITECTURE.md) names that boundary. +Each product crate listed on this guide holds architecture on that crate `docs/ARCHITECTURE.md`. The crate `docs/README.md` states purpose, Quickstart, and examples. `keetanetwork-node` and `keetanetwork-ledger` are empty stubs. Those crates hold a minimal `docs/README.md` only. [Architecture](ARCHITECTURE.md) names that boundary. Each member crate carries its own version in that crate `Cargo.toml`. This guide does not treat the unused workspace package version as the repository version. This table of contents does not stamp versions. @@ -67,7 +67,7 @@ These entries are the living table of contents for crate documentation. [Archite | `docs/STANDARD.md` | Documentation contract | | `docs/ARCHITECTURE.md` | Collaboration graph and interaction path | | `docs/QUICKSTART.md` | Install, build, test, and first use | -| `keetanetwork-*/docs/README.md` | Crate purpose, quickstart, and example | +| `keetanetwork-*/docs/README.md` | Crate purpose, Quickstart, and examples | | `keetanetwork-*/docs/ARCHITECTURE.md` | Product-crate architecture | GitHub issues and pull requests stay the history home. diff --git a/docs/STANDARD.md b/docs/STANDARD.md index 0d23814..171dbad 100644 --- a/docs/STANDARD.md +++ b/docs/STANDARD.md @@ -33,9 +33,9 @@ A page MUST NOT carry the following. The source is the one correct home for each One body of knowledge takes one page as its home. A second page that needs it MUST link to that home rather than restate it. The [Overview](README.md) names the living pages. -[Architecture](ARCHITECTURE.md) holds the workspace collaboration graph and the interaction path. Product-crate architecture lives under that crate `docs/ARCHITECTURE.md`. That page MUST add collaboration or feature-gate substance that rustdoc on a single type cannot hold. It MUST NOT restate that crate `pub use` list. The [Overview](README.md) is the table of contents into those paths. +[Architecture](ARCHITECTURE.md) holds the workspace collaboration graph and the interaction path. Product-crate architecture lives under that crate `docs/ARCHITECTURE.md`. That page MUST describe internal module responsibilities. It MUST include at least one Mermaid diagram with keyword-safe ids. It MUST name inbound and outbound neighbor crates. It MUST state feature and build contracts in the positive. It MUST NOT restate that crate `pub use` list. It MUST NOT carry fenced rust or JavaScript examples. The [Overview](README.md) is the table of contents into those paths. -A product-crate `docs/README.md` MUST state what the crate is for. It MUST name the features and the `cargo test -p` command or Make target. It MUST include at least one fenced code example copied from crate rustdoc or a test. It MUST link to that crate `docs/ARCHITECTURE.md` and the workspace [Overview](README.md). A stub crate MAY carry a minimal `docs/README.md` that names the reserved crate. It MUST NOT carry a product Architecture page. +A product-crate `docs/README.md` MUST state what the crate is for. It MUST name the features and the `cargo test -p` command or Make target. It MUST include at least two labeled fenced code examples copied from crate rustdoc or a test. It MUST link to that crate `docs/ARCHITECTURE.md` and the workspace [Overview](README.md). A stub crate MAY carry a minimal `docs/README.md` that names the reserved crate. It MUST NOT carry a product Architecture page. A concept page under `docs/concepts/` lands only when it still holds a non-rustdoc invariant after the workspace Architecture draft and the crate architecture. A candidate that collapses to a field list MUST NOT land. diff --git a/keetanetwork-account/docs/ARCHITECTURE.md b/keetanetwork-account/docs/ARCHITECTURE.md index af6e6cf..e5e5eeb 100644 --- a/keetanetwork-account/docs/ARCHITECTURE.md +++ b/keetanetwork-account/docs/ARCHITECTURE.md @@ -2,44 +2,51 @@ ## Abstract -This page is the consumer contract for `keetanetwork-account`. The crate owns typed and type-erased identities plus the certificate signing traits. Block, vote, x509, client, and bindings crates consume those identities. +This page is the internal design of `keetanetwork-account`. The crate turns seeds and key material into typed identities, then erases the algorithm at crate boundaries. Neighbor crates consume those identities. They do not invent a second account model. ## Purpose -An engineer reads this page before changing an identity type or adding a second account model in a higher crate. After reading, the engineer knows which types this crate owns and which crates must keep consuming them. +An engineer reads this page before changing how an identity is constructed or shared. After reading, the engineer can name the module that owns typing, erasure, certificate-mode signing, and errors. -## Ownership +## Internal design -`keetanetwork-account` owns `Account`, `GenericAccount`, `KeyPairType`, and identifier accounts. `Account` is the typed identity bound to one `KeyPairType`. `GenericAccount` is the type-erased account used at crate boundaries. `KeyPairType` names signing algorithms and identifier accounts. +`account` owns `Account`, `GenericAccount`, `KeyPairType`, and identifier accounts. A typed `Account` is bound to one algorithm marker such as `KeyED25519`. `GenericAccount` is the type-erased form that block, vote, and client carry across crate edges. Identifier kinds (`NETWORK`, `TOKEN`, `STORAGE`, `MULTISIG`) are accounts that do not sign. -`CertSigner` signs X.509-shaped artifacts in certificate mode. `CertVerifier` verifies those certificate-mode signatures. Certificate builders and stores stay in `keetanetwork-x509`. +`cert` owns `CertSigner` and `CertVerifier`. Certificate mode is the message-handling convention used by vote certificates and other X.509-shaped artifacts. ECDSA signs a SHA3-256 digest as DER `r` and `s`. Ed25519 signs the message directly. Identifier accounts cannot sign or verify in this mode. -Crate rustdoc on `keetanetwork-account/src/lib.rs` names those types. Field lists stay in rustdoc. +`error` owns `AccountError`. `constants` holds shared numeric and string constants. `utils` holds small helpers used by account construction. `doc_utils` is documentation-only test-key construction. -## Who consumes this crate +```mermaid +flowchart LR + mod_account[account] + mod_cert[cert] + mod_error[error] + type_typed[Account] + type_erased[GenericAccount] + crate_crypto[keetanetwork-crypto] + crate_block[keetanetwork-block] + crate_vote[keetanetwork-vote] + crate_x509[keetanetwork-x509] + crate_crypto -->|keys and signatures| mod_account + mod_account --> type_typed + type_typed --> type_erased + mod_account --> mod_cert + mod_error --> mod_account + type_erased --> crate_block + type_erased --> crate_vote + mod_cert --> crate_x509 +``` -| Consumer | How it uses the identities | -| --- | --- | -| `keetanetwork-block` | `AccountRef` wraps `GenericAccount`. Opening-hash and signing use the same account | -| `keetanetwork-vote` | A vote issuer is an `AccountRef` | -| `keetanetwork-x509` | Builders call `CertSigner` and `CertVerifier` | -| `keetanetwork-client` | `KeetaClient` and `UserClient` take an `AccountRef` | -| `keetanetwork-bindings` | Host ABIs map account algorithms through this crate | +## Collaboration -[Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. This page does not redraw it. +Inbound: `keetanetwork-crypto` supplies derivation, signing, and encryption. `keetanetwork-error` and `keetanetwork-utils` sit under those paths. `keetanetwork-asn1` is optional behind `der` and `rasn`. -## Feature contract - -Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1` and `keetanetwork-crypto`. - -A `no_std` consumer enables `alloc` and at least one of `der` or `rasn` when it needs the ASN.1 path. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the at-least-one codec contract. +Outbound: `keetanetwork-block` wraps `GenericAccount` as `AccountRef`. `keetanetwork-vote` uses that same `AccountRef` as a vote issuer. `keetanetwork-x509` calls `CertSigner` and `CertVerifier`. `keetanetwork-client` and `keetanetwork-bindings` take identities at the HTTP and host ABI edges. -This crate depends on `keetanetwork-crypto` with `signature` and `encryption`. It depends on `keetanetwork-error` and `keetanetwork-utils`. `keetanetwork-asn1` is optional behind `der` and `rasn`. - -## Seed and identifier tests +## Feature contract -Account seed, identifier, and signature cookbooks live in `keetanetwork-account/tests/account_creation.rs`, `keetanetwork-account/tests/seed_derivation.rs`, `keetanetwork-account/tests/identifier_accounts.rs`, and `keetanetwork-account/tests/signatures.rs`. +Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1` and `keetanetwork-crypto`. A `no_std` consumer enables `alloc` and at least one codec when it needs the ASN.1 path. ## Falsified by -A change that moves `Account`, `GenericAccount`, `KeyPairType`, `CertSigner`, or `CertVerifier` off this crate. A change that adds a second identity model in `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, `keetanetwork-client`, or `keetanetwork-bindings`. A change to the `der` / `rasn` forwarding in `keetanetwork-account/Cargo.toml`. +A change that moves `Account`, `GenericAccount`, `KeyPairType`, `CertSigner`, or `CertVerifier` off this crate. A change that adds a second identity model in block, vote, x509, client, or bindings. A change to the `der` / `rasn` forwarding in `keetanetwork-account/Cargo.toml`. diff --git a/keetanetwork-account/docs/README.md b/keetanetwork-account/docs/README.md index d2043bb..2bc4531 100644 --- a/keetanetwork-account/docs/README.md +++ b/keetanetwork-account/docs/README.md @@ -1,6 +1,6 @@ # keetanetwork-account -This crate owns typed and type-erased identities for the workspace. `Account` is bound to one `KeyPairType`. `GenericAccount` is the type-erased account used at crate boundaries. `CertSigner` and `CertVerifier` sign and verify X.509-shaped artifacts. Block, vote, x509, client, and bindings crates consume these identities. +This crate owns typed and type-erased identities for the workspace. `Account` is bound to one `KeyPairType`. `GenericAccount` is the type-erased account used at crate boundaries. `CertSigner` and `CertVerifier` sign and verify X.509-shaped artifacts. ## Quickstart @@ -12,7 +12,9 @@ cargo test -p keetanetwork-account `make test-feat` also runs this crate with `std,der` and `std,rasn`. -## Example +## Examples + +### Create from seed and sign From `keetanetwork-account/src/account.rs` rustdoc. @@ -28,8 +30,19 @@ let account = Account::::from(private_key); let message = b"Hello, Keeta Network!"; let signature = account.sign(message, None)?; -let is_valid = account.verify(message, &signature, None); -assert!(is_valid.is_ok()); +assert!(account.verify(message, &signature, None).is_ok()); +# Ok::<(), Box>(()) +``` + +### Identifier account + +From `keetanetwork-account/src/account.rs` rustdoc. + +```rust +use keetanetwork_account::{Account, KeyNETWORK, KeyPairType}; + +let network_account = Account::::generate_network_address(12345)?; +let token_account = network_account.generate_identifier(KeyPairType::TOKEN, None, 0)?; # Ok::<(), Box>(()) ``` diff --git a/keetanetwork-asn1/docs/ARCHITECTURE.md b/keetanetwork-asn1/docs/ARCHITECTURE.md index eea6812..ca2357d 100644 --- a/keetanetwork-asn1/docs/ARCHITECTURE.md +++ b/keetanetwork-asn1/docs/ARCHITECTURE.md @@ -2,30 +2,52 @@ ## Abstract -This page is the consumer contract for `keetanetwork-asn1`. The crate owns the encoding codecs that identity, certificate, block, and vote types share. A build enables at least one of `der` or `rasn`. +This page is the internal design of `keetanetwork-asn1`. The crate is the shared codec layer. Identity, certificate, block, and vote types encode through at least one of `der` or `rasn`. ## Purpose -An engineer reads this page before changing a codec feature or adding a third ASN.1 stack. After reading, the engineer knows the at-least-one feature contract and which crates forward `der` and `rasn` into this crate. +An engineer reads this page before changing a codec feature or adding a third ASN.1 stack. After reading, the engineer knows how the `der` and `rasn` backends sit under the block and vote transport modules. -## Ownership +## Internal design -`keetanetwork-asn1` owns ASN.1 structures and codec utilities used by certificates and related encodings. Crate rustdoc in `keetanetwork-asn1/src/lib.rs` lists the features and states the at-least-one contract. +`der` is the `der` crate backend. `rasn` is the `rasn` crate backend. When both features are on, unprefixed re-exports prefer `der` so x509, account, and crypto keep their legacy surface. `BitStringExt` and `ObjectIdentifierExt` surface whenever `rasn` is on. -This crate depends on `keetanetwork-utils`. The `build` feature on that crate supplies generation helpers. [Utils](../../keetanetwork-utils/docs/ARCHITECTURE.md) holds that helper. +`block` and `vote` are backend-neutral transport modules. They require `chrono` plus at least one codec. `asn1_time` owns `Asn1Time`. `oids` owns shared object identifiers. `utils` owns small codec helpers. `error` owns `Asn1Error`. -## Feature contract +`generated` and `schema_codec` are rasn-only generation and positional DER paths. `testing` is present when `testing` and `der` are on. + +```mermaid +flowchart TB + feat_der[feature_der] + feat_rasn[feature_rasn] + mod_der[der] + mod_rasn[rasn] + mod_block[block] + mod_vote[vote] + crate_x509[keetanetwork-x509] + crate_block[keetanetwork-block] + crate_vote[keetanetwork-vote] + feat_der --> mod_der + feat_rasn --> mod_rasn + mod_der --> mod_block + mod_rasn --> mod_block + mod_der --> mod_vote + mod_rasn --> mod_vote + mod_der --> crate_x509 + mod_block --> crate_block + mod_vote --> crate_vote +``` -A consumer enables at least one of `der` or `rasn`. Both features may be on together. The `compile_error!` in `keetanetwork-asn1/src/lib.rs` is the enforcement point. +## Collaboration -Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. +Inbound: `keetanetwork-utils` is a path dependency. The `build` feature on that crate supplies generation helpers used by this crate's build script. -Higher crates expose `der` and `rasn` under the same names and forward them here. Those crates include `keetanetwork-account`, `keetanetwork-crypto`, `keetanetwork-x509`, `keetanetwork-block`, and `keetanetwork-vote`. +Outbound: account, crypto, x509, block, vote, and bindings crates depend on this crate when they encode or decode shared structures. Those crates expose `der` and `rasn` under the same names and forward them here. -## Who consumes this crate +## Feature contract -Block, vote, x509, account, crypto, and bindings crates depend on this crate when they encode or decode shared structures. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. +A consumer enables at least one of `der` or `rasn`. Both features may be on together. The `compile_error!` in `keetanetwork-asn1/src/lib.rs` is the enforcement point. Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. ## Falsified by -A change to the `compile_error!` in `keetanetwork-asn1/src/lib.rs` that no longer requires at least one of `der` or `rasn`. A change that adds a third codec feature without updating this page and the rustdoc feature list. A change that stops `keetanetwork-account`, `keetanetwork-block`, or `keetanetwork-vote` from forwarding `der` and `rasn` here. +A change to the `compile_error!` that no longer requires at least one of `der` or `rasn`. A change that adds a third codec feature without updating this page. A change that stops account, block, or vote from forwarding `der` and `rasn` here. diff --git a/keetanetwork-asn1/docs/README.md b/keetanetwork-asn1/docs/README.md index d2bd020..ec3bd0a 100644 --- a/keetanetwork-asn1/docs/README.md +++ b/keetanetwork-asn1/docs/README.md @@ -12,9 +12,11 @@ cargo test -p keetanetwork-asn1 `make test-feat` also runs this crate with `std,der` and `std,rasn`. -## Example +## Examples -From `keetanetwork-asn1/tests/vote_codec_vectors.rs` `staple` and `test_vote_staple_reference_bytes`. +### Encode a vote staple + +From `keetanetwork-asn1/tests/vote_codec_vectors.rs` `test_vote_staple_reference_bytes`. ```rust use keetanetwork_asn1::vote::{codec, VoteStapleBundle}; @@ -27,6 +29,22 @@ let encoded = codec::encode_vote_staple(&bundle).expect("encode staple"); assert!(!encoded.is_empty()); ``` +### Decode a vote staple + +From `keetanetwork-asn1/tests/vote_codec_vectors.rs` `test_vote_staple_reference_bytes`. + +```rust +use keetanetwork_asn1::vote::{codec, VoteStapleBundle}; + +let bundle = VoteStapleBundle { + blocks: vec![vec![1, 2, 3]], + votes: vec![vec![4, 5, 6]], +}; +let encoded = codec::encode_vote_staple(&bundle).expect("encode staple"); +let decoded = codec::decode_vote_staple(&encoded).expect("decode staple"); +assert_eq!(decoded, bundle); +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-bindings/docs/ARCHITECTURE.md b/keetanetwork-bindings/docs/ARCHITECTURE.md index 4c0b401..0ef3e0f 100644 --- a/keetanetwork-bindings/docs/ARCHITECTURE.md +++ b/keetanetwork-bindings/docs/ARCHITECTURE.md @@ -2,32 +2,49 @@ ## Abstract -This page is the consumer contract for `keetanetwork-bindings`. The crate is the shared, target-agnostic projection used by the browser and WASI ABIs. It owns input parsing, account-algorithm mapping, and core-error reduction so those ABIs do not each grow a second copy. +This page is the internal design of `keetanetwork-bindings`. The crate is the shared, target-agnostic projection. Browser and WASI ABIs call these modules so each host does not grow a second parser or algorithm map. ## Purpose -An engineer reads this page before adding host-facing parsing in `keetanetwork-client-wasm` or `keetanetwork-client-wasi`. After reading, the engineer knows which work stays in this crate and which work stays in a target crate. +An engineer reads this page before adding host-facing parsing in `keetanetwork-client-wasm` or `keetanetwork-client-wasi`. After reading, the engineer knows which module owns amounts, algorithms, errors, and certificates. -## Ownership +## Internal design -`keetanetwork-bindings` owns the shared projection. Crate rustdoc in `keetanetwork-bindings/src/lib.rs` states that each FFI boundary repeats the same input parsing, account-algorithm mapping, and core-error reduction. +`parse` owns decimal `amount` parsing, adjust methods, purposes, and permission flag names. Rejected input becomes `ParseError` with a stable `code` such as `INVALID_AMOUNT`. -This crate depends on `keetanetwork-account`, `keetanetwork-crypto`, `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, and `keetanetwork-asn1` with `alloc` and `rasn`. Feature `client` pulls optional `keetanetwork-client`. +`account` owns `CRYPTO_ALGORITHMS`, `algorithm_name`, seed and public-key construction, and sign, verify, encrypt, and decrypt helpers. The default algorithm name is `ecdsa_secp256k1`. Identifier accounts map to `"other"`. -Field lists stay in rustdoc. +`error` owns `CodedError`, the reduced error shape hosts throw. `permissions` owns permission projection. `x509` owns certificate DER and PEM helpers. `time` owns moment parsing. `registry` owns small lookup tables. `client` is present when the `client` feature is on and pulls `keetanetwork-client`. -## Who consumes this crate +```mermaid +flowchart LR + mod_parse[parse] + mod_account[account] + mod_error[error] + mod_x509[x509] + crate_account[keetanetwork-account] + crate_block[keetanetwork-block] + crate_wasm[keetanetwork-client-wasm] + crate_wasi[keetanetwork-client-wasi] + crate_account --> mod_account + crate_block -->|Amount| mod_parse + mod_parse --> mod_error + mod_account --> crate_wasm + mod_parse --> crate_wasm + mod_x509 --> crate_wasi + mod_account --> crate_wasi +``` -`keetanetwork-client-wasm` depends on this crate with the `client` feature. `keetanetwork-client-wasi` depends on this crate on every build. Feature `p2` on the WASI crate also enables `keetanetwork-bindings/client`. +## Collaboration -[Client wasm](../../keetanetwork-client-wasm/docs/ARCHITECTURE.md) holds the browser ABI conventions. [Client WASI](../../keetanetwork-client-wasi/docs/ARCHITECTURE.md) holds the `p1` / `p2` contract. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. +Inbound: account, crypto, block, vote, x509, and asn1 crates are path dependencies with `alloc` and `rasn`. Feature `client` pulls `keetanetwork-client`. -## Feature contract +Outbound: `keetanetwork-client-wasm` depends on this crate with the `client` feature. `keetanetwork-client-wasi` depends on this crate on every build. Feature `p2` on the WASI crate also enables `keetanetwork-bindings/client`. -Default features include `std`. Feature `client` is opt-in and enables `keetanetwork-client`. +## Feature contract -A target crate that only needs the pure projection leaves `client` off. A target crate that needs the HTTP orchestrator enables `client`. +Default features include `std`. Feature `client` is opt-in. A target crate that only needs the pure projection leaves `client` off. ## Falsified by -A change that moves account-algorithm mapping or core-error reduction into `keetanetwork-client-wasm` or `keetanetwork-client-wasi` without this crate. A change to the `client` feature in `keetanetwork-bindings/Cargo.toml`. A change that drops this crate from either host ABI crate. +A change that moves account-algorithm mapping or core-error reduction into wasm or WASI without this crate. A change to the `client` feature in `keetanetwork-bindings/Cargo.toml`. A change that drops this crate from either host ABI crate. diff --git a/keetanetwork-bindings/docs/README.md b/keetanetwork-bindings/docs/README.md index 173bc39..5e12643 100644 --- a/keetanetwork-bindings/docs/README.md +++ b/keetanetwork-bindings/docs/README.md @@ -1,16 +1,18 @@ # keetanetwork-bindings -This crate is the shared, target-agnostic projection used by the browser and WASI ABIs. It owns input parsing, account-algorithm mapping, and core-error reduction so those ABIs do not each grow a second copy. +This crate is the shared, target-agnostic projection used by the browser and WASI ABIs. It owns input parsing, account-algorithm mapping, and core-error reduction. ## Quickstart -Default features include `std`. Feature `client` is opt-in and enables `keetanetwork-client`. +Default features include `std`. Feature `client` is opt-in. ```bash cargo test -p keetanetwork-bindings ``` -## Example +## Examples + +### Parse amount From `keetanetwork-bindings/src/parse.rs` `amount_round_trips_decimal_strings`. @@ -21,6 +23,19 @@ let parsed = amount("1000").expect("a decimal string must parse"); assert_eq!(amount_to_string(parsed), "1000"); ``` +### Algorithm map + +From `keetanetwork-bindings/src/account.rs` `algorithm_names_round_trip_every_crypto_type`. + +```rust +use keetanetwork_account::KeyPairType; +use keetanetwork_bindings::account::{algorithm_name, CRYPTO_ALGORITHMS}; + +assert_eq!(algorithm_name(KeyPairType::ED25519), "ed25519"); +assert_eq!(algorithm_name(KeyPairType::TOKEN), "other"); +assert_eq!(CRYPTO_ALGORITHMS[1].0, "ecdsa_secp256k1"); +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-block/docs/ARCHITECTURE.md b/keetanetwork-block/docs/ARCHITECTURE.md index 0d1fda7..8c19883 100644 --- a/keetanetwork-block/docs/ARCHITECTURE.md +++ b/keetanetwork-block/docs/ARCHITECTURE.md @@ -2,34 +2,51 @@ ## Abstract -This page is the consumer contract for `keetanetwork-block`. The crate owns `Block`, `BlockBuilder`, `Operation`, and `AccountRef`. Opening-hash and signing rules live here. The client builder uses the same rules. +This page is the internal design of `keetanetwork-block`. The crate turns an account identity and a list of operations into a signed block. Opening-hash and successor rules live here. Vote and client consume the resulting hashes and bytes. ## Purpose -An engineer reads this page before changing how a first block or a successor is signed. After reading, the engineer knows which types this crate owns and which crates must keep using them. +An engineer reads this page before changing how a first block or a successor is signed. After reading, the engineer can name the path from `BlockBuilder` through `UnsignedBlock` to `Block`, and which operation variants that builder accepts. -## Ownership +## Internal design -`keetanetwork-block` owns the signed block and the operations it carries. `AccountRef` wraps a `GenericAccount` from `keetanetwork-account`. Opening-hash calculation and `sign` live on the block types. +`builder` owns `BlockBuilder`. The builder collects network, account, previous hash, and operations. `as_opening` selects the opening previous. `with_previous` selects a successor. `build` produces `UnsignedBlock`. -The rustdoc example in `keetanetwork-block/src/lib.rs` builds a signed opening block through `BlockBuilder::default()`, `as_opening`, and `sign`. A live harness cookbook lives in `keetanetwork-block/tests/e2e.rs`. TypeScript compatibility tests live in `keetanetwork-block/tests/typescript_compat.rs`. +`block` owns `UnsignedBlock`, `Block`, `BlockData`, `BlockPurpose`, and `Signature`. `UnsignedBlock::sign` attaches the account signature and yields `Block`. `Block::try_from` decodes bytes. `Hashable` comes from `keetanetwork-crypto` and is re-exported as `BlockHash`. -Field lists stay in rustdoc. +`operation` owns `Operation` and `OperationType`. Variants are `Send`, `SetRep`, `SetInfo`, `ModifyPermissions`, `CreateIdentifier`, `TokenAdminSupply`, `TokenAdminModifyBalance`, `Receive`, and `ManageCertificate`. Each variant validates itself against the surrounding block. -## Who consumes this crate +`signer` owns `AccountRef` and `Signer`. `AccountRef` wraps `GenericAccount` from the account crate. `account_util` is crate-private dispatch over `GenericAccount` variants for parse, verify, and equality. `amount` owns `Amount`. `permissions` owns permission flags and groups. `time` owns `BlockTime`. `validation` owns `ValidationConfig` and text rules. `transport` owns byte encoding. `error` owns `BlockError`. `testing` is present when the `testing` feature is on. -`keetanetwork-vote` covers block hashes. `keetanetwork-client` assembles blocks through `TransactionBuilder` and transmits them inside a staple. `keetanetwork-bindings` and the host ABI crates project the same block types. +```mermaid +flowchart LR + crate_account[keetanetwork-account] + type_ref[AccountRef] + type_op[Operation] + type_builder[BlockBuilder] + type_unsigned[UnsignedBlock] + type_block[Block] + crate_vote[keetanetwork-vote] + crate_client[keetanetwork-client] + crate_account -->|GenericAccount| type_ref + type_ref --> type_builder + type_op --> type_builder + type_builder -->|build| type_unsigned + type_unsigned -->|sign| type_block + type_block -->|block hash| crate_vote + type_block --> crate_client +``` -[Account](../../keetanetwork-account/docs/ARCHITECTURE.md) holds the identity types. [Vote](../../keetanetwork-vote/docs/ARCHITECTURE.md) holds the commitment that covers those hashes. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. +## Collaboration -## Feature contract +Inbound: `keetanetwork-account` supplies the identity inside `AccountRef`. `keetanetwork-crypto` supplies `Hashable` and signatures. `keetanetwork-asn1` and `keetanetwork-x509` supply encoding and certificate material for `ManageCertificate`. -Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`, `keetanetwork-account`, `keetanetwork-crypto`, and `keetanetwork-x509`. +Outbound: `keetanetwork-vote` covers block hashes. `keetanetwork-client` assembles blocks through `TransactionBuilder` using the same opening-hash and signing rules. Bindings and host ABI crates project the same block types. -This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork-crypto` with `signature`, `keetanetwork-account`, `keetanetwork-asn1`, and `keetanetwork-x509`. +## Feature contract -A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract. +Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to asn1, account, crypto, and x509. A `no_std` consumer enables `alloc` and at least one codec. ## Falsified by -A change to `Block`, `BlockBuilder`, `Operation`, or `AccountRef` ownership. A change that lets `keetanetwork-client` compute an opening hash without this crate. A change to the rustdoc example in `keetanetwork-block/src/lib.rs`. A change to the `der` / `rasn` forwarding in `keetanetwork-block/Cargo.toml`. +A change to `Block`, `BlockBuilder`, `UnsignedBlock`, `Operation`, or `AccountRef` ownership. A change that lets the client compute an opening hash without this crate. A change to the rustdoc example in `keetanetwork-block/src/lib.rs`. diff --git a/keetanetwork-block/docs/README.md b/keetanetwork-block/docs/README.md index 5882648..8e97767 100644 --- a/keetanetwork-block/docs/README.md +++ b/keetanetwork-block/docs/README.md @@ -1,10 +1,10 @@ # keetanetwork-block -This crate owns `Block`, `BlockBuilder`, `Operation`, and `AccountRef`. Opening-hash and signing rules live here. The client builder uses the same rules when it assembles a first block or a successor. +This crate owns `Block`, `BlockBuilder`, `Operation`, and `AccountRef`. Opening-hash and signing rules live here. The client builder uses the same rules. ## Quickstart -Default features are `std` and `rasn`. `std` implies `alloc`. +Default features are `std` and `rasn`. ```bash cargo test -p keetanetwork-block @@ -12,7 +12,9 @@ cargo test -p keetanetwork-block `make test-feat` also runs this crate with `std,der` and `std,rasn`. -## Example +## Examples + +### Opening block and sign From `keetanetwork-block/src/lib.rs` rustdoc. @@ -49,6 +51,54 @@ assert_eq!(decoded.hash(), block.hash()); # Ok::<(), keetanetwork_block::BlockError>(()) ``` +### Successor with previous hash + +From `keetanetwork-block/src/lib.rs` rustdoc for the opening, plus `keetanetwork-block/tests/e2e.rs` successor `Send`. + +```rust +use keetanetwork_account::{Account, Accountable, GenericAccount, KeyED25519, KeyPairType, Keyable}; +use keetanetwork_block::{AccountRef, BlockBuilder, Receive, Send}; +use keetanetwork_crypto::hash::Hashable; +use keetanetwork_crypto::prelude::IntoSecret; + +let seed = [7u8; 32].into_secret(); +let account = Account::::try_from(Accountable::KeyAndType( + Keyable::Seed((seed, 0)), + KeyPairType::ED25519, +))?; +let token = account.generate_identifier(KeyPairType::TOKEN, None, 0)?; +let account = AccountRef::from(GenericAccount::Ed25519(account)); + +let opening = BlockBuilder::default() + .with_network(0u8) + .with_account(account.clone()) + .as_opening() + .with_operation(Receive { + amount: 10u64.into(), + token: token.clone().into(), + from: account.clone(), + exact: false, + forward: None, + }) + .build()? + .sign()?; + +let successor = BlockBuilder::default() + .with_network(0u8) + .with_account(account.clone()) + .with_previous(opening.hash()) + .with_operation(Send { + to: account.clone(), + amount: 1u64.into(), + token: token.into(), + external: None, + }) + .build()? + .sign()?; +assert_ne!(successor.hash(), opening.hash()); +# Ok::<(), keetanetwork_block::BlockError>(()) +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-client-wasi/docs/ARCHITECTURE.md b/keetanetwork-client-wasi/docs/ARCHITECTURE.md index 77c049d..174fbc4 100644 --- a/keetanetwork-client-wasi/docs/ARCHITECTURE.md +++ b/keetanetwork-client-wasi/docs/ARCHITECTURE.md @@ -2,29 +2,40 @@ ## Abstract -This page is the consumer contract for `keetanetwork-client-wasi`. The crate is the WASI ABI over a shared `pure` module. A WASI build selects exactly one of `p1` or `p2`. Feature `p2` pulls `keetanetwork-client`. Feature `p1` stays on the pure surface. +This page is the internal design of `keetanetwork-client-wasi`. The crate is two feature-selected WASI flavors over one shared `pure` module. Feature `p2` networks. Feature `p1` stays on the pure surface. ## Purpose -An engineer reads this page before changing a WASI feature or adding a second networking path on `p1`. After reading, the engineer knows which feature a P1 or P2 build enables and which crate supplies HTTP. +An engineer reads this page before changing a WASI feature or adding a second networking path on `p1`. After reading, the engineer knows which module is shared, which module is P1, and which module is P2. -## Ownership +## Internal design -`keetanetwork-client-wasi` owns two feature-selected flavors over one shared `pure` module in `keetanetwork-client-wasi/src/lib.rs`. +`pure` is always compiled. It re-exports account and certificate helpers from `keetanetwork-bindings` and adds block, vote, and identifier operations that both ABIs call. Off a WASI target, `p1` and `p2` compile out and leave `pure`. -Feature `p2` on `wasm32-wasip2` is a `wit-bindgen` component. It networks over `wasi:http` and exposes the pure surface. That feature pulls `keetanetwork-client` with the `wasi` feature and enables `keetanetwork-bindings/client`. +`p1` is present when feature `p1` is on and the target is WASI. It is a core module over a flat ABI. P1 has no outbound `connect`. The host dials. -Feature `p1` on `wasm32-wasip1` is a core module. It exposes the pure surface over a flat ABI. P1 has no outbound `connect`. The host dials. +`p2` is present when feature `p2` is on and the target is WASI. It is a `wit-bindgen` component that networks over `wasi:http`. That feature pulls `keetanetwork-client` with the `wasi` feature and enables `keetanetwork-bindings/client`. -A WASI build enables exactly one of `p1` or `p2`. The `compile_error!` in `keetanetwork-client-wasi/src/lib.rs` is the enforcement point. Off a WASI target both features compile out and leave `pure`. +A WASI build enables exactly one of `p1` or `p2`. The `compile_error!` in `keetanetwork-client-wasi/src/lib.rs` is the enforcement point. -Host tests live under `keetanetwork-client-wasi/host-tests/`. [Quickstart](../../docs/QUICKSTART.md) names `make build-wasi` and `make test-wasi`. Those targets select `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. +```mermaid +flowchart TB + mod_pure[pure] + mod_p1[p1] + mod_p2[p2] + crate_bindings[keetanetwork-bindings] + crate_client[keetanetwork-client] + crate_bindings --> mod_pure + mod_pure --> mod_p1 + mod_pure --> mod_p2 + crate_client -->|feature p2| mod_p2 +``` -## Who this crate projects +## Collaboration -This crate always depends on `keetanetwork-account`, `keetanetwork-block`, `keetanetwork-crypto`, `keetanetwork-vote`, `keetanetwork-x509`, and `keetanetwork-bindings`. Feature `p2` adds `keetanetwork-client`. +Inbound: this crate always depends on account, block, crypto, vote, x509, and bindings. Feature `p2` adds `keetanetwork-client`. -[Client](../../keetanetwork-client/docs/ARCHITECTURE.md) holds the `wasi` feature that supplies codec types without Tokio. [Bindings](../../keetanetwork-bindings/docs/ARCHITECTURE.md) holds the shared projection. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. +Outbound: host tests under `keetanetwork-client-wasi/host-tests/` exercise P1 and P2 artifacts. `make build-wasi` and `make test-wasi` select `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. ## Feature contract diff --git a/keetanetwork-client-wasi/docs/README.md b/keetanetwork-client-wasi/docs/README.md index 5d7a55c..e5cdebf 100644 --- a/keetanetwork-client-wasi/docs/README.md +++ b/keetanetwork-client-wasi/docs/README.md @@ -11,13 +11,15 @@ make build-wasi make test-wasi ``` -Those Make targets select `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. They need GitHub Packages read. Off a WASI target both features compile out and leave `pure`. +Those Make targets select `p1` for `wasm32-wasip1` and `p2` for `wasm32-wasip2`. Off a WASI target both features compile out and leave `pure`. ```bash cargo test -p keetanetwork-client-wasi ``` -## Example +## Examples + +### Seed and account on the pure surface From `keetanetwork-bindings/src/account.rs` `account_round_trips_through_seed_and_public_key_string`, re-exported by `keetanetwork-client-wasi/src/pure.rs`. @@ -31,6 +33,22 @@ let public_key_string = pure::account_public_key_string(&account); assert!(!public_key_string.is_empty()); ``` +### Identifier from a pure account + +From `keetanetwork-client-wasi/src/pure.rs` `generate_identifier`. + +```rust +use keetanetwork_account::KeyPairType; +use keetanetwork_client_wasi::pure; + +let seed = pure::generate_seed().expect("seed generation must succeed"); +let account = pure::account_from_seed(&seed, 0, pure::DEFAULT_ALGORITHM) + .expect("account derivation must succeed"); +let token = pure::generate_identifier(&account, KeyPairType::TOKEN, None, 0) + .expect("identifier derivation must succeed"); +assert_ne!(pure::account_public_key_string(&account), pure::account_public_key_string(&token)); +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-client-wasm/docs/ARCHITECTURE.md b/keetanetwork-client-wasm/docs/ARCHITECTURE.md index 97f8b74..803bffd 100644 --- a/keetanetwork-client-wasm/docs/ARCHITECTURE.md +++ b/keetanetwork-client-wasm/docs/ARCHITECTURE.md @@ -2,30 +2,45 @@ ## Abstract -This page is the consumer contract for `keetanetwork-client-wasm`. The crate is the browser ABI over `keetanetwork-client` and `keetanetwork-bindings`. Amounts are decimal strings. Errors carry `error.code`. +This page is the internal design of `keetanetwork-client-wasm`. The crate is the browser ABI. It projects `keetanetwork-client` and `keetanetwork-bindings` into JavaScript. Amounts stay decimal strings. Errors carry `error.code`. ## Purpose -An engineer reads this page before changing the browser ABI or adding a JavaScript number amount. After reading, the engineer knows the conventions this crate guarantees and which crates it projects. +An engineer reads this page before changing the browser ABI or adding a JavaScript `number` amount. After reading, the engineer can name which module owns the client, the user facade, and the conversions that keep amounts as strings. -## Ownership +## Internal design -`keetanetwork-client-wasm` projects `KeetaClient`, `UserClient`, and account helpers into JavaScript. Crate rustdoc in `keetanetwork-client-wasm/src/lib.rs` holds the conventions and the JavaScript example. +`client` and `user` own the JavaScript `KeetaClient` and `UserClient`. `builder` and `block_builder` own multi-operation assembly on the JS side. `account` owns seed and public-key construction. `block`, `vote`, `certificate`, and `x509` project those domain types. -Amounts are decimal strings such as `"1000"`. They are not JavaScript `number` values. Cryptographic bytes are `Uint8Array`. Hashes and keys are hex strings. Errors are JavaScript `Error` objects that carry a stable `error.code`. +`convert` and `dto` own the boundary conversions. Amounts become decimal strings. Cryptographic bytes become `Uint8Array`. Hashes and keys become hex strings. `options` owns `TransmitOptions`. `permissions`, `rep`, `pending`, and `swap` project the remaining client surfaces. -`make build-wasm` runs `wasm-pack build` for this crate. Playwright cookbooks live in `keetanetwork-client-wasm/tests/roundtrip.spec.ts` and `keetanetwork-client-wasm/tests/fee.spec.ts`. [Quickstart](../../docs/QUICKSTART.md) names the Make targets and the Packages gate. +The crate is gated to `wasm32-unknown-unknown`. It depends on `keetanetwork-client` with the `wasm` feature so `http` pairs with `WasmRuntime`. -## Who this crate projects +```mermaid +flowchart LR + js_caller[JavaScript caller] + mod_user[user] + mod_client[client] + mod_convert[convert] + crate_bindings[keetanetwork-bindings] + crate_client[keetanetwork-client] + js_caller -->|decimal string amounts| mod_user + mod_user --> mod_client + mod_convert --> mod_user + crate_bindings --> mod_convert + crate_client --> mod_client +``` -This crate depends on `keetanetwork-client` with the `wasm` feature. It depends on `keetanetwork-bindings` with the `client` feature. It also depends on `keetanetwork-account`, `keetanetwork-block`, `keetanetwork-crypto`, `keetanetwork-x509`, and `keetanetwork-asn1`. +## Collaboration -[Client](../../keetanetwork-client/docs/ARCHITECTURE.md) holds the orchestrator and the `http` plus `wasm` pairing. [Bindings](../../keetanetwork-bindings/docs/ARCHITECTURE.md) holds the shared projection. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. +Inbound: `keetanetwork-client` with `wasm`, `keetanetwork-bindings` with `client`, plus account, block, crypto, x509, and asn1. + +Outbound: this crate is a leaf ABI. Browser callers import the `wasm-pack` package. They do not take a Rust path dependency on the other workspace crates. ## Feature contract -The client `wasm` feature enables `http` on `wasm32-unknown-unknown`. That pairing satisfies the `compile_error!` in `keetanetwork-client/src/lib.rs`. +The client `wasm` feature enables `http` on `wasm32-unknown-unknown`. That pairing satisfies the `compile_error!` in `keetanetwork-client/src/lib.rs`. Amounts are decimal strings. Errors are JavaScript `Error` objects that carry `error.code`. ## Falsified by -A change that accepts a JavaScript `number` as an amount. A change that drops `error.code` from thrown errors. A change that builds this crate without `keetanetwork-client` feature `wasm` or `keetanetwork-bindings` feature `client`. A change to the rustdoc example in `keetanetwork-client-wasm/src/lib.rs`. +A change that accepts a JavaScript `number` as an amount. A change that drops `error.code` from thrown errors. A change that builds this crate without client feature `wasm` or bindings feature `client`. diff --git a/keetanetwork-client-wasm/docs/README.md b/keetanetwork-client-wasm/docs/README.md index 14ea9ce..8e0a3dd 100644 --- a/keetanetwork-client-wasm/docs/README.md +++ b/keetanetwork-client-wasm/docs/README.md @@ -1,6 +1,6 @@ # keetanetwork-client-wasm -This crate is the browser ABI over `keetanetwork-client` and `keetanetwork-bindings`. Amounts are decimal strings. Errors carry `error.code`. Cryptographic bytes are `Uint8Array`. +This crate is the browser ABI over `keetanetwork-client` and `keetanetwork-bindings`. Amounts are decimal strings. Errors carry `error.code`. ## Quickstart @@ -13,7 +13,9 @@ make test-wasm Those Make targets need GitHub Packages read. [Workspace Quickstart](../../docs/QUICKSTART.md) holds the Packages gate. -## Example +## Examples + +### Send through UserClient From `keetanetwork-client-wasm/src/lib.rs` rustdoc. @@ -21,7 +23,6 @@ From `keetanetwork-client-wasm/src/lib.rs` rustdoc. import init, { KeetaClient, UserClient, Account, TransmitOptions } from './pkg/keetanetwork_client_wasm.js'; await init(); - const client = KeetaClient.forNetwork('test'); const me = Account.fromSeed(Account.generateSeed(), 0); const token = Account.fromPublicKeyString('keeta_...token...'); @@ -35,6 +36,31 @@ builder.send(to, '250', token); await user.transmit(await builder.build(), new TransmitOptions()); ``` +### Sign, verify, and coded amount error + +From `keetanetwork-client-wasm/src/lib.rs` rustdoc. + +```js +import init, { KeetaClient, UserClient, Account } from './pkg/keetanetwork_client_wasm.js'; + +await init(); +const client = KeetaClient.forNetwork('test'); +const me = Account.fromSeed(Account.generateSeed(), 0); +const token = Account.fromPublicKeyString('keeta_...token...'); +const to = Account.fromPublicKeyString('keeta_...recipient...'); +const user = UserClient.fromClient(client, me); + +const message = new TextEncoder().encode('hello'); +const signature = me.sign(message); +const ok = me.verify(message, signature); // true + +try { + await user.send(to, 'not-a-number', token); +} catch (error) { + console.error(error.code, error.message); // INVALID_AMOUNT +} +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-client/docs/ARCHITECTURE.md b/keetanetwork-client/docs/ARCHITECTURE.md index 5f7a577..8c2d8cc 100644 --- a/keetanetwork-client/docs/ARCHITECTURE.md +++ b/keetanetwork-client/docs/ARCHITECTURE.md @@ -2,36 +2,52 @@ ## Abstract -This page is the consumer contract for `keetanetwork-client`. The crate owns `KeetaClient`, `UserClient`, and `TransactionBuilder`. HTTP transport is generated from the committed OpenAPI document. The crate re-exports the consumer-facing vote types. +This page is the internal design of `keetanetwork-client`. The crate is the orchestrator. It assembles blocks with the same rules as `keetanetwork-block`, then transmits vote staples through a generated HTTP transport. ## Purpose -An engineer reads this page before changing client construction, HTTP generation, or the `http` runtime pairing. After reading, the engineer knows which types this crate owns and which features a native or browser build enables. +An engineer reads this page before changing client construction, HTTP generation, or the `http` runtime pairing. After reading, the engineer can name the path from `KeetaClient` through `TransactionBuilder` and `UserClient` to the generated transport. -## Ownership +## Internal design -`KeetaClient` is the orchestrator. `UserClient` signs and transmits on behalf of an account. `TransactionBuilder` assembles blocks with the same opening-hash and signing rules as `keetanetwork-block`. +`client` owns `KeetaClient`. Construction is `KeetaClient::new` plus `with_network`, or `with_parts` for a `no_std` consumer that supplies a `Runtime` and a `NodeTransport`. -HTTP transport is generated at build time from `keetanetwork-client/openapi/keetanet-node.yaml` through progenitor. The generated types are exposed as the `generated` module when the `codec` feature is on. +`builder` owns `TransactionBuilder`. It assembles operations into blocks using block opening-hash and signing rules. `user` owns `UserClient`. A `UserClient` binds a signer and an optional operating account. Writes originate for the account and are signed by the bound signer. A client without a signer is read-only. -The rustdoc example in `keetanetwork-client/src/lib.rs` constructs `KeetaClient::new("http://localhost:8080/api")` and `.with_network(0u8)`. A live harness cookbook lives in `keetanetwork-client/tests/e2e.rs`. `UserClient` signing tests live in `keetanetwork-client/tests/user_signing.rs`. [Quickstart](../../docs/QUICKSTART.md) cites those examples. +`transport` owns `NodeTransport` and `TransportFactory`. Feature `http` generates the HTTP client from `keetanetwork-client/openapi/keetanet-node.yaml` through progenitor into the `generated` module when `codec` is on. `runtime` owns `Runtime`, `TokioRuntime` on `std`, `WasmRuntime` on `wasm`, and `WasiRuntime` on `wasi`. -The crate re-exports `Vote`, `VoteQuote`, `VoteStaple`, and `VoteBlockHash` from `keetanetwork-vote`. It also re-exports `KeetaNetError` and `NodeErrorType` from `keetanetwork-error`. +`model` owns query and response types. `rep` owns representative selection. `network` is present with `http`. `config` owns `ClientConfig`. `codec` owns transport-agnostic encoding when the `codec` feature is on. `genesis` owns network initialization helpers. `swap` owns swap request types. `math` owns quorum and backoff helpers. `sync` owns the `no_std` lock primitives that the orchestrator shares. `marker` owns `MaybeSend` and `MaybeSync`. `error` owns `ClientError`. -## Feature contract - -Default features include `std`. Feature `std` enables `http` and a native Tokio runtime. Feature `wasm` enables `http` on `wasm32-unknown-unknown`. Feature `wasi` enables `codec` without pulling Tokio. +```mermaid +flowchart LR + type_client[KeetaClient] + type_user[UserClient] + type_tx[TransactionBuilder] + type_runtime[Runtime] + type_transport[NodeTransport] + mod_generated[generated] + crate_block[keetanetwork-block] + crate_vote[keetanetwork-vote] + type_client --> type_user + type_user --> type_tx + type_client --> type_runtime + type_client --> type_transport + mod_generated --> type_transport + crate_block --> type_tx + type_tx -->|blocks| crate_vote + crate_vote -->|VoteStaple| type_client +``` -Feature `http` pairs with a runtime. Native builds enable `std`. Browser builds enable `wasm` on `wasm32-unknown-unknown`. The `compile_error!` in `keetanetwork-client/src/lib.rs` is the enforcement point. +## Collaboration -The orchestrator is `no_std` plus `alloc` when `std`, `http`, and `wasi` are off. A `no_std` consumer supplies a `Runtime` and a `NodeTransport` through `KeetaClient::with_parts`. +Inbound: `keetanetwork-account` supplies `AccountRef`. `keetanetwork-block` supplies opening-hash and signing. `keetanetwork-vote` supplies vote types that this crate re-exports. `keetanetwork-error` supplies `KeetaNetError`, also re-exported. -## Who consumes this crate +Outbound: `keetanetwork-client-wasm` enables the `wasm` feature. `keetanetwork-client-wasi` enables this crate only on feature `p2`. `keetanetwork-bindings` takes this crate behind its `client` feature. -`keetanetwork-client-wasm` enables the `wasm` feature. `keetanetwork-client-wasi` enables this crate only on feature `p2`. `keetanetwork-bindings` takes this crate behind its `client` feature. +## Feature contract -[Block](../../keetanetwork-block/docs/ARCHITECTURE.md) and [Vote](../../keetanetwork-vote/docs/ARCHITECTURE.md) hold the signed objects. [Bindings](../../keetanetwork-bindings/docs/ARCHITECTURE.md) holds the shared host projection. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. +Default features include `std`. Feature `std` enables `http` and a native Tokio runtime. Feature `wasm` enables `http` on `wasm32-unknown-unknown`. Feature `wasi` enables `codec` without pulling Tokio. Feature `http` pairs with a runtime. The `compile_error!` in `keetanetwork-client/src/lib.rs` is the enforcement point. The orchestrator is `no_std` plus `alloc` when `std`, `http`, and `wasi` are off. ## Falsified by -A change to `KeetaClient`, `UserClient`, or `TransactionBuilder` ownership. A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml`. A change to the `compile_error!` that pairs `http` with a runtime. A change that drops the vote or error re-exports from `keetanetwork-client/src/lib.rs`. +A change to `KeetaClient`, `UserClient`, or `TransactionBuilder` ownership. A change that moves the OpenAPI document away from `keetanetwork-client/openapi/keetanet-node.yaml`. A change to the `compile_error!` that pairs `http` with a runtime. diff --git a/keetanetwork-client/docs/README.md b/keetanetwork-client/docs/README.md index 6b5cb45..4a65369 100644 --- a/keetanetwork-client/docs/README.md +++ b/keetanetwork-client/docs/README.md @@ -1,18 +1,20 @@ # keetanetwork-client -This crate owns `KeetaClient`, `UserClient`, and `TransactionBuilder`. HTTP transport is generated from `keetanetwork-client/openapi/keetanet-node.yaml`. The crate re-exports the consumer-facing vote types. +This crate owns `KeetaClient`, `UserClient`, and `TransactionBuilder`. HTTP transport is generated from `keetanetwork-client/openapi/keetanet-node.yaml`. ## Quickstart -Default features include `std`. Feature `std` enables `http` and a native Tokio runtime. Feature `wasm` enables `http` on `wasm32-unknown-unknown`. Feature `http` pairs with a runtime. +Default features include `std`. Feature `http` pairs with a runtime. Native builds enable `std`. Browser builds enable `wasm`. ```bash cargo test -p keetanetwork-client --test user_signing ``` -`make test` runs the workspace tests after the node harness. That path needs GitHub Packages read. [Workspace Quickstart](../../docs/QUICKSTART.md) holds the cargo-only path. +`make test` runs the workspace tests after the node harness. [Workspace Quickstart](../../docs/QUICKSTART.md) holds the Packages gate. -## Example +## Examples + +### KeetaClient builder From `keetanetwork-client/src/lib.rs` rustdoc. @@ -25,7 +27,6 @@ use keetanetwork_block::AccountRef; use keetanetwork_client::KeetaClient; let client = KeetaClient::new("http://localhost:8080/api").with_network(0u8); - let (_, _, signer) = create_ed25519_test_keys(None); let account: AccountRef = Arc::new(GenericAccount::Ed25519(signer)); @@ -35,11 +36,34 @@ let blocks = client .set_rep(&account) .build() .await?; - assert_eq!(blocks.len(), 1); # Ok::<(), keetanetwork_client::ClientError>(()) ``` +### UserClient signing + +From `keetanetwork-client/tests/user_signing.rs` `delegated_writes_are_signed_by_the_bound_signer`. + +```rust +use std::sync::Arc; + +use keetanetwork_block::testing::generate_ed25519_ref; +use keetanetwork_client::{KeetaClient, UserClient}; + +let client = KeetaClient::new("http://127.0.0.1:0/api").with_network(1u8); +let account = generate_ed25519_ref(0x40); +let signer = generate_ed25519_ref(0x41); +let rep = generate_ed25519_ref(0x43); +let user = UserClient::from_parts(client, Some(Arc::clone(&signer))).with_account(Arc::clone(&account)); + +let mut builder = user.init_builder()?; +builder.with_previous(account.to_opening_hash()); +builder.set_rep(&rep); +let blocks = builder.build().await?; +assert_eq!(blocks[0].data().signer().principal().to_string(), signer.to_string()); +# Ok::<(), keetanetwork_client::ClientError>(()) +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-crypto/docs/ARCHITECTURE.md b/keetanetwork-crypto/docs/ARCHITECTURE.md index 25178bc..129556d 100644 --- a/keetanetwork-crypto/docs/ARCHITECTURE.md +++ b/keetanetwork-crypto/docs/ARCHITECTURE.md @@ -2,41 +2,47 @@ ## Abstract -This page is the consumer contract for `keetanetwork-crypto`. The crate owns algorithm-agnostic primitives for keys, hashes, signatures, and encryption. Account, block, vote, client, and bindings crates call those primitives. They do not embed a second crypto stack. +This page is the internal design of `keetanetwork-crypto`. The crate is the algorithm-agnostic primitive layer. Account, block, and vote crates derive keys, hash, and sign through these modules. They do not embed a second crypto stack. ## Purpose -An engineer reads this page before adding a signing or hashing path in a higher crate. After reading, the engineer knows which features this crate exposes and which crates must keep depending on it. +An engineer reads this page before adding a signing or hashing path in a higher crate. After reading, the engineer can name the module that owns algorithms, hashes, KDF, and secret handling. -## Ownership +## Internal design -`keetanetwork-crypto` owns key generation, derivation, public-key formatting, hashing, signatures, and encryption. The crate rustdoc in `keetanetwork-crypto/src/lib.rs` names support for `secp256k1` and `Ed25519`. +`algorithms` owns secp256k1, secp256r1, and Ed25519 derivation and key types. `hash` owns `HashAlgorithm`, `hash_default`, `Hashable`, and `BlockHash`. `kdf` owns HKDF-style derivation used by some algorithms. `operations` owns higher-level sign and encrypt entry points. `verify` owns verification helpers. -`Hashable` and the signing prelude live in this crate. `keetanetwork-block` and `keetanetwork-vote` hash and sign through those types. +`utils` owns `generate_random_seed` and related byte helpers. `prelude` re-exports `IntoSecret`, `ExposeSecret`, and the traits higher crates import. `bigint` owns big-integer helpers used by encodings. `error` owns `CryptoError`. `constants` holds algorithm constants. `test_utils` is present in test builds. -Field lists stay in rustdoc. +```mermaid +flowchart LR + mod_algo[algorithms] + mod_hash[hash] + mod_kdf[kdf] + mod_ops[operations] + mod_utils[utils] + crate_account[keetanetwork-account] + crate_block[keetanetwork-block] + crate_vote[keetanetwork-vote] + mod_utils -->|seed| mod_algo + mod_kdf --> mod_algo + mod_algo --> mod_ops + mod_hash --> crate_block + mod_ops --> crate_account + mod_hash --> crate_vote + mod_ops --> crate_vote +``` -## Who consumes this crate +## Collaboration -| Consumer | How it uses this crate | -| --- | --- | -| `keetanetwork-account` | Enables `signature` and `encryption` for account keys | -| `keetanetwork-block` | Enables `signature` for block signing | -| `keetanetwork-vote` | Enables `signature` for vote signing | -| `keetanetwork-x509` | Uses the same primitives for certificate material | -| `keetanetwork-client` | Depends on `alloc` for client-side hashing | -| `keetanetwork-bindings` | Depends on `alloc` and `signature` for host ABIs | +Inbound: `keetanetwork-utils` is a path dependency. `keetanetwork-error` is optional and comes on with `std`. `keetanetwork-asn1` is optional behind `der` and `rasn`. -[Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. +Outbound: `keetanetwork-account` enables `signature` and `encryption`. `keetanetwork-block` and `keetanetwork-vote` enable `signature` and hash through `Hashable`. `keetanetwork-x509`, `keetanetwork-client`, and `keetanetwork-bindings` call the same primitives. ## Feature contract -Default features are `std`, `signature`, `encryption`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to optional `keetanetwork-asn1`. - -`keetanetwork-error` is optional and comes on with `std`. `keetanetwork-utils` is a path dependency. - -A `no_std` consumer enables `alloc` plus `signature` or `encryption` as the call site needs. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract when `der` or `rasn` is on. +Default features are `std`, `signature`, `encryption`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to optional `keetanetwork-asn1`. A `no_std` consumer enables `alloc` plus `signature` or `encryption` as the call site needs. ## Falsified by -A change that moves hashing or signing primitives out of `keetanetwork-crypto`. A change that lets `keetanetwork-account`, `keetanetwork-block`, or `keetanetwork-vote` sign without this crate. A change to the `signature`, `encryption`, `der`, or `rasn` features in `keetanetwork-crypto/Cargo.toml`. +A change that moves hashing or signing primitives out of this crate. A change that lets account, block, or vote sign without this crate. A change to the `signature`, `encryption`, `der`, or `rasn` features in `keetanetwork-crypto/Cargo.toml`. diff --git a/keetanetwork-crypto/docs/README.md b/keetanetwork-crypto/docs/README.md index c77ceb2..721d654 100644 --- a/keetanetwork-crypto/docs/README.md +++ b/keetanetwork-crypto/docs/README.md @@ -1,6 +1,6 @@ # keetanetwork-crypto -This crate owns algorithm-agnostic primitives for keys, hashes, signatures, and encryption. Account, block, and vote crates sign through these types. They do not embed a second crypto stack. +This crate owns algorithm-agnostic primitives for keys, hashes, signatures, and encryption. Account, block, and vote crates call these modules. They do not embed a second crypto stack. ## Quickstart @@ -12,20 +12,30 @@ cargo test -p keetanetwork-crypto `make test-feat` also runs this crate with `std,signature`, `std,encryption`, `std,der`, and `std`. -## Example +## Examples -From `keetanetwork-crypto/src/hash.rs` `hash_default` and `keetanetwork-crypto/src/utils.rs` `test_generate_random_seed`. +### Default hash + +From `keetanetwork-crypto/src/hash.rs` `hash_default`. ```rust use keetanetwork_crypto::hash::hash_default; + +let digest = hash_default(b"hello world"); +assert_eq!(digest.len(), 32); +``` + +### Random seed + +From `keetanetwork-crypto/src/utils.rs` `test_generate_random_seed`. + +```rust use keetanetwork_crypto::prelude::ExposeSecret; use keetanetwork_crypto::utils::generate_random_seed; let seed = generate_random_seed()?; assert_eq!(seed.expose_secret().len(), 32); - -let digest = hash_default(b"hello world"); -assert_eq!(digest.len(), 32); +assert_ne!(*seed.expose_secret(), [0u8; 32]); # Ok::<(), keetanetwork_crypto::error::CryptoError>(()) ``` diff --git a/keetanetwork-error/docs/ARCHITECTURE.md b/keetanetwork-error/docs/ARCHITECTURE.md index b830ae8..ebfa50a 100644 --- a/keetanetwork-error/docs/ARCHITECTURE.md +++ b/keetanetwork-error/docs/ARCHITECTURE.md @@ -2,32 +2,48 @@ ## Abstract -This page is the consumer contract for `keetanetwork-error`. The crate owns shared error types that higher crates return and that the client re-exports. It also names the node error categories that a decoded envelope can carry. +This page is the internal design of `keetanetwork-error`. The crate is a single-module envelope. It turns a node error `type` field into `NodeErrorType`, then builds a typed `KeetaNetError` from decoded parts. ## Purpose -An engineer reads this page before introducing a crate-local error envelope that callers must learn twice. After reading, the engineer knows which types this crate owns and which crate re-exports them to HTTP callers. +An engineer reads this page before adding a crate-local error envelope that callers must learn twice. After reading, the engineer knows how a node envelope becomes `Code`, `Ledger`, `LedgerVote`, or `LedgerIdempotent`. -## Ownership +## Internal design -`keetanetwork-error` owns `KeetaNetError` and `NodeErrorType` in `keetanetwork-error/src/lib.rs`. `NodeErrorType` is the category taken from the `type` field of a node error envelope. The known categories are `Account`, `Api`, `Block`, `Certificate`, `Client`, `Kv`, `Ledger`, `Permissions`, `Vote`, and `Generic`. +The crate has no submodule split. `NodeErrorType` is the category taken from the envelope `type` field. Known categories are `Account`, `Api`, `Block`, `Certificate`, `Client`, `Kv`, `Ledger`, `Permissions`, `Vote`, and `Generic`. -Field lists and variant payloads stay in rustdoc. +`NodeErrorParts` is the decoded envelope used to construct `KeetaNetError`. Non-ledger kinds collapse to `KeetaNetError::Code`. Ledger codes in `LEDGER_NOT_SUCCESSOR` and `LEDGER_NOT_OPENING` become `LedgerVote` when accounts are present. `LEDGER_IDEMPOTENT_KEY_EXISTS` becomes `LedgerIdempotent` when both block hashes are present. Other ledger codes become `Ledger` and may carry retry data. -## Who consumes this crate +`KeetaNetError` also has `Internal`, `Unknown`, and `NotImplemented` for local failures that are not node envelopes. `node_type` recovers a category from a coded variant by reading the code prefix. -`keetanetwork-account`, `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, and `keetanetwork-client` depend on this crate. `keetanetwork-client` re-exports `KeetaNetError` and `NodeErrorType` from `keetanetwork-client/src/lib.rs`. +```mermaid +flowchart TD + type_parts[NodeErrorParts] + type_kind[NodeErrorType] + var_code[KeetaNetError_Code] + var_ledger[KeetaNetError_Ledger] + var_vote[KeetaNetError_LedgerVote] + var_idem[KeetaNetError_LedgerIdempotent] + var_internal[KeetaNetError_Internal] + type_local[local failure] + type_parts --> type_kind + type_kind -->|non ledger| var_code + type_kind -->|ledger base| var_ledger + type_kind -->|ledger vote codes| var_vote + type_kind -->|ledger idempotent codes| var_idem + type_local --> var_internal +``` -`keetanetwork-crypto` takes this crate only when the `std` feature is on. +## Collaboration -[Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. +Inbound: this crate depends only on `snafu`. It does not depend on other workspace crates. + +Outbound: `keetanetwork-account`, `keetanetwork-block`, `keetanetwork-vote`, `keetanetwork-x509`, and `keetanetwork-client` return or wrap these types. `keetanetwork-client` re-exports `KeetaNetError` and `NodeErrorType`. `keetanetwork-crypto` takes this crate only when `std` is on. ## Feature contract Default features include `std`. `std` implies `alloc`. The crate builds under `no_std` with `alloc`. -A higher crate that needs formatted errors on native targets enables `keetanetwork-error/std`. A `no_std` consumer enables `alloc` only. - ## Falsified by -A change to `KeetaNetError` or `NodeErrorType` in `keetanetwork-error/src/lib.rs`. A change that drops the client re-export of those two types from `keetanetwork-client/src/lib.rs`. A change to the `std` / `alloc` features in `keetanetwork-error/Cargo.toml`. +A change to `KeetaNetError` or `NodeErrorType` in `keetanetwork-error/src/lib.rs`. A change that drops the client re-export of those two types. A change to the ledger code tables that select `LedgerVote` or `LedgerIdempotent`. diff --git a/keetanetwork-error/docs/README.md b/keetanetwork-error/docs/README.md index 2624269..38cea08 100644 --- a/keetanetwork-error/docs/README.md +++ b/keetanetwork-error/docs/README.md @@ -1,16 +1,18 @@ # keetanetwork-error -This crate owns shared error types that higher crates return. `KeetaNetError` carries an internal failure or a node-emitted coded error. `NodeErrorType` is the category taken from the `type` field of a node error envelope. `keetanetwork-client` re-exports both types. +This crate owns shared error types that higher crates return. `KeetaNetError` carries an internal failure or a node-emitted coded error. `NodeErrorType` is the category taken from the `type` field of a node error envelope. ## Quickstart -Default features include `std`. `std` implies `alloc`. The crate builds under `no_std` with `alloc`. +Default features include `std`. `std` implies `alloc`. ```bash cargo test -p keetanetwork-error ``` -## Example +## Examples + +### Coded node envelope From `keetanetwork-error/src/lib.rs` `non_ledger_collapses_to_code`. @@ -27,6 +29,17 @@ let error = KeetaNetError::from(parts); assert!(matches!(error, KeetaNetError::Code { code, .. } if code == "API_INVALID_SIDE")); ``` +### Internal construction + +From `keetanetwork-error/src/lib.rs` `KeetaNetError::Internal`. + +```rust +use keetanetwork_error::KeetaNetError; + +let error = KeetaNetError::Internal; +assert_eq!(error.node_type(), None); +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-utils/docs/ARCHITECTURE.md b/keetanetwork-utils/docs/ARCHITECTURE.md index 7204234..93ddcc0 100644 --- a/keetanetwork-utils/docs/ARCHITECTURE.md +++ b/keetanetwork-utils/docs/ARCHITECTURE.md @@ -2,31 +2,45 @@ ## Abstract -This page is the consumer contract for `keetanetwork-utils`. The crate owns shared test macros, optional ASN.1 build helpers, and the `node-harness` feature that talks to the private GitHub Packages package. [Quickstart](../../docs/QUICKSTART.md) holds the operator steps for that gate. +This page is the internal design of `keetanetwork-utils`. The crate is shared tooling under the product path. It owns test macros, optional ASN.1 build helpers, and the node harness client. ## Purpose -An engineer reads this page before adding a workspace-wide test helper or changing the harness feature. After reading, the engineer knows which features this crate owns and which pages hold the install steps. +An engineer reads this page before adding a workspace-wide test helper or changing the harness feature. After reading, the engineer knows which module is compile-time, which module is test-only, and which module talks to GitHub Packages. -## Ownership +## Internal design -`keetanetwork-utils` owns reusable `macro_rules!` macros, a `testing` module, an optional `build` module, and an optional `node_harness` module. Crate rustdoc in `keetanetwork-utils/src/lib.rs` is the module reference. +`testing` owns `test_error_variants` and `test_error_from_conversions`. Those macros generate Display, Debug, and conversion tests that workspace crates share. -Feature `build` enables `rasn-compiler` and the `build` module. `keetanetwork-asn1` and `keetanetwork-x509` use that feature from their build scripts. +`errors` owns `impl_source_error_from` and related From-boilerplate macros. Domain crates use those macros so each error enum does not hand-write the same conversions. -Feature `node-harness` enables the harness client. `keetanetwork-utils/node-harness/.npmrc` sets `@keetanetwork:registry=https://npm.pkg.github.com`. [Quickstart](../../docs/QUICKSTART.md) holds the Packages token steps and the cargo-only path. +`build` is present when the `build` feature is on. It wraps `rasn-compiler` and cleans generated ASN.1 Rust. `keetanetwork-asn1` and `keetanetwork-x509` call it from their build scripts. -## Who consumes this crate +`node_harness` is present when the `node-harness` feature is on. It talks to `@keetanetwork/keetanet-node` through `keetanetwork-utils/node-harness/.npmrc`. -Account, crypto, asn1, x509, block, and vote crates depend on this crate for shared helpers. Test binaries enable `std` and `node-harness` when they talk to a live node. +```mermaid +flowchart TB + mod_testing[testing] + mod_errors[errors] + mod_build[build] + mod_harness[node_harness] + crate_asn1[keetanetwork-asn1] + crate_x509[keetanetwork-x509] + crate_tests[workspace tests] + mod_errors --> crate_tests + mod_testing --> crate_tests + mod_build --> crate_asn1 + mod_build --> crate_x509 + mod_harness --> crate_tests +``` -This crate is not on the signed-write collaboration path in [Architecture](../../docs/ARCHITECTURE.md). It is the shared tooling under that path. +## Collaboration -## Feature contract +This crate is not on the signed-write collaboration path. Account, crypto, asn1, x509, block, and vote crates depend on it for helpers. Test binaries enable `std` and `node-harness` when they talk to a live node. -Default features include `std`. Feature `build` is opt-in. Feature `node-harness` is opt-in and pulls `serde_json` and `snafu`. +## Feature contract -A docs or compile-only change does not need `node-harness`. `make test`, `make test-wasm`, and `make test-wasi` do. +Default features include `std`. Feature `build` is opt-in and enables `rasn-compiler`. Feature `node-harness` is opt-in and pulls `serde_json` and `snafu`. `make test`, `make test-wasm`, and `make test-wasi` need `node-harness`. ## Falsified by diff --git a/keetanetwork-utils/docs/README.md b/keetanetwork-utils/docs/README.md index aba3118..807c89a 100644 --- a/keetanetwork-utils/docs/README.md +++ b/keetanetwork-utils/docs/README.md @@ -1,6 +1,6 @@ # keetanetwork-utils -This crate owns shared test macros, optional ASN.1 build helpers, and the `node-harness` feature that talks to the private GitHub Packages package. Workspace crates use the macros in tests. `keetanetwork-asn1` and `keetanetwork-x509` use the `build` feature from their build scripts. +This crate owns shared test macros, optional ASN.1 build helpers, and the `node-harness` feature that talks to the private GitHub Packages package. ## Quickstart @@ -12,7 +12,9 @@ cargo test -p keetanetwork-utils [Workspace Quickstart](../../docs/QUICKSTART.md) holds the Packages token steps for `node-harness`. -## Example +## Examples + +### Error variant tests From `keetanetwork-utils/src/testing.rs` `test_error_variants`. @@ -42,6 +44,25 @@ test_error_variants! { } ``` +### Source error From impls + +From `keetanetwork-utils/src/errors.rs` rustdoc on `impl_source_error_from`. + +```rust +use keetanetwork_utils::impl_source_error_from; + +#[derive(Debug)] +enum MyError { + IoError { source: std::io::Error }, + ParseError { source: std::num::ParseIntError }, +} + +impl_source_error_from!(MyError, { + std::io::Error => IoError, + std::num::ParseIntError => ParseError, +}); +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-vote/docs/ARCHITECTURE.md b/keetanetwork-vote/docs/ARCHITECTURE.md index ba0f251..5d73056 100644 --- a/keetanetwork-vote/docs/ARCHITECTURE.md +++ b/keetanetwork-vote/docs/ARCHITECTURE.md @@ -2,34 +2,52 @@ ## Abstract -This page is the consumer contract for `keetanetwork-vote`. The crate owns `Vote`, `VoteQuote`, `VoteStaple`, and `PossiblyExpiredVote`. The client re-exports the consumer-facing vote types. A quote is for fee negotiation. A staple is the bundle that operators transmit. +This page is the internal design of `keetanetwork-vote`. The crate turns block hashes into a representative commitment, then compresses votes and blocks into a staple. The client re-exports the consumer-facing vote types. ## Purpose -An engineer reads this page before changing vote construction or adding a second staple type in the client. After reading, the engineer knows which vote kinds this crate owns and which crate re-exports them. +An engineer reads this page before changing vote construction or adding a second staple type in the client. After reading, the engineer can name the path from `VoteBuilder` to `Vote`, from `VoteQuoteBuilder` to `VoteQuote`, and from `VoteStapleBuilder` to `VoteStaple`. -## Ownership +## Internal design -A `Vote` is a representative's signed commitment that named block hashes should enter the ledger. A `VoteQuote` is a non-binding vote whose fees field has `quote = true`. A quote cannot be stapled or used to confirm blocks. A `PossiblyExpiredVote` is a parsed and signature-verified vote whose validity window may have ended. A `VoteStaple` is the compressed bundle of votes and the blocks they cover. +`builder` owns the three fluent builders. `VoteBuilder` produces `UnsignedVote` or a signed `Vote`. `VoteQuoteBuilder` wraps `VoteBuilder` and forces `quote = true` on the fee schedule. A quote cannot be stapled or used to confirm blocks. `VoteStapleBuilder` collects votes and blocks, applies canonical ordering, and builds a `VoteStaple`. -`VoteBuilder`, `VoteQuoteBuilder`, and `VoteStapleBuilder` assemble those types. Crate rustdoc in `keetanetwork-vote/src/lib.rs` holds the rustdoc example and the verification contract. This crate denies missing docs. +`vote` owns `Vote`, `VoteQuote`, `UnsignedVote`, and `PossiblyExpiredVote`. A possibly expired vote is parsed and signature-verified. Its validity window may have ended. -Cookbooks live in `keetanetwork-vote/tests/e2e_node.rs`, `keetanetwork-vote/tests/typescript_compat.rs`, and `keetanetwork-vote/tests/wire_corruption.rs`. +`staple` owns `VoteStaple`. `Vote::verify` decodes bytes, rejects non-canonical DER, and checks the issuer signature. `VoteStaple::verify` also enforces canonical ordering, an agreed block set, a single issuer, and uniform permanence at a caller-supplied moment. -## Who consumes this crate +`cert` owns certificate-shaped encoding that uses account `CertSigner`. `fee` owns `Fee` and `Fees` as `Single` or `Multiple`. `validity` owns the validity window. `hash` owns `VoteBlockHash`, `VoteHash`, and `VoteStapleHash`. `validation` owns `ValidationConfig`. `error` owns `VoteError`. `testing` is present when the `testing` feature is on. -`keetanetwork-client` depends on this crate and re-exports `Vote`, `VoteQuote`, `VoteStaple`, and `VoteBlockHash` from `keetanetwork-client/src/lib.rs`. `keetanetwork-bindings` and `keetanetwork-client-wasi` depend on this crate so host ABIs can project vote types. +```mermaid +flowchart LR + crate_block[keetanetwork-block] + type_builder[VoteBuilder] + type_quote_builder[VoteQuoteBuilder] + type_vote[Vote] + type_quote[VoteQuote] + type_staple_builder[VoteStapleBuilder] + type_staple[VoteStaple] + crate_client[keetanetwork-client] + crate_block -->|block hash| type_builder + type_builder -->|build_signed| type_vote + type_quote_builder -->|quote true| type_quote + type_vote --> type_staple_builder + crate_block -->|Block| type_staple_builder + type_staple_builder --> type_staple + type_vote --> crate_client + type_staple --> crate_client +``` -[Block](../../keetanetwork-block/docs/ARCHITECTURE.md) holds the hashes a vote covers. [Client](../../keetanetwork-client/docs/ARCHITECTURE.md) holds the transmit path. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration path. +## Collaboration -## Feature contract +Inbound: `keetanetwork-block` supplies `AccountRef`, `Block`, and `BlockHash`. `keetanetwork-account` supplies the issuer and `CertSigner`. `keetanetwork-crypto` supplies signatures. `keetanetwork-asn1` supplies vote transport codecs. -Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`, `keetanetwork-account`, `keetanetwork-crypto`, and `keetanetwork-block`. +Outbound: `keetanetwork-client` re-exports `Vote`, `VoteQuote`, `VoteStaple`, and `VoteBlockHash`. `keetanetwork-bindings` and `keetanetwork-client-wasi` project vote types at host ABIs. -This crate depends on `keetanetwork-error`, `keetanetwork-utils`, `keetanetwork-crypto` with `signature`, `keetanetwork-account`, `keetanetwork-asn1`, and `keetanetwork-block`. +## Feature contract -A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the codec contract. +Default features are `std` and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to asn1, account, crypto, and block. A `no_std` consumer enables `alloc` and at least one codec. ## Falsified by -A change to `Vote`, `VoteQuote`, `VoteStaple`, or `PossiblyExpiredVote` ownership. A change that drops the client re-export of `Vote`, `VoteQuote`, or `VoteStaple` from `keetanetwork-client/src/lib.rs`. A change to the rustdoc example in `keetanetwork-vote/src/lib.rs`. +A change to `Vote`, `VoteQuote`, `VoteStaple`, or `PossiblyExpiredVote` ownership. A change that drops the client re-export of `Vote`, `VoteQuote`, or `VoteStaple`. A change to the rustdoc example in `keetanetwork-vote/src/lib.rs`. diff --git a/keetanetwork-vote/docs/README.md b/keetanetwork-vote/docs/README.md index da98957..95461fb 100644 --- a/keetanetwork-vote/docs/README.md +++ b/keetanetwork-vote/docs/README.md @@ -1,16 +1,18 @@ # keetanetwork-vote -This crate owns `Vote`, `VoteQuote`, `VoteStaple`, and `PossiblyExpiredVote`. A quote is for fee negotiation. A staple is the bundle that operators transmit. The client re-exports the consumer-facing vote types. +This crate owns `Vote`, `VoteQuote`, `VoteStaple`, and `PossiblyExpiredVote`. A quote is for fee negotiation. A staple is the bundle that operators transmit. ## Quickstart -Default features are `std` and `rasn`. `std` implies `alloc`. +Default features are `std` and `rasn`. ```bash cargo test -p keetanetwork-vote ``` -## Example +## Examples + +### VoteBuilder signed vote From `keetanetwork-vote/src/lib.rs` rustdoc. @@ -24,7 +26,6 @@ use keetanetwork_vote::VoteBuilder; let (_, _, signer) = create_ed25519_test_keys(None); let issuer: AccountRef = Arc::new(GenericAccount::Ed25519(signer)); - let from = BlockTime::from_unix_millis(1_000_000).expect("moment in range"); let to = BlockTime::from_unix_millis(2_000_000).expect("moment in range"); @@ -34,11 +35,41 @@ let vote = VoteBuilder::new() .validity(from, to) .add_block(issuer.to_opening_hash()) .build_signed(issuer.as_ref())?; - assert!(!vote.as_bytes().is_empty()); # Ok::<(), keetanetwork_vote::VoteError>(()) ``` +### VoteQuoteBuilder + +From `keetanetwork-vote/src/builder.rs` `test_vote_quote_builder_forces_quote_flag`. + +```rust +use std::sync::Arc; + +use keetanetwork_account::GenericAccount; +use keetanetwork_account::doc_utils::create_ed25519_test_keys; +use keetanetwork_block::{AccountRef, BlockTime}; +use keetanetwork_vote::{Fee, Fees, VoteQuoteBuilder}; + +let (_, _, signer) = create_ed25519_test_keys(None); +let issuer: AccountRef = Arc::new(GenericAccount::Ed25519(signer)); +let from = BlockTime::from_unix_millis(1_000_000).expect("moment in range"); +let to = BlockTime::from_unix_millis(2_000_000).expect("moment in range"); + +let quote = VoteQuoteBuilder::new() + .serial(1u64) + .issuer(issuer.clone()) + .validity(from, to) + .add_block(issuer.to_opening_hash()) + .fees(Fees::Single { + quote: true, + fee: Fee { amount: 1u64.into(), pay_to: None, token: None }, + }) + .build(issuer.as_ref())?; +assert!(quote.as_vote().is_quote()); +# Ok::<(), keetanetwork_vote::VoteError>(()) +``` + ## Related documents - [Architecture](ARCHITECTURE.md) diff --git a/keetanetwork-x509/docs/ARCHITECTURE.md b/keetanetwork-x509/docs/ARCHITECTURE.md index 4bf61e7..64ca09b 100644 --- a/keetanetwork-x509/docs/ARCHITECTURE.md +++ b/keetanetwork-x509/docs/ARCHITECTURE.md @@ -2,34 +2,47 @@ ## Abstract -This page is the consumer contract for `keetanetwork-x509`. The crate owns certificate builders and stores. Account crate traits sign and verify those artifacts. Block, bindings, and the host ABI crates consume the resulting certificates. +This page is the internal design of `keetanetwork-x509`. The crate builds, stores, and validates certificates. Account crate traits sign and verify those artifacts. This crate does not grow a second signer trait. ## Purpose -An engineer reads this page before adding a certificate builder in another crate. After reading, the engineer knows the split between account traits and x509 builders, and which crates consume the builders. +An engineer reads this page before adding a certificate builder in another crate. After reading, the engineer can name the module that owns builders, certificate types, distinguished names, and validation. -## Ownership +## Internal design -`keetanetwork-x509` owns builders, parsers, stores, and validation for X.509 certificates. Crate rustdoc in `keetanetwork-x509/src/lib.rs` is the field reference. +`builder` owns `CertificateBuilder` and `ExtensionBuilder`. A builder assembles subject, issuer, serial, validity, and extensions, then signs through `CertSigner` on the account crate. -`CertSigner` and `CertVerifier` live on `keetanetwork-account`. This crate calls those traits. It does not grow a second signer trait. +`certificates` owns the parsed certificate types and verification entry points. `utils` owns `create_dn` and other name helpers. `oids` owns certificate object identifiers. `asn1` owns crate-local ASN.1 helpers used by builders. `error` owns `CertificateError`. -Builder, bundle, and validation cookbooks live in `keetanetwork-x509/tests/builders.rs`, `keetanetwork-x509/tests/bundles.rs`, and `keetanetwork-x509/tests/validation.rs`. +`serde` is present when the `serde` feature is on. `testing` and `doc_utils` are test and rustdoc helpers. -## Who consumes this crate +```mermaid +flowchart LR + mod_utils[utils] + mod_builder[builder] + mod_certs[certificates] + mod_oids[oids] + crate_account[keetanetwork-account] + crate_asn1[keetanetwork-asn1] + crate_block[keetanetwork-block] + mod_oids --> mod_utils + mod_utils -->|DistinguishedName| mod_builder + crate_account -->|CertSigner| mod_builder + crate_asn1 --> mod_builder + mod_builder -->|signed certificate| mod_certs + mod_certs --> crate_block +``` -`keetanetwork-block` depends on this crate so a block can carry certificate material. `keetanetwork-bindings`, `keetanetwork-client-wasm`, and `keetanetwork-client-wasi` depend on this crate so host ABIs can project certificates. +## Collaboration -[Account](../../keetanetwork-account/docs/ARCHITECTURE.md) holds the signer and verifier traits. [Architecture](../../docs/ARCHITECTURE.md) holds the collaboration graph. +Inbound: `keetanetwork-account` supplies `CertSigner` and `CertVerifier`. `keetanetwork-asn1` and `keetanetwork-crypto` supply encodings and key material. `keetanetwork-utils` with the `build` feature supports the crate build script. -## Feature contract - -Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`, `keetanetwork-crypto`, and `keetanetwork-account`. +Outbound: `keetanetwork-block` depends on this crate so a block can carry certificate material. `keetanetwork-bindings`, `keetanetwork-client-wasm`, and `keetanetwork-client-wasi` project certificates at host ABIs. -The crate build depends on `keetanetwork-utils` with the `build` feature. [Utils](../../keetanetwork-utils/docs/ARCHITECTURE.md) holds that helper. +## Feature contract -A `no_std` consumer enables `alloc` and at least one of `der` or `rasn`. [ASN.1](../../keetanetwork-asn1/docs/ARCHITECTURE.md) holds the at-least-one codec contract. +Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`, `keetanetwork-crypto`, and `keetanetwork-account`. A `no_std` consumer enables `alloc` and at least one codec. ## Falsified by -A change that moves certificate builders or stores off `keetanetwork-x509`. A change that adds a signer trait on this crate that duplicates `CertSigner` or `CertVerifier`. A change to the `der` / `rasn` forwarding in `keetanetwork-x509/Cargo.toml`. +A change that moves certificate builders or stores off this crate. A change that adds a signer trait on this crate that duplicates `CertSigner` or `CertVerifier`. A change to the `der` / `rasn` forwarding in `keetanetwork-x509/Cargo.toml`. diff --git a/keetanetwork-x509/docs/README.md b/keetanetwork-x509/docs/README.md index 4328467..fabb9b0 100644 --- a/keetanetwork-x509/docs/README.md +++ b/keetanetwork-x509/docs/README.md @@ -1,10 +1,10 @@ # keetanetwork-x509 -This crate owns X.509 certificate builders, stores, and validation. Account crate traits `CertSigner` and `CertVerifier` sign and verify those artifacts. Block, bindings, and the host ABI crates consume the resulting certificates. +This crate owns X.509 certificate builders, stores, and validation. Account crate traits `CertSigner` and `CertVerifier` sign and verify those artifacts. ## Quickstart -Default features are `std`, `serde`, and `rasn`. `std` implies `alloc`. Features `der` and `rasn` forward to `keetanetwork-asn1`. +Default features are `std`, `serde`, and `rasn`. Features `der` and `rasn` forward to `keetanetwork-asn1`. ```bash cargo test -p keetanetwork-x509 @@ -12,7 +12,25 @@ cargo test -p keetanetwork-x509 `make test-feat` also runs this crate with `std,der` and `std,rasn`. -## Example +## Examples + +### Distinguished name + +From `keetanetwork-x509/src/utils.rs` rustdoc on `create_dn`. + +```rust +use keetanetwork_asn1::oids; +use keetanetwork_x509::utils::create_dn; + +let pairs = &[ + (oids::CN, "example.com"), + (oids::O, "Example Organization"), +]; +let dn = create_dn(pairs)?; +# Ok::<(), Box>(()) +``` + +### Certificate builder From `keetanetwork-x509/src/builder.rs` rustdoc.