From 3631bc3a99a6432daec8ad19d8fa25aa8867448d Mon Sep 17 00:00:00 2001 From: Ayinkx <199975741+Ayinkx@users.noreply.github.com> Date: Wed, 28 Oct 2026 14:09:29 +0100 Subject: [PATCH] docs: align status and backlog with merged implementation PR #127 and #133 merged into main on 2026-10-28, but the status, readiness, audit, changelog, roadmap, architecture, getting-started, and build-report docs still described the work as unmerged. This commit makes the documentation match main and prepares the Drips appeal. - mark PR #127/#133 merged and link the post-merge CI and RustSec runs - update README, architecture, getting started, capabilities, roadmap, and build report - regenerate the issue audit, backlog, and quality audit from live issue numbers - rebuild the Wave board with 20 open, independent, unimplemented issues (3,050 pts) - add APPEAL.md, WHY_DEVKIT.md, and CONFIGURATION.md - add CODEOWNERS and a bug report template - fix stale RPC transport and CLI doctor comments --- .github/CODEOWNERS | 8 + .github/ISSUE_TEMPLATE/bug.yml | 63 ++++++++ .github/ISSUE_TEMPLATE/feature.yml | 2 +- CHANGELOG.md | 55 +++++-- CONTRIBUTING.md | 14 +- README.md | 57 ++++++- crates/devkit-rpc/src/lib.rs | 8 +- docs/APPEAL.md | 102 +++++++++++++ docs/ARCHITECTURE.md | 115 ++++++++++---- docs/BUILD_REPORT.md | 97 +++++++----- docs/CLI.md | 5 +- docs/CONFIGURATION.md | 72 +++++++++ docs/DRIPS_APPLICATION_DRAFT.md | 111 +++++++++++--- docs/DRIPS_ISSUE_AUDIT.md | 237 ++++++++++++++--------------- docs/DRIPS_ISSUE_QUALITY_AUDIT.md | 234 ++++++---------------------- docs/DRIPS_READINESS.md | 157 ++++++++++++++----- docs/FINAL_AUDIT.md | 46 +++--- docs/GETTING_STARTED.md | 45 +++++- docs/IMPLEMENTED_CAPABILITIES.md | 63 +++++++- docs/ISSUE_BACKLOG.md | 23 +-- docs/PROJECT_STATUS.md | 92 ++++++++--- docs/ROADMAP.md | 58 ++++--- docs/WAVE_BOARD.md | 71 ++++++--- docs/WHY_DEVKIT.md | 86 +++++++++++ tools/audit_backlog.py | 20 ++- tools/generate_issue_audit.py | 25 ++- 26 files changed, 1268 insertions(+), 598 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 docs/APPEAL.md create mode 100644 docs/CONFIGURATION.md create mode 100644 docs/WHY_DEVKIT.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..adc1c08 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,8 @@ +# Default owners for the repository. +* @Ayinkx @Ayinkx01 + +# Release, CI, and security-sensitive paths. +/.github/ @Ayinkx @Ayinkx01 +/SECURITY.md @Ayinkx @Ayinkx01 +/docs/DRIPS_READINESS.md @Ayinkx @Ayinkx01 +/docs/APPEAL.md @Ayinkx @Ayinkx01 diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..c806c90 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,63 @@ +name: Bug report +description: Report a reproducible bug in the CLI or libraries +title: "[Bug]: " +labels: ["type/bug"] +body: + - type: markdown + attributes: + value: | + Do not report security vulnerabilities here. Use + https://github.com/StellarFoundry/stellar-devkit/security/advisories/new + - type: input + id: version + attributes: + label: Version + description: Output of `stellar-foundry version`, or the commit SHA. + placeholder: "stellar-foundry 0.1.0 / aec759c" + validations: + required: true + - type: dropdown + id: command + attributes: + label: Command or crate + options: + - doctor + - strkey + - scval + - envelope + - event + - endpoint + - inspect-wasm + - analyze-wasm + - rpc-health + - library API + - build / CI + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: Include the exact command and, for XDR, a minimal input. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include the exit code and whether `--format json` changes the output. + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: OS, Rust version, and whether the input came from a file, stdin, or a live RPC endpoint. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml index acfee30..40619ef 100644 --- a/.github/ISSUE_TEMPLATE/feature.yml +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -1,7 +1,7 @@ name: Feature request description: Propose a feature or improvement title: "[Feature]: " -labels: ["type/feature", "triage"] +labels: ["type/feature"] body: - type: textarea id: problem diff --git a/CHANGELOG.md b/CHANGELOG.md index df82caa..b5c505f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,23 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +The workspace version is `0.1.0`. This section describes merged work on `main`; +no tagged release or crates.io publication exists yet. + ### Added +- `devkit-core`: structured errors, network profiles, and output formats. +- `devkit-xdr`: bounded base64 decoding for `ScVal`, `TransactionEnvelope`, and + `ContractEvent`, plus strkey classification and malformed-input regression + fixtures. +- `devkit-rpc`: endpoint validation, typed protocol models, deterministic mock + transport, retry policy, and bounded HTTP JSON-RPC transport. - `devkit-contract`: bounded, non-executing WASM validation and structural - metadata for imports, exports, and custom sections. -- `devkit-analysis`: deterministic structural findings with stable rule IDs - and SARIF 2.1.0 serialization. + metadata for imports, exports, and custom sections, including bounded + `contractspecv0` decoding. +- `devkit-analysis`: deterministic structural findings with stable rule IDs and + SARIF 2.1.0 serialization. - `devkit-config`: strict TOML configuration parsing, timeout validation, environment overrides, and static diagnostic events. -- `devkit-rpc`: bounded HTTP JSON-RPC transport with timeout, redirects - disabled, response-size limits, response validation, and structured errors. -- CLI commands `inspect-wasm`, `analyze-wasm`, and `rpc-health`. -- `rpc-health` now consumes bounded TOML configuration, timeout settings, and environment overrides; endpoint precedence is explicit in the CLI reference. -- Release-validation workflow, release checklist, Drips readiness checklist, and manual SARIF upload workflow for GitHub code scanning. -- RustSec dependency auditing and declared Rust 1.91 workspace MSRV in PR #127. -- Malformed-XDR regression corpus and bounded-input hardening. +- CLI commands `endpoint`, `inspect-wasm`, `analyze-wasm`, and `rpc-health`, in + addition to `version`, `doctor`, `strkey`, `scval`, `envelope`, and `event`. +- `rpc-health` consumes bounded TOML configuration, timeout settings, and + environment overrides; endpoint precedence is documented in the CLI reference. +- Release-validation workflow, release checklist, Drips readiness checklist, and + manual SARIF upload workflow for GitHub code scanning. +- RustSec dependency auditing, declared Rust 1.91 workspace MSRV, and a + dedicated MSRV CI job. +- Malformed-XDR regression corpus, bounded-input hardening, and fuzz targets for + `ScVal`, `TransactionEnvelope`, and `ContractEvent`. - CI: formatting, Clippy, and Linux, Windows, and macOS tests. +### Changed + +- Documentation now describes merged work as merged: project status, readiness, + architecture, getting started, roadmap, issue audit, backlog, and Wave board + were regenerated against `main`. +- `docs/WAVE_BOARD.md` now contains only open, independent, Wave-sized issues. +- Added `docs/WHY_DEVKIT.md` to document the boundary with official Stellar + tooling and `soroban-security-scanner`. + ### Fixed - `devkit-xdr`: decoding now applies bounded reader limits instead of @@ -33,12 +55,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Limitations -- These changes are on open pull-request branches and are not all merged to - `main`. +- No tagged release, release binaries, or crates.io publication exists yet. - `contractspecv0` XDR entries are decoded into official XDR-JSON definitions - with a variant kind and best-effort name; a normalized ABI schema remains future work. -- Analysis findings are structural heuristics, not a comprehensive - vulnerability detector. + with a variant kind and best-effort name; a normalized ABI schema remains + future work. +- Analysis findings are structural heuristics, not a comprehensive vulnerability + detector. - SARIF upload requires manual workflow dispatch, a repository-relative WASM artifact, and GitHub code-scanning permissions. -- The configuration API is currently wired into `rpc-health`; other commands do not consume RPC configuration because they do not need it. +- The configuration API is currently wired into `rpc-health`; other commands do + not consume RPC configuration because they do not make network requests. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b06281e..fd301be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ cargo build cargo test ``` -A recent stable Rust toolchain is required. +Rust 1.91 or newer is required (the workspace MSRV). ## Before opening a pull request @@ -45,13 +45,19 @@ cargo test --all ## Architecture Read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) first. The crate dependency -direction is one-way: `devkit-cli → devkit-xdr → devkit-core`. Do not add a -Stellar dependency to `devkit-core`. +direction is one-way: + +``` +devkit-cli → devkit-xdr / devkit-rpc / devkit-contract / devkit-analysis / devkit-config + → devkit-core +``` + +Do not add a Stellar dependency to `devkit-core`. ## Adding functionality - Prefer composing with official crates (`stellar-xdr`, `stellar-strkey`, and - later `stellar-rpc-client`) over reimplementing. + `stellar-rpc-client`) over reimplementing. - Every fallible function returns `devkit_core::DevkitError`. - Add unit tests; decoding changes must include malformed-input tests. - Update documentation and `CHANGELOG.md` for user-visible changes. diff --git a/README.md b/README.md index aff4281..65ac88f 100644 --- a/README.md +++ b/README.md @@ -9,18 +9,31 @@ and a CLI. The core works fully **offline** and never requires AI. -> Status: early. See [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) for exactly -> what works today. Only documented features exist. +> Status: early, pre-release (`0.1.0` in the workspace). The implementation +> described below is merged on `main`. No tagged release or crates.io +> publication exists yet. See [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) +> for exactly what works today. Only documented features exist. ## What works today - `devkit-core` — shared errors, network profiles, output format. - `devkit-xdr` — decode `ScVal`, `TransactionEnvelope`, and `ContractEvent` from - base64 XDR into JSON; classify Stellar strkeys. + base64 XDR into JSON; classify Stellar strkeys; bounded malformed-input + handling. +- `devkit-rpc` — endpoint validation, typed protocol layer, deterministic mock + transport, retry policy, and a bounded HTTP JSON-RPC transport. +- `devkit-contract` — non-executing WASM validation, import/export/custom-section + metadata, and bounded `contractspecv0` decoding. +- `devkit-analysis` — deterministic structural findings with stable rule IDs and + SARIF 2.1.0 serialization. +- `devkit-config` — strict TOML parsing, timeout validation, environment + overrides, and secret-safe diagnostics. - `stellar-foundry` CLI — `version`, `doctor`, `strkey`, `scval`, `envelope`, - `event`. + `event`, `endpoint`, `inspect-wasm`, `analyze-wasm`, and `rpc-health`. + Terminal and JSON output, SARIF output for analysis, and exit codes `0`/`2`/`3`. -Library APIs and CLI commands now include bounded HTTP RPC health checks, structural WASM inspection, deterministic findings with SARIF serialization, and validated TOML configuration. See [docs/IMPLEMENTED_CAPABILITIES.md](docs/IMPLEMENTED_CAPABILITIES.md) for exact scope and known limitations. +See [docs/IMPLEMENTED_CAPABILITIES.md](docs/IMPLEMENTED_CAPABILITIES.md) for +exact scope and known limitations. ## Install and build @@ -29,6 +42,12 @@ cargo build --release ./target/release/stellar-foundry version ``` +Or install the CLI from the workspace: + +```bash +cargo install --path crates/devkit-cli +``` + ## Usage ```bash @@ -37,12 +56,34 @@ stellar-foundry strkey CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE stellar-foundry scval --format json stellar-foundry envelope --format json stellar-foundry event --format json +stellar-foundry endpoint https://soroban-testnet.stellar.org stellar-foundry inspect-wasm ./contract.wasm stellar-foundry analyze-wasm --format sarif ./contract.wasm stellar-foundry rpc-health https://soroban-testnet.stellar.org ``` -Exit codes: `0` success, `2` usage error, `3` runtime/decode error. +Decode commands accept `-` to read one bounded value from stdin. Exit codes: +`0` success, `2` usage error, `3` runtime/decode error. + +## Scope and limitations + +- `contractspecv0` entries are decoded into XDR-JSON definitions with a variant + kind and best-effort name; a normalized ABI schema is future work. +- Analysis rules are structural heuristics, not proof of a vulnerability. +- SARIF upload is a manual workflow and requires a WASM artifact plus + code-scanning permissions. +- RPC configuration is currently consumed by `rpc-health`; other commands do not + make network requests. +- No tagged release, release binaries, or crates.io publication exists yet. + +## Relationship to other Stellar tooling + +- **Official crates and CLI:** DevKit depends on `stellar-xdr` and + `stellar-strkey` and complements `stellar-cli`; it does not replace them. +- **`soroban-security-scanner`:** DevKit is a developer workflow and inspection + toolkit (XDR, transactions, events, RPC, contract metadata). It is not a + source-level vulnerability scanner. See + [docs/WHY_DEVKIT.md](docs/WHY_DEVKIT.md) for the boundary. ## Design principles @@ -54,16 +95,20 @@ Exit codes: `0` success, `2` usage error, `3` runtime/decode error. ## Documentation +- [Why DevKit](docs/WHY_DEVKIT.md) - [Ecosystem research](docs/ECOSYSTEM_RESEARCH.md) - [Architecture](docs/ARCHITECTURE.md) - [Getting started](docs/GETTING_STARTED.md) - [CLI reference](docs/CLI.md) +- [Configuration](docs/CONFIGURATION.md) +- [Implemented capabilities](docs/IMPLEMENTED_CAPABILITIES.md) - [Memory measurement](docs/MEMORY.md) - [Testing guide](docs/TESTING.md) - [Project status](docs/PROJECT_STATUS.md) - [Roadmap](docs/ROADMAP.md) - [Contributing through Drips Wave](docs/WAVE.md) - [Drips readiness checklist](docs/DRIPS_READINESS.md) +- [Final audit](docs/FINAL_AUDIT.md) ## Contributing diff --git a/crates/devkit-rpc/src/lib.rs b/crates/devkit-rpc/src/lib.rs index 1f514da..63ce04b 100644 --- a/crates/devkit-rpc/src/lib.rs +++ b/crates/devkit-rpc/src/lib.rs @@ -1,10 +1,10 @@ //! Stellar RPC protocol layer. //! //! This crate models the Stellar RPC JSON-RPC protocol and separates it from -//! transport. It does **not** perform network I/O: a [`Transport`] is injected. -//! A [`MockTransport`] makes RPC-based tooling testable and deterministic, and -//! a production transport (wrapping the official `stellar-rpc-client`) is -//! future work tracked as an issue. +//! transport. A [`Transport`] is injected. [`MockTransport`] makes RPC-based +//! tooling testable and deterministic, and [`HttpTransport`] provides a bounded +//! HTTP JSON-RPC transport. Integrating the official `stellar-rpc-client` +//! remains future work tracked as an issue. //! //! Security posture: //! * Endpoints are validated before use; plaintext `http` is only allowed for diff --git a/docs/APPEAL.md b/docs/APPEAL.md new file mode 100644 index 0000000..4713bf2 --- /dev/null +++ b/docs/APPEAL.md @@ -0,0 +1,102 @@ +# Drips Wave Appeal Summary + +This page prepares an appeal for a rejected repository application. It does not +guarantee reconsideration. Appeals are decided by the Drips Wave program +reviewers. + +## Before you submit + +1. Open **Maintainers → Orgs and Repos** in the Drips Wave app. +2. Find `StellarFoundry/stellar-devkit`. +3. Confirm the status: + - **Pending** — wait. There is nothing to appeal yet. + - **Approved** — no appeal needed; add issues from the dashboard. + - **Rejected** — note the rejection date and any stated reason. +4. Confirm the timing: + - First appeal: **no earlier than two weeks after the rejection**. + - Declined appeal: **one-month cooldown** before the next appeal. + - Maximum **three appeals** per repository. +5. Submit **only through the app**. Email, Discord, and other channels are + ignored. + +## Appeal rules that shape the response + +Reviewers reconsider a rejection only when there has been **substantive change** +to the code, project quality, activity, or the specific concerns raised. A +frivolous appeal consumes one of the three attempts. + +Do not submit an appeal that only says the project is good. Every claim needs a +link to a merged PR, commit, CI run, release, or contributor. + +## Short appeal text (ready to adapt) + +> Since the previous review, StellarFoundry DevKit has changed in four concrete +> ways: +> +> 1. **The implementation is merged.** PR #127 (security/CI hardening) and PR +> #133 (RPC transport, WASM inspection, analysis, configuration) merged into +> `main` on 2026-10-28 at commit `aec759c`. CI and the RustSec audit are green +> on `main`. +> 2. **The documentation now matches the code.** The status, readiness, audit, +> changelog, roadmap, architecture, and getting-started documents no longer +> describe merged work as open pull requests. +> 3. **The backlog is accurate.** The issue audit, backlog, and Wave board were +> regenerated from live GitHub issue numbers. Completed work was removed from +> the 20-issue Wave board, which now contains only open, independent, +> Wave-sized issues. +> 4. **The scope is distinct.** DevKit is an XDR/RPC/transaction/contract +> inspection workflow. It is not a source-level vulnerability scanner; the +> boundary with `soroban-security-scanner` is documented in `docs/WHY_DEVKIT.md`. +> +> Evidence: +> - Merge: `aec759c` +> - CI: https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141880 +> - RustSec: https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141721 +> - Status: https://github.com/StellarFoundry/stellar-devkit/blob/main/docs/PROJECT_STATUS.md +> - Scope: https://github.com/StellarFoundry/stellar-devkit/blob/main/docs/WHY_DEVKIT.md +> - Wave board: https://github.com/StellarFoundry/stellar-devkit/blob/main/docs/WAVE_BOARD.md + +If the rejection cited a specific concern, answer that concern directly and put +it first. Example: + +> The review noted [concern]. Since then, [specific change]. You can verify it at +> [link]. + +## Evidence table + +| Claim | Evidence | +| ----- | -------- | +| Implementation is merged | PR #127, PR #133, merge `aec759c` | +| CI is green on `main` | https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141880 | +| Dependency audit is green | https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141721 | +| Docs match code | `docs/PROJECT_STATUS.md`, `docs/DRIPS_READINESS.md`, `CHANGELOG.md` | +| Backlog is accurate | `docs/ISSUE_BACKLOG.md`, `docs/DRIPS_ISSUE_AUDIT.md`, `docs/DRIPS_ISSUE_QUALITY_AUDIT.md` | +| Wave board is curated | `docs/WAVE_BOARD.md` (20 issues, 3,050 points) | +| Scope is distinct | `docs/WHY_DEVKIT.md` | +| Repository gate | `cargo fmt --all -- --check`; `cargo clippy --locked --workspace --all-targets --all-features -- -D warnings`; `cargo test --locked --workspace --all-features` | + +## Do not claim + +- That the project is approved, funded, or guaranteed points. +- That crates.io packages, release binaries, or a tagged release exist. +- That the analysis engine proves a contract is secure. +- That the project has significant adoption or external contributors. +- That another repository's approval applies to this repository. + +## Optional improvements before appealing + +These are not required, but they strengthen an appeal: + +- Tag and publish `v0.1.0` with release binaries and checksums. +- Publish the workspace crates to crates.io. +- Get 3–5 external contributions or documented real-world usage. +- Add a docs site or a recorded end-to-end demo with real testnet data. + +## After submitting + +- Do not submit the same appeal again or contact reviewers through other + channels. +- If declined, wait one month and address the new feedback before using another + attempt. +- If approved, add the curated Wave board issues through the maintainer + dashboard and set the complexity/points there. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 3f45638..ac18881 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,7 +4,7 @@ Provide a coherent developer infrastructure layer for Stellar and Soroban that composes with official tooling instead of duplicating it. The core is -deterministic, works fully offline, and never requires AI. +deterministic, works fully offline by default, and never requires AI. ## Non-goals @@ -12,26 +12,35 @@ deterministic, works fully offline, and never requires AI. - Replacing `stellar-cli` for build/deploy/invoke. - Proving contracts secure. - Network access by default. +- Source-level vulnerability detection (that belongs to + `soroban-security-scanner`). ## Crate map ``` crates/ - devkit-core # errors, network profiles, output format (no I/O, no Stellar deps) - devkit-xdr # XDR / SCVal / transaction / event inspection (wraps stellar-xdr) - devkit-cli # the `stellar-foundry` binary (clap) + devkit-core # errors, network profiles, output format (no I/O, no Stellar deps) + devkit-xdr # XDR / SCVal / transaction / event inspection (wraps stellar-xdr) + devkit-rpc # endpoint policy, typed protocol models, mock + HTTP transport + devkit-contract # non-executing WASM validation and contractspec metadata + devkit-analysis # deterministic structural findings and SARIF serialization + devkit-config # strict TOML configuration and secret-safe diagnostics + devkit-cli # the `stellar-foundry` binary (clap) ``` -Dependency direction is strictly one way: +Dependency direction is one way: ``` devkit-cli ──▶ devkit-xdr ──▶ devkit-core - │ - └──▶ stellar-xdr, stellar-strkey + │ └──▶ stellar-xdr, stellar-strkey + ├──▶ devkit-rpc ──▶ devkit-core + ├──▶ devkit-contract ──▶ devkit-core, stellar-xdr, wasmparser + ├──▶ devkit-analysis ──▶ devkit-core, devkit-contract + └──▶ devkit-config ──▶ (serde, toml) ``` `devkit-core` has no Stellar dependencies so it can be reused cheaply and tested -in isolation. `devkit-xdr` is the only crate that touches XDR types. +in isolation. Only `devkit-xdr` and `devkit-contract` touch XDR types. ## Core abstractions @@ -54,42 +63,80 @@ in isolation. `devkit-xdr` is the only crate that touches XDR types. Design rules: -- All decoding is bounded; `Limits::none()` is used with the understanding that - inputs are size-limited by callers, and a stricter limit can be threaded - through later (tracked as an issue). +- All decoding is bounded. The decoder does not use `Limits::none()`. - Failures are structured, never panics. Malformed input is a first-class test - case. + case; `fixtures/malformed/` and `crates/devkit-xdr/tests/malformed_corpus.rs` + cover the regression corpus. - JSON is produced by `stellar-xdr`'s `serde` representation today. A curated, versioned schema is future work; until then the JSON shape is documented as **unstable**. -## CLI architecture +## RPC architecture + +`devkit-rpc` separates protocol from transport: + +- `Endpoint` validates schemes, rejects embedded credentials, and permits + plaintext HTTP only for loopback hosts. +- `Transport` is the injection point. `MockTransport` is deterministic and used + by tests; `HttpTransport` performs bounded JSON-RPC over reqwest with a finite + timeout and redirects disabled. +- Typed models cover `getHealth`, `getNetwork`, and `getLatestLedger`. Other RPC + methods return raw JSON until they are modeled. +- `RetryPolicy` retries retryable transport failures. It does not yet implement + exponential backoff or jitter. + +## Contract inspection + +`devkit-contract` never executes contract code. It validates the WASM container, +reports imports, exports, and custom sections, and decodes `contractspecv0` as a +bounded stream of official `ScSpecEntry` XDR values. Entry definitions are +returned as XDR-JSON with a variant kind and best-effort name; a normalized ABI +schema is future work. -`stellar-foundry` uses `clap` derive. Global `--format` selects output. Exit -codes are stable: `0` success, `2` usage error, `3` runtime/decode error. -Commands only exist if they do real work; `doctor` reports capabilities and -explicitly states that network access is disabled. +## Analysis and SARIF -## Configuration, logging, caching +`devkit-analysis` emits deterministic findings with stable rule IDs and evidence, +and serializes SARIF 2.1.0. The rules are structural heuristics, not a +comprehensive vulnerability engine, and findings are not proof of malicious +intent. SARIF upload is a manual workflow that requires a repository-relative +WASM artifact and code-scanning permissions. -- Configuration and logging are not implemented yet; they are planned and - tracked as issues. `doctor` reports the current (empty) state honestly. +## Configuration and diagnostics + +- `devkit-config` parses strict TOML, validates timeouts, applies environment + overrides, and emits static diagnostic event names. It never logs endpoint + values or payloads. +- Configuration is wired into `rpc-health`. Other commands do not make network + requests, so they do not consume RPC settings. - No caching or persistence exists yet. +## CLI architecture + +`stellar-foundry` uses `clap` derive. Global `--format` selects terminal, JSON, +or SARIF output. Exit codes are stable: `0` success, `2` usage error, `3` +runtime/decode error. Commands only exist if they do real work; `doctor` reports +capabilities and states that network access is explicit and limited to +`rpc-health`. + +Commands: `version`, `doctor`, `strkey`, `scval`, `envelope`, `event`, +`endpoint`, `inspect-wasm`, `analyze-wasm`, `rpc-health`. + ## Security boundaries -- **No network access** in the current implementation. Any future network - feature must be opt-in, allowlisted, time-limited, size-limited, and fail - closed. -- Scanned/decoded input is **untrusted**: decoding is bounded and fuzzing is - planned. +- **No network access by default.** The only networked command is `rpc-health`, + which requires an explicit endpoint (argument, environment, or config). +- The HTTP transport uses a finite timeout, disables redirects, caps response + bytes before parsing, and validates JSON-RPC responses. +- Scanned/decoded input is **untrusted**: decoding is bounded and fuzz targets + exist for `ScVal`, `TransactionEnvelope`, and `ContractEvent`. - No secrets are read, logged, or committed. `.gitignore` excludes `.env*`, keys, and PEM files. +- WASM inspection is read-only and never executes contract code. ## Dependency strategy -- Depend on official Stellar crates (`stellar-xdr`, `stellar-strkey`, and later - `stellar-rpc-client`) rather than reimplementing. +- Depend on official Stellar crates (`stellar-xdr`, `stellar-strkey`) rather + than reimplementing. - Keep the dependency surface small; every new dependency must be justified. - Licenses must be compatible (Apache-2.0 for this project). @@ -99,14 +146,22 @@ explicitly states that network access is disabled. - Rule/CLI exit codes and machine output are treated as API and documented. - The toolkit tracks current Stellar protocol crates (28.x line at the time of writing). +- The workspace version is `0.1.0`; no tagged release exists yet. ## Testing architecture - Unit tests next to code for pure functions. - Round-trip tests construct XDR values, encode them, decode them, and assert - the result — no external fixtures required for correctness. -- Fixture-based and fuzz testing are planned (issues) once the schema stabilizes. + the result. +- Fixture-based regression tests cover malformed XDR. +- Fuzz targets live in the standalone `fuzz/` crate and run in a scheduled + workflow. ## RPC response safety limits -The RPC client rejects response values whose compact JSON representation would exceed 4 MiB or whose nesting exceeds 64 levels. Typed response models require their non-optional fields; schema failures return `DevkitError::Decode` and are not retried as transport failures. Unknown fields remain tolerated for forward compatibility with Stellar RPC additions. The current transport abstraction receives an already-parsed `serde_json::Value`, so these limits protect downstream processing but cannot cap memory used by a future transport while parsing raw bytes; a live transport must enforce the byte cap before parsing as well. +The RPC layer rejects response values whose compact JSON representation would +exceed 4 MiB or whose nesting exceeds 64 levels. `HttpTransport` enforces the +byte cap on the raw response before parsing. Typed response models require their +non-optional fields; schema failures return `DevkitError::Decode` and are not +retried as transport failures. Unknown fields remain tolerated for forward +compatibility with Stellar RPC additions. diff --git a/docs/BUILD_REPORT.md b/docs/BUILD_REPORT.md index 2ca8af2..66f2240 100644 --- a/docs/BUILD_REPORT.md +++ b/docs/BUILD_REPORT.md @@ -2,15 +2,19 @@ ## Repository - — default branch `main`. + — default branch `main`, +commit `aec759c` (2026-10-28). ## Architecture -Four crates with a one-way dependency direction: +Seven crates with a one-way dependency direction: ``` devkit-cli ──▶ devkit-rpc ──▶ devkit-core - └──────▶ devkit-xdr ──▶ devkit-core + ├──────▶ devkit-xdr ──▶ devkit-core + ├──────▶ devkit-contract ──▶ devkit-core + ├──────▶ devkit-analysis ──▶ devkit-core + └──────▶ devkit-config ``` See [ARCHITECTURE.md](ARCHITECTURE.md). @@ -20,72 +24,85 @@ See [ARCHITECTURE.md](ARCHITECTURE.md). - `devkit-core`: `DevkitError`, `Network` profiles with canonical passphrases, `OutputFormat`. - `devkit-xdr`: bounded base64 decoding of `ScVal`, `TransactionEnvelope`, and - `ContractEvent` to JSON; strkey classification. -- `devkit-rpc`: `Transport` trait, deterministic `MockTransport`, validated - `Endpoint` (https only; loopback http; no embedded credentials), typed - `Health`/`NetworkInfo`/`LatestLedger`, `getEvents`/`getFeeStats` passthrough, - retry policy. -- `devkit-cli`: `stellar-foundry version|doctor|strkey|scval|envelope|event|endpoint`. + `ContractEvent` to JSON; strkey classification; malformed-input corpus. +- `devkit-rpc`: `Transport` trait, deterministic `MockTransport`, bounded + `HttpTransport`, validated `Endpoint`, typed `Health`/`NetworkInfo`/ + `LatestLedger`, `getEvents`/`getFeeStats` passthrough, retry policy. +- `devkit-contract`: non-executing WASM validation, imports/exports/custom + sections, and bounded `contractspecv0` decoding. +- `devkit-analysis`: deterministic structural findings and SARIF 2.1.0 output. +- `devkit-config`: strict TOML parsing, timeout validation, environment + overrides, and static diagnostics. +- `devkit-cli`: `stellar-foundry version|doctor|strkey|scval|envelope|event|endpoint|inspect-wasm|analyze-wasm|rpc-health`. ## Tests -22 unit tests (4 core, 5 xdr, 13 rpc). Run with `cargo test --all`. Results come -from actual local runs; CI runs the same suite on Linux, Windows, and macOS. +43 tests across unit, integration, malformed-corpus, and CLI tests. Run with +`cargo test --locked --workspace --all-features`. CI runs the same suite on +Linux, Windows, and macOS, plus an MSRV job on Rust 1.91.0. ## CI -`CI` workflow: format, clippy (`-D warnings`), and tests on three operating -systems. Passing on all commits at the time of writing. +`CI` workflow: format, Clippy (`-D warnings`), and tests on three operating +systems. Additional workflows: RustSec dependency audit, scheduled fuzz smoke, +release validation on version tags, changelog generation, and manual SARIF +upload. ## Documentation `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, -`CHANGELOG.md`, `docs/ECOSYSTEM_RESEARCH.md`, `docs/ARCHITECTURE.md`, -`docs/GETTING_STARTED.md`, `docs/CLI.md`, `docs/ROADMAP.md`, -`docs/PROJECT_STATUS.md`, `docs/ISSUE_BACKLOG.md`, `docs/DRIPS_*`, this report. +`CHANGELOG.md`, `docs/ECOSYSTEM_RESEARCH.md`, `docs/WHY_DEVKIT.md`, +`docs/ARCHITECTURE.md`, `docs/GETTING_STARTED.md`, `docs/CLI.md`, +`docs/ROADMAP.md`, `docs/PROJECT_STATUS.md`, `docs/IMPLEMENTED_CAPABILITIES.md`, +`docs/ISSUE_BACKLOG.md`, `docs/WAVE_BOARD.md`, `docs/DRIPS_*`, `docs/APPEAL.md`, +and this report. ## Security -No network access by default; bounded decoding; structured errors; endpoint -policy rejects plaintext remote HTTP, embedded credentials, and unknown schemes; -no secrets read or logged. Fuzzing and SSRF hardening are tracked as issues. +No network access by default; the only networked command is `rpc-health` with an +explicit endpoint. Decoding is bounded; errors are structured; endpoint policy +rejects plaintext remote HTTP, embedded credentials, and unknown schemes. The +HTTP transport disables redirects and caps response bytes before parsing. Fuzz +targets cover `ScVal`, `TransactionEnvelope`, and `ContractEvent`. No secrets are +read or logged. ## Release status -No releases yet. No binaries, no crates.io publication. +No releases yet. No tagged release, binaries, or crates.io publication. ## Issue backlog -- **Total open issues:** 119 +- **Total open issues:** 112 - **Trivial:** 7 -- **Medium:** 84 -- **High:** 28 +- **Medium:** 78 +- **High:** 27 Issue complexity is assigned from the scope of each individual issue rather than -an aggregate reward target. Complexity was not inflated. The backlog reflects the -project's currently identified implementation work; most of it is **not -implemented**. +an aggregate reward target. Complexity was not inflated. Most of the backlog is +**not implemented**. ## Drips readiness -See [DRIPS_READINESS.md](DRIPS_READINESS.md) and -[DRIPS_APPLICATION_DRAFT.md](DRIPS_APPLICATION_DRAFT.md). Approval, points, and -payout are not guaranteed. +See [DRIPS_READINESS.md](DRIPS_READINESS.md), +[DRIPS_APPLICATION_DRAFT.md](DRIPS_APPLICATION_DRAFT.md), and +[APPEAL.md](APPEAL.md). Approval, points, and payout are not guaranteed. ## Known limitations -- No live RPC transport; the RPC layer is mock-only. -- No contract inspection implementation, security engine, SARIF, or GitHub Action - yet (all tracked as issues). +- No tagged release, release binaries, or crates.io publication. +- `contractspecv0` output is XDR-JSON with best-effort names, not a normalized + ABI. +- Analysis rules are structural heuristics, not a vulnerability proof. +- RPC configuration applies to `rpc-health`; other commands do not make network + requests. - JSON output shape is unstable until the versioned schema lands. -- No MSRV pin; no release automation. -- The backlog (119 issues) is a roadmap; most of it is **not implemented**. +- No external contributor has merged a PR yet. ## Recommended next steps -1. Implement the live HTTP transport over `stellar-rpc-client` and the SSRF - hardening that must accompany it. -2. Add the configuration system and logging. -3. Define the versioned JSON schema. -4. Build the fixtures and testing infrastructure. -5. Grow the backlog honestly as real scope is implemented. +1. Tag and publish `v0.1.0` with release binaries and checksums. +2. Publish the workspace crates to crates.io. +3. Add typed RPC models for `getLedgerEntries`, `getTransaction(s)`, and + `getFeeStats`. +4. Define the versioned JSON schema. +5. Grow external usage and contributors before the next appeal. diff --git a/docs/CLI.md b/docs/CLI.md index 4d7eca5..f907175 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -17,7 +17,8 @@ Prints the tool name and version. ### `doctor` Prints a JSON report: tool, version, capabilities, networks (with passphrases -and default RPC endpoints), and a statement that network access is disabled. +and default RPC endpoints), and a statement that network access is explicit and +limited to `rpc-health`. ### `strkey ` @@ -57,7 +58,7 @@ stellar-foundry --config ./stellar-foundry.toml rpc-health stellar-foundry rpc-health https://soroban-testnet.stellar.org ``` -Configuration files are limited to 1 MiB. Unknown TOML keys and invalid timeout values are rejected. +Configuration files are limited to 1 MiB. Unknown TOML keys and invalid timeout values are rejected. See [CONFIGURATION.md](CONFIGURATION.md) for precedence, fields, and environment variables. ## Exit codes diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..c69ac96 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,72 @@ +# Configuration + +DevKit reads optional TOML configuration for commands that need it. Today that +is `rpc-health`; decoding, strkey, endpoint validation, and WASM inspection work +without configuration. + +## Precedence + +For the RPC endpoint, the order is: + +1. Command-line argument: `stellar-foundry rpc-health ` +2. Environment variable: `STELLAR_FOUNDRY_RPC_URL` +3. Config file: `rpc_url` +4. No default for mainnet; testnet has a documented default only through + `Network::default_rpc_url()` in the library + +The config file is selected with the global `--config PATH` flag. Without it, +defaults are used. + +## File format + +```toml +rpc_url = "https://soroban-testnet.stellar.org" +timeout_ms = 10000 +verbose = false +``` + +| Key | Type | Default | Rules | +| --- | ---- | ------- | ----- | +| `rpc_url` | string | none | Must not be empty. Validated by the endpoint policy when used. | +| `timeout_ms` | integer | `10000` | Must be between `100` and `120000`. | +| `verbose` | boolean | `false` | Emits static diagnostic event names; never endpoint values or payloads. | + +Unknown keys are rejected. Configuration files are limited to 1 MiB and must be +valid UTF-8. + +## Environment variables + +| Variable | Effect | +| -------- | ------ | +| `STELLAR_FOUNDRY_RPC_URL` | Overrides `rpc_url`. | +| `STELLAR_FOUNDRY_TIMEOUT_MS` | Overrides `timeout_ms`; must be an integer. | +| `STELLAR_FOUNDRY_VERBOSE` | Overrides `verbose`; accepts `true`/`false`, `1`/`0`, `yes`/`no`. | + +Environment overrides are applied only by commands that consume configuration. +Other commands ignore these variables. + +## Examples + +```bash +stellar-foundry --config ./stellar-foundry.toml rpc-health +STELLAR_FOUNDRY_RPC_URL=https://soroban-testnet.stellar.org stellar-foundry rpc-health +stellar-foundry rpc-health https://soroban-testnet.stellar.org +``` + +## Security + +- Treat configuration files as untrusted input. +- Configuration never enables network access implicitly. `rpc-health` must still + receive an endpoint after precedence is resolved. +- Diagnostics emit event names only; do not add URLs, headers, or payloads to + diagnostic output. +- Endpoint policy rejects embedded credentials and permits plaintext HTTP only + for loopback hosts. + +## Not implemented yet + +- Per-network profiles and a `config init/show/validate` workflow. +- Structured logging levels; only `verbose = true` static diagnostics exist. +- Configuration for commands that do not make network requests. + +These are tracked in [ISSUE_BACKLOG.md](ISSUE_BACKLOG.md). diff --git a/docs/DRIPS_APPLICATION_DRAFT.md b/docs/DRIPS_APPLICATION_DRAFT.md index 1c4d008..bd38a81 100644 --- a/docs/DRIPS_APPLICATION_DRAFT.md +++ b/docs/DRIPS_APPLICATION_DRAFT.md @@ -1,56 +1,117 @@ # Drips Application Draft -This is a factual draft for review before any application is submitted. It does not guarantee acceptance, points, funding, or payout. Claims below distinguish the current open PR branch from features already merged to `main`. +This is a factual draft for a Drips Wave application or appeal. It does not +guarantee acceptance, points, funding, or payout. Every claim below is true of +`main` at commit `aec759c` (2026-10-28) unless marked as a limitation. ## Project description -StellarFoundry DevKit is a Rust developer toolkit for Stellar and Soroban. Its current implementation provides bounded decoding of `ScVal`, `TransactionEnvelope`, and `ContractEvent` XDR; Stellar strkey classification; RPC endpoint validation; a typed RPC protocol layer with deterministic mock transport; and a CLI named `stellar-foundry`. +StellarFoundry DevKit is a Rust developer toolkit for Stellar and Soroban. It +provides bounded decoding of `ScVal`, `TransactionEnvelope`, and +`ContractEvent` XDR; Stellar strkey classification; RPC endpoint validation; a +typed RPC protocol layer with deterministic mocks and a bounded HTTP transport; +non-executing WASM inspection; deterministic structural findings with SARIF 2.1.0 +output; strict TOML configuration; and a CLI named `stellar-foundry`. -The implementation branch also adds bounded HTTP JSON-RPC transport, non-executing WASM inspection, bounded decoding of contractspecv0 XDR entries, deterministic structural findings, SARIF 2.1.0 serialization and a manual code-scanning upload workflow, strict TOML configuration wired into `rpc-health`, and release/readiness workflows. These changes are still under review until PR #133 merges. +The implementation is merged into `main`. There is no tagged release or crates.io +publication yet. ## Problem and ecosystem relevance -Stellar developers often need to inspect XDR values, contract artifacts, events, and RPC behavior during development and testing. DevKit centralizes several of these workflows behind reusable Rust APIs and a CLI, with an emphasis on bounded handling of untrusted inputs, deterministic tests, and structured output. +Stellar developers often need to inspect XDR values, contract artifacts, events, +and RPC behavior during development and testing. DevKit centralizes several of +these workflows behind reusable Rust APIs and a CLI, with an emphasis on bounded +handling of untrusted inputs, deterministic tests, and structured output. -The project composes with ecosystem crates such as `stellar-xdr` and `stellar-strkey`. It is intended to complement official Stellar tooling, not replace the official CLI or RPC client. +The project composes with ecosystem crates such as `stellar-xdr` and +`stellar-strkey`. It complements official Stellar tooling and does not replace +the official CLI or RPC client. It is a developer workflow and inspection layer, +not a source-level vulnerability scanner; see +[WHY_DEVKIT.md](WHY_DEVKIT.md) for the boundary with +`soroban-security-scanner`. ## Current implementation and evidence - Repository: [StellarFoundry/stellar-devkit](https://github.com/StellarFoundry/stellar-devkit) -- Combined implementation and hardening PR: [PR #133](https://github.com/StellarFoundry/stellar-devkit/pull/133) -- Security/CI hardening PR: [PR #127](https://github.com/StellarFoundry/stellar-devkit/pull/127) -- Latest combined CI run: [CI run #40679489331](https://github.com/StellarFoundry/stellar-devkit/actions/runs/40679489331) - -The combined CI run passed formatting, Clippy, Linux, Windows, macOS, and Rust 1.91.0 MSRV tests: [CI run #40680053061](https://github.com/StellarFoundry/stellar-devkit/actions/runs/40680053061). The regenerated lockfile includes the new transport and WASM-parser dependencies, and the RustSec audit passed: [audit run #40680053077](https://github.com/StellarFoundry/stellar-devkit/actions/runs/40680053077). - -## Current limitations - -- `contractspecv0` entries are decoded with the official Stellar XDR types into XDR-JSON definitions, variant names, and best-effort names; a normalized ABI schema remains future work. -- Security-analysis rules are structural heuristics, not a comprehensive vulnerability detector. -- SARIF can be uploaded using the manual workflow when a repository-relative WASM artifact exists and code-scanning permissions are available. -- RPC configuration is wired into `rpc-health`; other commands do not consume RPC settings. -- The implementation PRs remain open. Do not state that all proposed features are already available on `main`. +- Merge commit: `aec759c` (2026-10-28) +- Security/CI hardening PR: [PR #127](https://github.com/StellarFoundry/stellar-devkit/pull/127) — merged +- Implementation PR: [PR #133](https://github.com/StellarFoundry/stellar-devkit/pull/133) — merged +- Post-merge CI on `main`: [CI run 40690141880](https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141880) +- Post-merge RustSec audit: [audit run 40690141721](https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141721) + +The post-merge CI run passed formatting, Clippy, Linux, Windows, macOS, and Rust +1.91.0 MSRV tests. The RustSec audit passed against the committed lockfile. + +Merged capabilities: + +- Bounded XDR decoding with structured errors and a malformed-input corpus. +- RPC endpoint validation, typed protocol models, deterministic mock transport, + retry policy, timeout, and bounded HTTP transport. +- Non-executing WASM inspection and bounded `contractspecv0` decoding. +- Deterministic structural findings and SARIF 2.1.0 serialization. +- Strict TOML configuration and secret-safe diagnostics wired into `rpc-health`. +- CLI commands `inspect-wasm`, `analyze-wasm`, and `rpc-health`. +- Pinned CI, locked dependencies, MSRV job, RustSec audit, fuzz targets, and + release-validation workflow. + +## What changed since the previous review + +Use this section for an appeal. Replace the bracketed text with the rejection +reason and confirm dates in the Drips dashboard. + +| Review concern | Change since review | Evidence | +| -------------- | ------------------- | -------- | +| [Fill in the stated reason] | PR #127 and PR #133 are merged; the implementation is on `main`, not an open branch | Merge `aec759c`; CI 40690141880; audit 40690141721 | +| Documentation did not match the code | Status, readiness, audit, changelog, roadmap, architecture, and getting-started docs now describe merged work accurately | `docs/PROJECT_STATUS.md`, `docs/DRIPS_READINESS.md`, `CHANGELOG.md`, `docs/ARCHITECTURE.md` | +| Backlog advertised completed work | Issue audit, backlog, and Wave board regenerated from live GitHub issues; completed items removed from the board | `docs/WAVE_BOARD.md`, `docs/ISSUE_BACKLOG.md` | +| Possible overlap with another org repo | Scope boundary documented: DevKit is XDR/RPC/transaction inspection; `soroban-security-scanner` is source-level detection | `docs/WHY_DEVKIT.md` | +| [Any other stated reason] | [Describe the specific change] | [Link] | ## Contributor opportunities -The issue backlog documents potential work across RPC, XDR/SCVal, contract inspection, testing, security, CLI, configuration, SARIF, performance, observability, release engineering, and documentation. Backlog issues are proposed work, not completed functionality. Check current issue states and assignment requirements before describing specific issues as available. +The backlog contains 112 open issues: 82 Drips-ready, 24 blocked by dependencies, +3 needing revision, and 3 deferred. Five of the 82 are implemented or partially +implemented on `main` and are excluded from the board pending closure or re-scope +(#1, #7, #20, #25, #33). [WAVE_BOARD.md](WAVE_BOARD.md) curates 20 independent, +Wave-sized issues (3 trivial, 13 medium, 4 high; 3,050 points). +Backlog issues are proposed work, not completed functionality. Check current +issue states and assignment requirements before describing specific issues as +available. + +## Current limitations -See [ISSUE_BACKLOG.md](ISSUE_BACKLOG.md), [DRIPS_ISSUE_AUDIT.md](DRIPS_ISSUE_AUDIT.md), and [DRIPS_READINESS.md](DRIPS_READINESS.md). +- `contractspecv0` entries are decoded with the official Stellar XDR types into + XDR-JSON definitions, variant names, and best-effort names; a normalized ABI + schema remains future work. +- Security-analysis rules are structural heuristics, not a comprehensive + vulnerability detector. +- SARIF can be uploaded using the manual workflow when a repository-relative WASM + artifact exists and code-scanning permissions are available. +- RPC configuration is wired into `rpc-health`; other commands do not consume + RPC settings. +- No tagged release, release binaries, or crates.io publication exists yet. +- External adoption is limited; no external contributor has merged a PR yet. ## Supporting documentation +- [Why DevKit](WHY_DEVKIT.md) - [Architecture](ARCHITECTURE.md) - [Ecosystem research](ECOSYSTEM_RESEARCH.md) - [Project status](PROJECT_STATUS.md) +- [Implemented capabilities](IMPLEMENTED_CAPABILITIES.md) - [Testing guide](TESTING.md) - [Release checklist](RELEASE_CHECKLIST.md) - [Contributing through Drips Wave](WAVE.md) +- [Appeal summary](APPEAL.md) ## Final verification before submission -- Confirm the latest combined CI remains green after final documentation updates. -- Confirm the RustSec audit passes against the committed lockfile. -- Verify the current Drips Wave program's application process, eligibility, required evidence, and deadlines with the program maintainers. -- Replace this draft only with verified facts from the final repository state; do not claim approval, funding, user traction, or contributor activity without evidence. +- [x] Post-merge CI is green on `main`. +- [x] RustSec audit passes against the committed lockfile. +- [ ] Confirm the repository's current application status in the Drips dashboard. +- [ ] Confirm the appeal window and submit through the dashboard only. +- [ ] Replace bracketed text with the actual rejection reason and dates. +- [ ] Do not claim approval, funding, user traction, or contributor activity + without evidence. -No application has been submitted by this draft. +No application or appeal has been submitted by this draft. diff --git a/docs/DRIPS_ISSUE_AUDIT.md b/docs/DRIPS_ISSUE_AUDIT.md index 70ecaf4..c40584e 100644 --- a/docs/DRIPS_ISSUE_AUDIT.md +++ b/docs/DRIPS_ISSUE_AUDIT.md @@ -3,10 +3,10 @@ Generated from `tools/backlog/issues_*.json`. The GitHub issue numbers are assigned on creation; titles are the stable identifier. -- **Total issues:** 119 +- **Total issues:** 112 - **Trivial:** 7 -- **Medium:** 84 -- **High:** 28 +- **Medium:** 78 +- **High:** 27 Complexity is assigned from the scope of each individual issue, not from an aggregate reward target. Drips determines applicable points and budgets @@ -14,125 +14,118 @@ through its own system. | # | Title | Area | Complexity | Dependencies | Acceptance | Tests | Security | | - | ----- | ---- | ---------- | ------------ | ---------- | ----- | -------- | -| 1 | ci(deps): configure automated dependency updates | release | trivial | None. | yes | yes | yes | -| 2 | feat(cli): add shell completion generation | cli | trivial | None. | yes | yes | yes | -| 3 | feat(cli): add verbosity control | cli | trivial | Structured logging issue. | yes | yes | yes | -| 4 | feat(ledger): add ledger sequence and close-time helpers | rpc | trivial | None. | yes | yes | yes | -| 5 | feat(rpc): add a typed model for getFeeStats | rpc | trivial | None. | yes | yes | yes | -| 6 | test(cli): assert the exit-code contract | cli | trivial | None. | yes | yes | yes | -| 7 | test(core): add deterministic snapshot tests for core types | core | trivial | Error taxonomy issue. | yes | yes | yes | -| 8 | chore(ci): add triage automation for issues and pull requests | github | medium | None. | yes | yes | yes | -| 9 | ci(msrv): pin and test a minimum supported Rust version | release | medium | None. | yes | yes | yes | -| 10 | ci(release): add compatibility testing across toolchains | release | medium | MSRV pin. | yes | yes | yes | -| 11 | ci(release): automate changelog generation | release | medium | Versioning policy issue. | yes | yes | yes | -| 12 | docs(release): define the versioning and compatibility policy | release | medium | None. | yes | yes | yes | -| 13 | docs: add a configuration reference | config | medium | Configuration system issue. | yes | yes | yes | -| 14 | docs: add a contract inspection guide | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | -| 15 | docs: add a security rule authoring guide | security | medium | Rule engine issue. | yes | yes | yes | -| 16 | docs: add an RPC guide | rpc | medium | None. | yes | yes | yes | -| 17 | docs: add an XDR and SCVal guide | xdr | medium | None. | yes | yes | yes | -| 18 | feat(ci): add a release validation workflow | release | medium | Release binaries issue. | yes | yes | yes | -| 19 | feat(ci): add a reusable workflow for consumers | github | medium | Composite Action issue. | yes | yes | yes | -| 20 | feat(ci): add dependency and license auditing | security | medium | None. | yes | yes | yes | -| 21 | feat(cli): add a JSON error output mode | cli | medium | Error taxonomy issue. | yes | yes | yes | -| 22 | feat(cli): add batch decoding from files and directories | cli | medium | None. | yes | yes | yes | -| 23 | feat(cli): add config init, show, and validate subcommands | cli | medium | Configuration system issue. | yes | yes | yes | -| 24 | feat(cli): add live RPC diagnostics to doctor | rpc | medium | Live transport issue. | yes | yes | yes | -| 25 | feat(cli): add stdin input for decode commands | cli | medium | None. | yes | yes | yes | -| 26 | feat(cli): improve error presentation with suggestions | cli | medium | Secret redaction issue. | yes | yes | yes | -| 27 | feat(cli): unify global flags across commands | cli | medium | None. | yes | yes | yes | -| 28 | feat(config): resolve network profiles and custom endpoints | rpc | medium | Configuration system issue. | yes | yes | yes | -| 29 | feat(contracts): add the contract inspection CLI command | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | -| 30 | feat(contracts): cache extracted contract specs | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | -| 31 | feat(contracts): discover and validate WASM containers | contract-inspection | medium | None. | yes | yes | yes | -| 32 | feat(contracts): handle and validate contract IDs | contract-inspection | medium | None. | yes | yes | yes | -| 33 | feat(contracts): report contract environment and protocol compatibility | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | -| 34 | feat(contracts): represent contract invocations | transactions | medium | SCVal rendering issue. | yes | yes | yes | -| 35 | feat(core): add a configuration system with file and environment support | core | medium | None. | yes | yes | yes | -| 36 | feat(core): add a versioned output envelope for machine-readable commands | core | medium | None. | yes | yes | yes | -| 37 | feat(core): add an optional decode cache | core | medium | None. | yes | yes | yes | -| 38 | feat(core): add shared Severity and Confidence models | core | medium | None. | yes | yes | yes | -| 39 | feat(core): add structured logging with levels | core | medium | None. | yes | yes | yes | -| 40 | feat(core): define a categorized error taxonomy | core | medium | None. | yes | yes | yes | -| 41 | feat(events): add event filtering by contract and topics | rpc | medium | Typed getEvents model issue. | yes | yes | yes | -| 42 | feat(events): correlate events with their transaction | events | medium | Event normalization issue. | yes | yes | yes | -| 43 | feat(events): decode diagnostic events distinctly | events | medium | Diagnostic events XDR issue. | yes | yes | yes | -| 44 | feat(events): normalize events into a stable structure | events | medium | Typed getEvents model issue. | yes | yes | yes | -| 45 | feat(github): add a SARIF upload workflow | github | medium | SARIF emission issue. | yes | yes | yes | -| 46 | feat(github): add changed-file pull-request analysis workflow | github | medium | Action issue. | yes | yes | yes | -| 47 | feat(rpc): add a typed JSON-RPC error taxonomy | rpc | medium | Typed JSON-RPC request issue. | yes | yes | yes | -| 48 | feat(rpc): add a typed model for getLedgerEntries | rpc | medium | Fixture loader issue. | yes | yes | yes | -| 49 | feat(rpc): add connection reuse and pool configuration | rpc | medium | Live transport issue. | yes | yes | yes | -| 50 | feat(rpc): add cursor-based pagination for list methods | rpc | medium | Request construction issue. | yes | yes | yes | -| 51 | feat(rpc): add exponential backoff with jitter to retries | rpc | medium | None. | yes | yes | yes | -| 52 | feat(rpc): add timeouts and cancellation to RPC calls | rpc | medium | None. | yes | yes | yes | -| 53 | feat(rpc): add typed models for getTransaction and getTransactions | rpc | medium | Fixture loader issue. | yes | yes | yes | -| 54 | feat(rpc): distinguish Horizon and RPC data sources | rpc | medium | None. | yes | yes | yes | -| 55 | feat(rpc): handle rate limiting and Retry-After | rpc | medium | Typed JSON-RPC error taxonomy. | yes | yes | yes | -| 56 | feat(rpc): implement JSON-RPC request construction | rpc | medium | Error taxonomy issue. | yes | yes | yes | -| 57 | feat(scval): decode and render addresses and contract IDs | scval | medium | None. | yes | yes | yes | -| 58 | feat(scval): fully decode and render maps and vectors | scval | medium | Curated SCVal rendering issue. | yes | yes | yes | -| 59 | feat(security): add a SARIF rule catalog with stable identifiers | sarif | medium | Findings model issue. | yes | yes | yes | -| 60 | feat(security): add a findings model with evidence | security | medium | Severity/Confidence models. | yes | yes | yes | -| 61 | feat(security): add finding suppression with documented reasons | security | medium | Findings model issue. | yes | yes | yes | -| 62 | feat(security): make XDR decode limits configurable and strict | xdr | medium | None. | yes | yes | yes | -| 63 | feat(security): redact secrets in logs and output | security | medium | None. | yes | yes | yes | -| 64 | feat(security): validate contract metadata for consistency | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | -| 65 | feat(testing): add mock RPC network scenarios | rpc | medium | Fixture loader issue. | yes | yes | yes | -| 66 | feat(transactions): add an envelope summary command | transactions | medium | None. | yes | yes | yes | -| 67 | feat(transactions): analyze fees (base, resource, and total) | transactions | medium | Soroban transaction data issue. | yes | yes | yes | -| 68 | feat(transactions): extract source account and sequence number | transactions | medium | Envelope summary issue. | yes | yes | yes | -| 69 | feat(transactions): handle memo and time/ledger bounds | transactions | medium | None. | yes | yes | yes | -| 70 | feat(transactions): inspect signatures and signer hints | transactions | medium | None. | yes | yes | yes | -| 71 | feat(xdr): distinguish envelope v0 and v1 variants | xdr | medium | None. | yes | yes | yes | -| 72 | feat(xdr): inspect TransactionResult and TransactionMeta | xdr | medium | None. | yes | yes | yes | -| 73 | feat(xdr): pretty-print ledger entries | xdr | medium | getLedgerEntries model issue. | yes | yes | yes | -| 74 | feat(xdr): validate bytes, symbol, and string lengths | xdr | medium | None. | yes | yes | yes | -| 75 | perf(observability): benchmark decode throughput | observability | medium | None. | yes | yes | yes | -| 76 | perf(rpc): measure and document RPC call overhead | rpc | medium | Local integration test server issue. | yes | yes | yes | -| 77 | perf(xdr): optimize SCVal decoding for large maps | scval | medium | SCVal collections issue. | yes | yes | yes | -| 78 | perf: add performance regression tests to CI | performance | medium | Decode and RPC benchmarks. | yes | yes | yes | -| 79 | perf: measure memory usage on large inputs | performance | medium | None. | yes | yes | yes | -| 80 | refactor(core): add validation primitives for untrusted strings | core | medium | None. | yes | yes | yes | -| 81 | test(ci): add a scheduled fuzz smoke job | security | medium | Fuzz targets. | yes | yes | yes | -| 82 | test(events): add event fixture generation tooling | events | medium | Encode helpers issue. | yes | yes | yes | -| 83 | test(rpc): add snapshot tests for RPC response models | rpc | medium | None. | yes | yes | yes | -| 84 | test(security): add false-negative regression tests | testing | medium | Rule engine issue. | yes | yes | yes | -| 85 | test(security): add false-positive regression tests | testing | medium | Rule engine issue. | yes | yes | yes | -| 86 | test(security): fuzz RPC response parsing | rpc | medium | Untrusted RPC response hardening issue. | yes | yes | yes | -| 87 | test(xdr): add a malformed XDR corpus | xdr | medium | None. | yes | yes | yes | -| 88 | test(xdr): add golden fixtures for XDR decoding | xdr | medium | None. | yes | yes | yes | -| 89 | test(xdr): add property-based round-trip tests | xdr | medium | Encode helpers issue. | yes | yes | yes | -| 90 | test: add a regression corpus runner | testing | medium | Fixture loader issue. | yes | yes | yes | -| 91 | test: add cross-platform and endianness tests | testing | medium | None. | yes | yes | yes | -| 92 | ci(release): build and attach cross-platform release binaries | release | high | None. | yes | yes | yes | -| 93 | ci(release): generate an SBOM and artifact attestations | security | high | Release binaries issue. | yes | yes | yes | -| 94 | feat(contracts): inspect WASM contract specs via soroban-spec | contract-inspection | high | None. | yes | yes | yes | -| 95 | feat(contracts): inspect contract instance storage | contract-inspection | high | Ledger entry pretty-printing issue. | yes | yes | yes | -| 96 | feat(contracts): inspect persistent and temporary storage entries | contract-inspection | high | Ledger entry pretty-printing issue. | yes | yes | yes | -| 97 | feat(contracts): map contract events to spec types | events | high | WASM spec extraction issue and event normalization issue. | yes | yes | yes | -| 98 | feat(events): add a typed getEvents model with pagination | rpc | high | Fixture loader issue. | yes | yes | yes | -| 99 | feat(github): add a composite Action to run DevKit checks | github | high | None. | yes | yes | yes | -| 100 | feat(github): add baseline scanning support | security | high | Findings model issue. | yes | yes | yes | -| 101 | feat(release): prepare crates.io packaging | release | high | MSRV pin. | yes | yes | yes | -| 102 | feat(rpc): implement a live HTTP transport over the official client | rpc | high | None. | yes | yes | yes | -| 103 | feat(sarif): emit SARIF for security findings | security | high | Security analysis issue. | yes | yes | yes | -| 104 | feat(scval): add curated human-readable rendering for common SCVal types | xdr | high | None. | yes | yes | yes | -| 105 | feat(scval): add type-safe conversions between SCVal and Rust primitives | scval | high | None. | yes | yes | yes | -| 106 | feat(security): add WASM safety checks | contract-inspection | high | WASM container validation issue. | yes | yes | yes | -| 107 | feat(security): add a security fixture corpus | testing | high | Rule engine issue. | yes | yes | yes | -| 108 | feat(security): design and implement the rule engine architecture | security | high | Severity/Confidence models. | yes | yes | yes | -| 109 | feat(security): harden against untrusted RPC responses | rpc | high | Live transport issue. | yes | yes | yes | -| 110 | feat(security): harden the HTTP transport against SSRF and unsafe redirects | rpc | high | Live transport issue. | yes | yes | yes | -| 111 | feat(testing): add a fixture loader and schema | testing | high | None. | yes | yes | yes | -| 112 | feat(transactions): inspect Soroban transaction data and footprint | scval | high | Ledger entry pretty-printing issue. | yes | yes | yes | -| 113 | feat(transactions): inspect operations with type-specific detail | transactions | high | None. | yes | yes | yes | -| 114 | feat(transactions): interpret transaction results and failure codes | transactions | high | Transaction result decoding issue. | yes | yes | yes | -| 115 | feat(xdr): add strict encode helpers from JSON to XDR | xdr | high | Versioned schema issue. | yes | yes | yes | -| 116 | feat(xdr): define a versioned JSON schema for decoded values | xdr | high | None. | yes | yes | yes | -| 117 | test(contracts): add fixture WASM contracts | contract-inspection | high | WASM spec extraction issue. | yes | yes | yes | -| 118 | test(rpc): add a local integration test server | rpc | high | Live transport issue. | yes | yes | yes | -| 119 | test(security): add a fuzz target for XDR and SCVal decoding | security | high | None. | yes | yes | yes | +| #31 | ci(deps): configure automated dependency updates | release | trivial | None. | yes | yes | yes | +| #30 | feat(cli): add shell completion generation | cli | trivial | None. | yes | yes | yes | +| #98 | feat(cli): add verbosity control | cli | trivial | Structured logging issue. | yes | yes | yes | +| #76 | feat(ledger): add ledger sequence and close-time helpers | rpc | trivial | None. | yes | yes | yes | +| #6 | feat(rpc): add a typed model for getFeeStats | rpc | trivial | None. | yes | yes | yes | +| #33 | test(cli): assert the exit-code contract | cli | trivial | None. | yes | yes | yes | +| #40 | test(core): add deterministic snapshot tests for core types | core | trivial | Error taxonomy issue. | yes | yes | yes | +| #105 | chore(ci): add triage automation for issues and pull requests | github | medium | None. | yes | yes | yes | +| #34 | ci(msrv): pin and test a minimum supported Rust version | release | medium | None. | yes | yes | yes | +| #116 | ci(release): add compatibility testing across toolchains | release | medium | MSRV pin. | yes | yes | yes | +| #112 | docs(release): define the versioning and compatibility policy | release | medium | None. | yes | yes | yes | +| #121 | docs: add a configuration reference | config | medium | Configuration system issue. | yes | yes | yes | +| #119 | docs: add a contract inspection guide | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | +| #120 | docs: add a security rule authoring guide | security | medium | Rule engine issue. | yes | yes | yes | +| #117 | docs: add an RPC guide | rpc | medium | None. | yes | yes | yes | +| #118 | docs: add an XDR and SCVal guide | xdr | medium | None. | yes | yes | yes | +| #104 | feat(ci): add a release validation workflow | release | medium | Release binaries issue. | yes | yes | yes | +| #101 | feat(ci): add a reusable workflow for consumers | github | medium | Composite Action issue. | yes | yes | yes | +| #106 | feat(ci): add dependency and license auditing | security | medium | None. | yes | yes | yes | +| #15 | feat(cli): add batch decoding from files and directories | cli | medium | None. | yes | yes | yes | +| #32 | feat(cli): add config init, show, and validate subcommands | cli | medium | Configuration system issue. | yes | yes | yes | +| #9 | feat(cli): add live RPC diagnostics to doctor | rpc | medium | Live transport issue. | yes | yes | yes | +| #97 | feat(cli): improve error presentation with suggestions | cli | medium | Secret redaction issue. | yes | yes | yes | +| #96 | feat(cli): unify global flags across commands | cli | medium | None. | yes | yes | yes | +| #8 | feat(config): resolve network profiles and custom endpoints | rpc | medium | Configuration system issue. | yes | yes | yes | +| #71 | feat(contracts): add the contract inspection CLI command | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | +| #65 | feat(contracts): cache extracted contract specs | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | +| #64 | feat(contracts): discover and validate WASM containers | contract-inspection | medium | None. | yes | yes | yes | +| #63 | feat(contracts): handle and validate contract IDs | contract-inspection | medium | None. | yes | yes | yes | +| #70 | feat(contracts): report contract environment and protocol compatibility | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | +| #66 | feat(contracts): represent contract invocations | transactions | medium | SCVal rendering issue. | yes | yes | yes | +| #7 | feat(core): add a configuration system with file and environment support | core | medium | None. | yes | yes | yes | +| #38 | feat(core): add a versioned output envelope for machine-readable commands | core | medium | None. | yes | yes | yes | +| #110 | feat(core): add an optional decode cache | core | medium | None. | yes | yes | yes | +| #37 | feat(core): add shared Severity and Confidence models | core | medium | None. | yes | yes | yes | +| #10 | feat(core): add structured logging with levels | core | medium | None. | yes | yes | yes | +| #36 | feat(core): define a categorized error taxonomy | core | medium | None. | yes | yes | yes | +| #72 | feat(events): add event filtering by contract and topics | rpc | medium | Typed getEvents model issue. | yes | yes | yes | +| #75 | feat(events): correlate events with their transaction | events | medium | Event normalization issue. | yes | yes | yes | +| #73 | feat(events): decode diagnostic events distinctly | events | medium | Diagnostic events XDR issue. | yes | yes | yes | +| #74 | feat(events): normalize events into a stable structure | events | medium | Typed getEvents model issue. | yes | yes | yes | +| #102 | feat(github): add a SARIF upload workflow | github | medium | SARIF emission issue. | yes | yes | yes | +| #35 | feat(github): add changed-file pull-request analysis workflow | github | medium | Action issue. | yes | yes | yes | +| #44 | feat(rpc): add a typed JSON-RPC error taxonomy | rpc | medium | Typed JSON-RPC request issue. | yes | yes | yes | +| #4 | feat(rpc): add a typed model for getLedgerEntries | rpc | medium | Fixture loader issue. | yes | yes | yes | +| #46 | feat(rpc): add connection reuse and pool configuration | rpc | medium | Live transport issue. | yes | yes | yes | +| #43 | feat(rpc): add cursor-based pagination for list methods | rpc | medium | Request construction issue. | yes | yes | yes | +| #3 | feat(rpc): add exponential backoff with jitter to retries | rpc | medium | None. | yes | yes | yes | +| #2 | feat(rpc): add timeouts and cancellation to RPC calls | rpc | medium | None. | yes | yes | yes | +| #5 | feat(rpc): add typed models for getTransaction and getTransactions | rpc | medium | Fixture loader issue. | yes | yes | yes | +| #42 | feat(rpc): distinguish Horizon and RPC data sources | rpc | medium | None. | yes | yes | yes | +| #45 | feat(rpc): handle rate limiting and Retry-After | rpc | medium | Typed JSON-RPC error taxonomy. | yes | yes | yes | +| #41 | feat(rpc): implement JSON-RPC request construction | rpc | medium | Error taxonomy issue. | yes | yes | yes | +| #49 | feat(scval): decode and render addresses and contract IDs | scval | medium | None. | yes | yes | yes | +| #48 | feat(scval): fully decode and render maps and vectors | scval | medium | Curated SCVal rendering issue. | yes | yes | yes | +| #87 | feat(security): add a SARIF rule catalog with stable identifiers | sarif | medium | Findings model issue. | yes | yes | yes | +| #79 | feat(security): add a findings model with evidence | security | medium | Severity/Confidence models. | yes | yes | yes | +| #80 | feat(security): add finding suppression with documented reasons | security | medium | Findings model issue. | yes | yes | yes | +| #13 | feat(security): make XDR decode limits configurable and strict | xdr | medium | None. | yes | yes | yes | +| #22 | feat(security): redact secrets in logs and output | security | medium | None. | yes | yes | yes | +| #84 | feat(security): validate contract metadata for consistency | contract-inspection | medium | WASM spec extraction issue. | yes | yes | yes | +| #18 | feat(testing): add mock RPC network scenarios | rpc | medium | Fixture loader issue. | yes | yes | yes | +| #26 | feat(transactions): add an envelope summary command | transactions | medium | None. | yes | yes | yes | +| #58 | feat(transactions): analyze fees (base, resource, and total) | transactions | medium | Soroban transaction data issue. | yes | yes | yes | +| #56 | feat(transactions): extract source account and sequence number | transactions | medium | Envelope summary issue. | yes | yes | yes | +| #60 | feat(transactions): handle memo and time/ledger bounds | transactions | medium | None. | yes | yes | yes | +| #59 | feat(transactions): inspect signatures and signer hints | transactions | medium | None. | yes | yes | yes | +| #54 | feat(xdr): distinguish envelope v0 and v1 variants | xdr | medium | None. | yes | yes | yes | +| #50 | feat(xdr): inspect TransactionResult and TransactionMeta | xdr | medium | None. | yes | yes | yes | +| #52 | feat(xdr): pretty-print ledger entries | xdr | medium | getLedgerEntries model issue. | yes | yes | yes | +| #55 | feat(xdr): validate bytes, symbol, and string lengths | xdr | medium | None. | yes | yes | yes | +| #28 | perf(observability): benchmark decode throughput | observability | medium | None. | yes | yes | yes | +| #107 | perf(rpc): measure and document RPC call overhead | rpc | medium | Local integration test server issue. | yes | yes | yes | +| #108 | perf(xdr): optimize SCVal decoding for large maps | scval | medium | SCVal collections issue. | yes | yes | yes | +| #111 | perf: add performance regression tests to CI | performance | medium | Decode and RPC benchmarks. | yes | yes | yes | +| #39 | refactor(core): add validation primitives for untrusted strings | core | medium | None. | yes | yes | yes | +| #77 | test(events): add event fixture generation tooling | events | medium | Encode helpers issue. | yes | yes | yes | +| #90 | test(rpc): add snapshot tests for RPC response models | rpc | medium | None. | yes | yes | yes | +| #83 | test(security): add false-negative regression tests | testing | medium | Rule engine issue. | yes | yes | yes | +| #82 | test(security): add false-positive regression tests | testing | medium | Rule engine issue. | yes | yes | yes | +| #88 | test(security): fuzz RPC response parsing | rpc | medium | Untrusted RPC response hardening issue. | yes | yes | yes | +| #16 | test(xdr): add golden fixtures for XDR decoding | xdr | medium | None. | yes | yes | yes | +| #19 | test(xdr): add property-based round-trip tests | xdr | medium | Encode helpers issue. | yes | yes | yes | +| #92 | test: add a regression corpus runner | testing | medium | Fixture loader issue. | yes | yes | yes | +| #91 | test: add cross-platform and endianness tests | testing | medium | None. | yes | yes | yes | +| #29 | ci(release): build and attach cross-platform release binaries | release | high | None. | yes | yes | yes | +| #115 | ci(release): generate an SBOM and artifact attestations | security | high | Release binaries issue. | yes | yes | yes | +| #25 | feat(contracts): inspect WASM contract specs via soroban-spec | contract-inspection | high | None. | yes | yes | yes | +| #67 | feat(contracts): inspect contract instance storage | contract-inspection | high | Ledger entry pretty-printing issue. | yes | yes | yes | +| #68 | feat(contracts): inspect persistent and temporary storage entries | contract-inspection | high | Ledger entry pretty-printing issue. | yes | yes | yes | +| #69 | feat(contracts): map contract events to spec types | events | high | WASM spec extraction issue and event normalization issue. | yes | yes | yes | +| #27 | feat(events): add a typed getEvents model with pagination | rpc | high | Fixture loader issue. | yes | yes | yes | +| #24 | feat(github): add a composite Action to run DevKit checks | github | high | None. | yes | yes | yes | +| #103 | feat(github): add baseline scanning support | security | high | Findings model issue. | yes | yes | yes | +| #114 | feat(release): prepare crates.io packaging | release | high | MSRV pin. | yes | yes | yes | +| #1 | feat(rpc): implement a live HTTP transport over the official client | rpc | high | None. | yes | yes | yes | +| #23 | feat(sarif): emit SARIF for security findings | security | high | Security analysis issue. | yes | yes | yes | +| #11 | feat(scval): add curated human-readable rendering for common SCVal types | xdr | high | None. | yes | yes | yes | +| #53 | feat(scval): add type-safe conversions between SCVal and Rust primitives | scval | high | None. | yes | yes | yes | +| #85 | feat(security): add WASM safety checks | contract-inspection | high | WASM container validation issue. | yes | yes | yes | +| #81 | feat(security): add a security fixture corpus | testing | high | Rule engine issue. | yes | yes | yes | +| #78 | feat(security): design and implement the rule engine architecture | security | high | Severity/Confidence models. | yes | yes | yes | +| #21 | feat(security): harden the HTTP transport against SSRF and unsafe redirects | rpc | high | Live transport issue. | yes | yes | yes | +| #17 | feat(testing): add a fixture loader and schema | testing | high | None. | yes | yes | yes | +| #61 | feat(transactions): inspect Soroban transaction data and footprint | scval | high | Ledger entry pretty-printing issue. | yes | yes | yes | +| #57 | feat(transactions): inspect operations with type-specific detail | transactions | high | None. | yes | yes | yes | +| #62 | feat(transactions): interpret transaction results and failure codes | transactions | high | Transaction result decoding issue. | yes | yes | yes | +| #14 | feat(xdr): add strict encode helpers from JSON to XDR | xdr | high | Versioned schema issue. | yes | yes | yes | +| #12 | feat(xdr): define a versioned JSON schema for decoded values | xdr | high | None. | yes | yes | yes | +| #93 | test(contracts): add fixture WASM contracts | contract-inspection | high | WASM spec extraction issue. | yes | yes | yes | +| #47 | test(rpc): add a local integration test server | rpc | high | Live transport issue. | yes | yes | yes | +| #20 | test(security): add a fuzz target for XDR and SCVal decoding | security | high | None. | yes | yes | yes | ## Notes diff --git a/docs/DRIPS_ISSUE_QUALITY_AUDIT.md b/docs/DRIPS_ISSUE_QUALITY_AUDIT.md index a78a369..8259d81 100644 --- a/docs/DRIPS_ISSUE_QUALITY_AUDIT.md +++ b/docs/DRIPS_ISSUE_QUALITY_AUDIT.md @@ -1,8 +1,8 @@ # Drips Issue Quality Audit -- **Audit date:** 2026-09-22 -- **Repository commit audited:** 07bef9e -- **Issues classified:** 121 (1 duplicate and 1 merge closed during remediation; 119 open). +- **Audit date:** 2026-10-28 +- **Repository commit audited:** aec759c +- **Issues classified:** 112 open issues. Standard applied: Drips *Creating Meaningful Issues* and the Wave maintainer documentation. Classification is evidence-based; weak issues are flagged, not @@ -12,14 +12,18 @@ hidden. Nothing here claims Drips approval. | Classification | Count | |---|---:| -| Drips-ready | 89 | +| Drips-ready | 82 | | Needs revision | 3 | | Must split | 0 | -| Must merge | 1 | -| Remove | 1 | +| Must merge | 0 | +| Remove | 0 | | Defer | 3 | | Blocked | 24 | +> **Post-merge note (2026-10-28):** #1, #7, #20, #25, +> and #33 have merged or partial implementation on `main` and are excluded +> from `docs/WAVE_BOARD.md` pending maintainer closure or re-scope. + No issue required splitting: the largest issues are already scoped to a single capability, and the previously broad areas had already been decomposed. @@ -31,10 +35,10 @@ through its own system. | Complexity | Count | |---|---:| -| High | 28 | -| Medium | 86 | +| High | 27 | +| Medium | 78 | | Trivial | 7 | -| **Total** | **121** | +| **Total** | **112** | No complexity label was changed during this audit: no issue was found to be clearly underpriced or overpriced. Complexity was not inflated. @@ -97,7 +101,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #17 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -112,7 +116,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #17 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -157,7 +161,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #7 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -247,7 +251,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #12 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -307,7 +311,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #17 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -322,7 +326,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #14 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -442,7 +446,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #17 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -637,7 +641,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #36 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -652,7 +656,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #36 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -682,7 +686,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #41 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -697,7 +701,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #41 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -712,7 +716,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #44 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -757,7 +761,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #11 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -791,21 +795,6 @@ clearly underpriced or overpriced. Complexity was not inflated. - Duplication: PASS. - Final recommendation: Drips-ready. -### #51 — feat(xdr): inspect diagnostic events - -- Classification: **Remove (duplicate)** -- Complexity: medium -- Area: xdr -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: FAIL — remove (duplicate). -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. -- Dependencies: #50 -- Duplication: FAIL — duplicate. -- Final recommendation: Remove (duplicate). - ### #52 — feat(xdr): pretty-print ledger entries - Classification: **Drips-ready** @@ -817,7 +806,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #4 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -877,7 +866,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #26 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -907,7 +896,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #61 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -952,7 +941,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #52 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -967,7 +956,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #50 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1027,7 +1016,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #11 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1117,7 +1106,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #27 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1147,7 +1136,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #27 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1192,7 +1181,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #14 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1207,7 +1196,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #37 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1222,7 +1211,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #37 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1237,7 +1226,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #79 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1252,7 +1241,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #78 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1267,7 +1256,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #78 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1282,7 +1271,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #78 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1316,21 +1305,6 @@ clearly underpriced or overpriced. Complexity was not inflated. - Duplication: PASS. - Final recommendation: Blocked by dependency. -### #86 — feat(security): harden against untrusted RPC responses - -- Classification: **Drips-ready** -- Complexity: high -- Area: rpc -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: PASS — a single capability, Wave-sized. -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. -- Dependencies: #1 -- Duplication: PASS. -- Final recommendation: Drips-ready. - ### #87 — feat(security): add a SARIF rule catalog with stable identifiers - Classification: **Blocked by dependency** @@ -1357,21 +1331,6 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #86 -- Duplication: PASS. -- Final recommendation: Drips-ready. - -### #89 — test(xdr): add a malformed XDR corpus - -- Classification: **Drips-ready** -- Complexity: medium -- Area: xdr -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: PASS — a single capability, Wave-sized. -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. - Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1417,7 +1376,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #17 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1436,36 +1395,6 @@ clearly underpriced or overpriced. Complexity was not inflated. - Duplication: PASS. - Final recommendation: Blocked by dependency. -### #94 — test(ci): add a scheduled fuzz smoke job - -- Classification: **Drips-ready** -- Complexity: medium -- Area: security -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: PASS — a single capability, Wave-sized. -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. -- Dependencies: #20 -- Duplication: PASS. -- Final recommendation: Drips-ready. - -### #95 — feat(cli): add configuration profiles - -- Classification: **Merge** -- Complexity: medium -- Area: cli -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: FAIL — merge. -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. -- Dependencies: #7 -- Duplication: PASS. -- Final recommendation: Merge. - ### #96 — feat(cli): unify global flags across commands - Classification: **Drips-ready** @@ -1492,7 +1421,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #22 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1507,36 +1436,6 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #10 -- Duplication: PASS. -- Final recommendation: Drips-ready. - -### #99 — feat(cli): add a JSON error output mode - -- Classification: **Drips-ready** -- Complexity: medium -- Area: cli -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: PASS — a single capability, Wave-sized. -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. -- Dependencies: #36 -- Duplication: PASS. -- Final recommendation: Drips-ready. - -### #100 — feat(cli): add stdin input for decode commands - -- Classification: **Drips-ready** -- Complexity: medium -- Area: cli -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: PASS — a single capability, Wave-sized. -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. - Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1597,7 +1496,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #29 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1661,21 +1560,6 @@ clearly underpriced or overpriced. Complexity was not inflated. - Duplication: PASS. - Final recommendation: Blocked by dependency. -### #109 — perf: measure memory usage on large inputs - -- Classification: **Drips-ready** -- Complexity: medium -- Area: performance -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: PASS — a single capability, Wave-sized. -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. -- Dependencies: None. -- Duplication: PASS. -- Final recommendation: Drips-ready. - ### #110 — feat(core): add an optional decode cache - Classification: **Needs revision** @@ -1721,21 +1605,6 @@ clearly underpriced or overpriced. Complexity was not inflated. - Duplication: PASS. - Final recommendation: Drips-ready. -### #113 — ci(release): automate changelog generation - -- Classification: **Drips-ready** -- Complexity: medium -- Area: release -- Impact: PASS — maps to a real capability of the toolkit. -- Context: PASS — problem, why, current state, and scope sections present. -- Scope: PASS — a single capability, Wave-sized. -- Acceptance criteria: PASS — testable criteria present. -- Testing: PASS — tests requested. -- Security: N/A or addressed where relevant. -- Dependencies: #112 -- Duplication: PASS. -- Final recommendation: Drips-ready. - ### #114 — feat(release): prepare crates.io packaging - Classification: **Drips-ready** @@ -1747,7 +1616,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #34 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1762,7 +1631,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #29 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1777,7 +1646,7 @@ clearly underpriced or overpriced. Complexity was not inflated. - Acceptance criteria: PASS — testable criteria present. - Testing: PASS — tests requested. - Security: N/A or addressed where relevant. -- Dependencies: #34 +- Dependencies: None. - Duplication: PASS. - Final recommendation: Drips-ready. @@ -1925,25 +1794,18 @@ clearly underpriced or overpriced. Complexity was not inflated. | #81 | feat(security): add a security fixture corpus | high | testing | Depends only on implemented or independent work; testable. | | #82 | test(security): add false-positive regression tests | medium | testing | Depends only on implemented or independent work; testable. | | #83 | test(security): add false-negative regression tests | medium | testing | Depends only on implemented or independent work; testable. | -| #86 | feat(security): harden against untrusted RPC responses | high | rpc | Depends only on implemented or independent work; testable. | | #88 | test(security): fuzz RPC response parsing | medium | rpc | Depends only on implemented or independent work; testable. | -| #89 | test(xdr): add a malformed XDR corpus | medium | xdr | Depends only on implemented or independent work; testable. | | #90 | test(rpc): add snapshot tests for RPC response models | medium | rpc | Depends only on implemented or independent work; testable. | | #91 | test: add cross-platform and endianness tests | medium | testing | Depends only on implemented or independent work; testable. | | #92 | test: add a regression corpus runner | medium | testing | Depends only on implemented or independent work; testable. | -| #94 | test(ci): add a scheduled fuzz smoke job | medium | security | Depends only on implemented or independent work; testable. | | #96 | feat(cli): unify global flags across commands | medium | cli | Depends only on implemented or independent work; testable. | | #97 | feat(cli): improve error presentation with suggestions | medium | cli | Depends only on implemented or independent work; testable. | | #98 | feat(cli): add verbosity control | trivial | cli | Depends only on implemented or independent work; testable. | -| #99 | feat(cli): add a JSON error output mode | medium | cli | Depends only on implemented or independent work; testable. | -| #100 | feat(cli): add stdin input for decode commands | medium | cli | Depends only on implemented or independent work; testable. | | #104 | feat(ci): add a release validation workflow | medium | release | Depends only on implemented or independent work; testable. | | #105 | chore(ci): add triage automation for issues and pull requests | medium | github | Depends only on implemented or independent work; testable. | | #106 | feat(ci): add dependency and license auditing | medium | security | Depends only on implemented or independent work; testable. | -| #109 | perf: measure memory usage on large inputs | medium | performance | Depends only on implemented or independent work; testable. | | #111 | perf: add performance regression tests to CI | medium | ci | Depends only on implemented or independent work; testable. | | #112 | docs(release): define the versioning and compatibility policy | medium | release | Depends only on implemented or independent work; testable. | -| #113 | ci(release): automate changelog generation | medium | release | Depends only on implemented or independent work; testable. | | #114 | feat(release): prepare crates.io packaging | high | release | Depends only on implemented or independent work; testable. | | #115 | ci(release): generate an SBOM and artifact attestations | high | security | Depends only on implemented or independent work; testable. | | #116 | ci(release): add compatibility testing across toolchains | medium | release | Depends only on implemented or independent work; testable. | @@ -1962,7 +1824,6 @@ clearly underpriced or overpriced. Complexity was not inflated. | #42 | Defer / future work | Label status/deferred; revisit when the subsystem is planned. | | #46 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | | #47 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | -| #51 | Remove (duplicate) | Close as duplicate of #73; keep the canonical event issue. | | #55 | Needs revision | Revise the issue body before it can be Wave-ready. | | #65 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | | #67 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | @@ -1976,7 +1837,6 @@ clearly underpriced or overpriced. Complexity was not inflated. | #85 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | | #87 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | | #93 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | -| #95 | Merge | Close and fold into #8 (network profiles). | | #101 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | | #102 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | | #103 | Blocked by dependency | Label status/blocked; add to a Wave only after the dependency lands. | diff --git a/docs/DRIPS_READINESS.md b/docs/DRIPS_READINESS.md index 640e709..dba2fce 100644 --- a/docs/DRIPS_READINESS.md +++ b/docs/DRIPS_READINESS.md @@ -1,62 +1,137 @@ # Drips Readiness -This document records the repository's current state for a possible Drips Wave application. It does not guarantee approval, funding, payout, contributor activity, or points. +This document records the repository's current state for a possible Drips Wave +application or appeal. It does not guarantee approval, funding, payout, +contributor activity, or points. ## Project summary -StellarFoundry DevKit is a Rust developer toolkit for Stellar and Soroban. It provides bounded XDR decoding, endpoint validation, a typed RPC protocol layer, WASM metadata inspection, deterministic structural findings, SARIF serialization, configuration parsing, and a CLI. +StellarFoundry DevKit is a Rust developer toolkit for Stellar and Soroban. It +provides bounded XDR decoding, endpoint validation, a typed RPC protocol layer, +bounded HTTP transport, WASM metadata inspection, deterministic structural +findings, SARIF serialization, configuration parsing, and a CLI. ## Problem and ecosystem fit -Stellar developers routinely need to inspect XDR values, transactions, events, contract artifacts, and RPC behavior. DevKit aims to consolidate these workflows behind testable Rust APIs and command-line interfaces while composing with ecosystem crates such as `stellar-xdr` and `stellar-strkey`. - -The project complements official Stellar tooling; it should not claim to replace the official CLI or RPC client. - -## Implementation status on the current combined PR branch - -The combined branch for PR #133 includes the feature work and the security-hardening changes from PR #127. This combined work is still under review and has **not** been merged to `main`. - -- Bounded base64 decoding for `ScVal`, `TransactionEnvelope`, and `ContractEvent`, with structured errors and malformed-input regression fixtures. -- RPC endpoint policy validation and a typed RPC client with deterministic mock transport. -- HTTP JSON-RPC transport with timeout, redirects disabled, a response-size cap, response validation, and structured errors. -- Non-executing WASM validation, structural metadata, and bounded decoding of `contractspecv0` XDR entries into entry kind/name/definition records. -- Deterministic structural analysis findings with stable rule IDs and SARIF 2.1.0 serialization. -- Strict TOML configuration parsing, timeout validation, environment overrides, and static diagnostic events. -- CLI commands for WASM inspection, WASM analysis, and RPC health checks using optional TOML config, environment overrides, and a validated timeout. -- Pinned CI actions, locked dependency resolution, a dedicated Rust 1.91.0 MSRV job, RustSec dependency auditing, release-validation workflow, and release checklist. - -See [IMPLEMENTED_CAPABILITIES.md](IMPLEMENTED_CAPABILITIES.md), [PROJECT_STATUS.md](PROJECT_STATUS.md), [CHANGELOG.md](../CHANGELOG.md), and [PR #133](https://github.com/StellarFoundry/stellar-devkit/pull/133) for exact scope. - -## Known limitations (must be represented honestly) - -- Contract-spec entries are decoded into XDR-JSON definitions with a variant kind and best-effort name; a normalized, fully typed ABI schema is still future work. -- Analysis rules are structural heuristics, not a complete vulnerability detector and not proof of malicious intent. -- SARIF upload is available through a manual workflow dispatch and requires a WASM artifact in the repository plus code-scanning permissions. -- RPC config is wired into `rpc-health`; other commands do not use RPC settings. Endpoint precedence is command-line, then environment, then config file. -- No claim is made here that the project has published crates or release binaries, has a large user base, or is approved for a Wave. +Stellar developers routinely need to inspect XDR values, transactions, events, +contract artifacts, and RPC behavior. DevKit consolidates these workflows behind +testable Rust APIs and command-line interfaces while composing with ecosystem +crates such as `stellar-xdr` and `stellar-strkey`. + +The project complements official Stellar tooling. It does not replace the +official CLI or RPC client, and it is not a source-level vulnerability scanner. +See [WHY_DEVKIT.md](WHY_DEVKIT.md) for the boundary with +`soroban-security-scanner`. + +## Implementation status + +The implementation is **merged into `main`**. PR #127 (security/CI hardening) +and PR #133 (RPC transport, WASM inspection, analysis, and configuration) merged +on 2026-10-28; the merge commit is `aec759c`. + +Merged capabilities: + +- Bounded base64 decoding for `ScVal`, `TransactionEnvelope`, and + `ContractEvent`, with structured errors and malformed-input regression + fixtures. +- RPC endpoint policy validation and a typed RPC client with deterministic mock + transport. +- HTTP JSON-RPC transport with timeout, redirects disabled, a response-size cap, + response validation, and structured errors. +- Non-executing WASM validation, structural metadata, and bounded decoding of + `contractspecv0` XDR entries into entry kind/name/definition records. +- Deterministic structural analysis findings with stable rule IDs and SARIF 2.1.0 + serialization. +- Strict TOML configuration parsing, timeout validation, environment overrides, + and static diagnostic events, wired into `rpc-health`. +- CLI commands for WASM inspection, WASM analysis, and RPC health checks. +- Pinned CI actions, locked dependency resolution, a dedicated Rust 1.91.0 MSRV + job, RustSec dependency auditing, fuzz targets, release-validation workflow, + and release checklist. + +See [IMPLEMENTED_CAPABILITIES.md](IMPLEMENTED_CAPABILITIES.md), +[PROJECT_STATUS.md](PROJECT_STATUS.md), and [CHANGELOG.md](../CHANGELOG.md) for +exact scope. + +## Verified post-merge evidence + +- Merge commit: `aec759c` +- PR #127: https://github.com/StellarFoundry/stellar-devkit/pull/127 +- PR #133: https://github.com/StellarFoundry/stellar-devkit/pull/133 +- CI on `main`: + https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141880 +- RustSec audit on `main`: + https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141721 + +## Known limitations (represented honestly) + +- Contract-spec entries are decoded into XDR-JSON definitions with a variant kind + and best-effort name; a normalized, fully typed ABI schema is future work. +- Analysis rules are structural heuristics, not a complete vulnerability detector + and not proof of malicious intent. +- SARIF upload is available through a manual workflow dispatch and requires a + WASM artifact in the repository plus code-scanning permissions. +- RPC config is wired into `rpc-health`; other commands do not use RPC settings. + Endpoint precedence is command line, then environment, then config file. +- The workspace is `0.1.0`, but there is no tagged release, no release binaries, + and no crates.io publication. +- The project has limited external adoption: no external contributors have merged + PRs yet, and the repository is new. Do not present issue counts or labels as + evidence of traction. ## Contributor workflow - Issues are labeled by `area/*`, `type/*`, `difficulty/*`, and `phase/*`. -- Contributors request assignment before starting and follow each issue's scope and acceptance criteria. -- PRs reference the relevant issue, include tests and documentation, and report commands and results truthfully. -- The repository gate is `cargo fmt --all -- --check`, `cargo clippy --locked --workspace --all-targets --all-features -- -D warnings`, and `cargo test --locked --workspace --all-features`. CI runs on Linux, Windows, and macOS and includes Rust 1.91.0 MSRV tests; release validation checks packaging. +- Contributors request assignment before starting and follow each issue's scope + and acceptance criteria. +- PRs reference the relevant issue, include tests and documentation, and report + commands and results truthfully. +- The repository gate is `cargo fmt --all -- --check`, + `cargo clippy --locked --workspace --all-targets --all-features -- -D warnings`, + and `cargo test --locked --workspace --all-features`. CI runs on Linux, Windows, + and macOS and includes Rust 1.91.0 MSRV tests; release validation checks + packaging. ## Issue quality and backlog -The backlog audit and issue labels are documented in [DRIPS_ISSUE_QUALITY_AUDIT.md](DRIPS_ISSUE_QUALITY_AUDIT.md) and [ISSUE_BACKLOG.md](ISSUE_BACKLOG.md). Backlog issues are planned work, not completed features. Do not present issue count or labels as evidence that those features already exist. +There are 112 open issues: 82 Drips-ready, 24 blocked, 3 needing revision, and 3 +deferred. Five of the 82 are implemented or partially implemented on `main` and +are excluded from the Wave board pending closure or re-scope (#1, #7, #20, #25, +#33). The audit and manifest are regenerated from live GitHub issue numbers: + +- [DRIPS_ISSUE_QUALITY_AUDIT.md](DRIPS_ISSUE_QUALITY_AUDIT.md) +- [DRIPS_ISSUE_AUDIT.md](DRIPS_ISSUE_AUDIT.md) +- [ISSUE_BACKLOG.md](ISSUE_BACKLOG.md) +- [WAVE_BOARD.md](WAVE_BOARD.md) — 20 curated, independent, Wave-sized issues + +Backlog issues are planned work, not completed features. ## Security and release process -See [SECURITY.md](../SECURITY.md), [TESTING.md](TESTING.md), and [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md). Security claims must correspond to implementation and tests; secrets, endpoint values, and payloads should not be written to logs. +See [SECURITY.md](../SECURITY.md), [TESTING.md](TESTING.md), and +[RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md). Security claims must correspond to +implementation and tests; secrets, endpoint values, and payloads should not be +written to logs. ## Appeal readiness checklist -- [x] Both PR heads are included in a combined review branch; PR #127 remains open and unmerged. -- [x] The combined implementation passed CI on Linux, Windows, and macOS, plus formatting, Clippy, and Rust 1.91.0 MSRV tests. -- [x] The RustSec audit passed against the regenerated lockfile on the combined head. -- [x] User-facing documentation, project status, and changelog distinguish proposed work from work merged to `main`. -- [ ] The application is finalized with links to the combined PR, latest CI/audit results, and concrete completed work. -- [ ] A maintainer/program administrator has confirmed the applicable Wave application process and eligibility. - -The combined CI and RustSec audit are green. Passing checks do not establish maintainer approval or Drips eligibility; verify the program-specific requirements before submitting. +- [x] Implementation merged into `main` (PR #127 and PR #133, merge `aec759c`). +- [x] Post-merge CI passed on Linux, Windows, and macOS, plus formatting, Clippy, + and Rust 1.91.0 MSRV tests. +- [x] RustSec audit passed on `main`. +- [x] User-facing documentation, project status, and changelog describe merged + work as merged and planned work as planned. +- [x] Issue audit, backlog, and Wave board regenerated against `main`; completed + issues are no longer advertised as open work. +- [x] Scope boundary with `soroban-security-scanner` documented in + [WHY_DEVKIT.md](WHY_DEVKIT.md). +- [x] Appeal narrative and evidence table prepared in [APPEAL.md](APPEAL.md). +- [ ] Confirm in the Drips dashboard whether the repository is pending or + rejected, and note the rejection date and any stated reasons. +- [ ] Confirm the appeal window (first appeal no earlier than two weeks after + rejection) and submit through the dashboard only. +- [ ] Optional but recommended before appealing: tagged `v0.1.0` release with + binaries/checksums, and 3–5 external contributions or documented usage. + +Passing checks do not establish maintainer approval or Drips eligibility. Verify +the program-specific status before submitting. diff --git a/docs/FINAL_AUDIT.md b/docs/FINAL_AUDIT.md index 52ae19d..4a810cf 100644 --- a/docs/FINAL_AUDIT.md +++ b/docs/FINAL_AUDIT.md @@ -1,33 +1,41 @@ # Final Audit Honest status of the repository at the time of writing. **Verified** means the -check was actually run; **Pending** means it is not done. +check was actually run; **Partial** means some evidence exists but the item is +not complete; **Pending** means it is not done. + +Audit date: 2026-10-28. Commit: `aec759c`. | Item | Status | Evidence | | ---- | ------ | -------- | | Build succeeds | Verified | `cargo build` | -| Tests pass | Verified | 22 tests, `cargo test --all` | -| Lint passes | Verified | `cargo clippy --all-targets --all-features -- -D warnings` | +| Tests pass | Verified | `cargo test --locked --workspace --all-features` (43 tests); post-merge CI | +| Lint passes | Verified | `cargo clippy --locked --all-targets --all-features -- -D warnings` | | Formatting passes | Verified | `cargo fmt --all -- --check` | -| CI passes | Verified | GitHub Actions on Linux/Windows/macOS | +| CI passes | Verified | CI run 40690141880 on Linux/Windows/macOS | +| Dependency audit | Verified | RustSec run 40690141721 | | No secrets in repo | Verified | No secrets; `.gitignore` excludes keys/env | -| No placeholder/fake implementations | Verified | CLI exposes only working commands | -| Documentation for public features | Verified | README + docs set | -| Issue backlog present | Verified | 119 issues on GitHub | -| Issue complexity honest | Verified | 7 trivial / 84 medium / 28 high | -| Live RPC transport | Pending | Mock only; tracked as an issue | -| Contract inspection | Pending | Tracked as an issue | -| Security analysis + SARIF | Pending | Tracked as issues | -| GitHub Action | Pending | Tracked as an issue | -| Release binaries / crates.io | Pending | Tracked as issues | -| MSRV pinned | Pending | Tracked as an issue | -| Fuzzing | Pending | Tracked as an issue | -| Performance measured | Pending | Benchmark tracked as an issue | +| No placeholder/fake implementations | Verified | CLI exposes only commands that do real work | +| Documentation for public features | Verified | README plus the `docs/` set | +| Issue backlog present | Verified | 112 open issues | +| Issue complexity honest | Verified | 7 trivial / 78 medium / 27 high | +| Live RPC transport | Verified | `devkit_rpc::HttpTransport`; `rpc-health`; CI tests | +| Contract inspection | Verified | `inspect-wasm`; `devkit-contract` tests | +| Security analysis + SARIF | Verified (structural) | `devkit-analysis`; `analyze-wasm --format sarif` | +| MSRV pinned | Verified | `rust-version = "1.91"`; MSRV CI job | +| Fuzzing | Verified | `fuzz/fuzz_targets/*`; scheduled fuzz workflow | +| Performance measured | Partial | Memory measurement example; benchmarks pending | +| Composite GitHub Action | Pending | Tracked as an issue; only manual SARIF upload exists | +| Release binaries / crates.io | Pending | No tag, no binaries, no crates.io package | +| External contributors | Pending | No external contributor has merged a PR yet | ## Notes -- No documentation claims a feature that does not exist; the README lists - "what works today" and marks everything else as planned. +- The README lists what works today and marks planned work as planned. +- Analysis findings are structural heuristics and do not prove a contract is + secure. - No coverage percentage is claimed. -- No performance number is claimed. +- No performance number is claimed beyond the memory measurement example. - Complexity is not inflated to reach an aggregate reward target. +- The Wave board is curated from open issues only; see + [WAVE_BOARD.md](WAVE_BOARD.md). diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index bbb9d58..7c561ab 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -2,15 +2,21 @@ ## Prerequisites -- A recent stable Rust toolchain. +- Rust 1.91 or newer. +- No network access is required for decoding, strkey, or WASM inspection. -## Build +## Build and install ```bash cargo build --release ``` -The binary is written to `target/release/stellar-foundry`. +The binary is written to `target/release/stellar-foundry`. To install it from +the workspace: + +```bash +cargo install --path crates/devkit-cli +``` ## First steps @@ -20,7 +26,7 @@ stellar-foundry doctor ``` `doctor` reports the tool version, its capabilities, the known network profiles, -and that **network access is disabled**. There is no network functionality yet. +and that network access is explicit and limited to `rpc-health`. ## Classify an address @@ -49,18 +55,45 @@ stellar-foundry envelope --format json stellar-foundry event --format json ``` +Pass `-` to read one value from piped stdin: + +```bash +printf 'AAAAAwAAACo=' | stellar-foundry --format json scval - +``` + Malformed input produces a structured error and exit code `3`; it never panics. +## Inspect a contract artifact + +```bash +stellar-foundry inspect-wasm ./contract.wasm +stellar-foundry analyze-wasm --format sarif ./contract.wasm +``` + +Inspection is read-only and never executes the contract. + +## Check an RPC endpoint + +```bash +stellar-foundry endpoint https://soroban-testnet.stellar.org +stellar-foundry rpc-health https://soroban-testnet.stellar.org +``` + +`rpc-health` is the only command that makes a network request. It accepts an +endpoint argument, `STELLAR_FOUNDRY_RPC_URL`, or `rpc_url` in a TOML config file. +See [CLI.md](CLI.md) for configuration and precedence. + ## Exit codes | Code | Meaning | | ---- | ------- | | 0 | Success | | 2 | Usage error | -| 3 | Runtime error (decode failure) | +| 3 | Runtime error (decode failure, I/O) | ## Next - [CLI reference](CLI.md) +- [Why DevKit](WHY_DEVKIT.md) - [Architecture](ARCHITECTURE.md) -- [Ecosystem research](ECOSYSTEM_RESEARCH.md) +- [Implemented capabilities](IMPLEMENTED_CAPABILITIES.md) diff --git a/docs/IMPLEMENTED_CAPABILITIES.md b/docs/IMPLEMENTED_CAPABILITIES.md index cf463af..33d03c9 100644 --- a/docs/IMPLEMENTED_CAPABILITIES.md +++ b/docs/IMPLEMENTED_CAPABILITIES.md @@ -1,11 +1,60 @@ # Implemented library capabilities -This branch adds reusable library APIs for the remaining developer-tooling workstreams: +The merged implementation on `main` provides reusable library APIs for the +developer-tooling workstreams below. This page describes scope, not a roadmap. -- **RPC transport:** `devkit_rpc::HttpTransport` sends JSON-RPC POST requests with a finite timeout, disabled redirects, request ID validation, and a response byte cap enforced before JSON parsing. Endpoint policy continues to allow HTTPS and loopback-only HTTP. -- **WASM inspection:** `devkit_contract::inspect_wasm` validates the WASM container without executing it, and reports imports, exports, custom sections, and decodes the `contractspecv0` section as a bounded stream of official `ScSpecEntry` XDR values. It returns each decoded definition as XDR-JSON with a variant kind and best-effort declared name; the stream is capped at 4,096 entries. -- **Analysis and SARIF:** `devkit_analysis::analyze` emits deterministic findings with stable rule IDs and evidence. `to_sarif` produces SARIF 2.1.0. Current rules are structural heuristics, not proof of a vulnerability. -- **Configuration/diagnostics:** `devkit_config::Config` parses strict TOML, validates timeouts, and supports environment overrides. Verbose diagnostics accept static event names and avoid printing endpoints or payloads. -- **Release readiness:** the release-validation workflow runs tests, formatting/lint checks, and package validation on version tags. +- **RPC transport:** `devkit_rpc::HttpTransport` sends JSON-RPC POST requests + with a finite timeout, disabled redirects, request ID validation, and a + response byte cap enforced before JSON parsing. Endpoint policy continues to + allow HTTPS and loopback-only HTTP. +- **WASM inspection:** `devkit_contract::inspect_wasm` validates the WASM + container without executing it, and reports imports, exports, custom sections, + and decodes the `contractspecv0` section as a bounded stream of official + `ScSpecEntry` XDR values. It returns each decoded definition as XDR-JSON with + a variant kind and best-effort declared name; the stream is capped at 4,096 + entries. +- **Analysis and SARIF:** `devkit_analysis::analyze` emits deterministic findings + with stable rule IDs and evidence. `to_sarif` produces SARIF 2.1.0. Current + rules are structural heuristics, not proof of a vulnerability. +- **Configuration/diagnostics:** `devkit_config::Config` parses strict TOML, + validates timeouts, and supports environment overrides. Verbose diagnostics + accept static event names and avoid printing endpoints or payloads. +- **Release readiness:** the release-validation workflow runs tests, + formatting/lint checks, and package validation on version tags. -CLI commands are available as `inspect-wasm`, `analyze-wasm`, and `rpc-health`. A manual GitHub Actions workflow can upload SARIF to code scanning when given a repository-relative WASM artifact path. The analysis rules remain structural heuristics, not a comprehensive vulnerability engine. No WASM is executed and no network request is made unless a caller explicitly constructs and uses the HTTP transport. +## CLI + +```text +stellar-foundry version +stellar-foundry doctor +stellar-foundry strkey +stellar-foundry scval +stellar-foundry envelope +stellar-foundry event +stellar-foundry endpoint +stellar-foundry inspect-wasm +stellar-foundry analyze-wasm [--format sarif] +stellar-foundry rpc-health [ENDPOINT] +``` + +`--format json` produces machine-readable output and structured JSON errors. +`--format sarif` is accepted by `analyze-wasm`. Exit codes are `0` success, `2` +usage error, and `3` runtime/decode error. + +A manual GitHub Actions workflow can upload SARIF to code scanning when given a +repository-relative WASM artifact path. The analysis rules remain structural +heuristics, not a comprehensive vulnerability engine. No WASM is executed, and +no network request is made unless a caller explicitly runs `rpc-health` or +constructs `HttpTransport`. + +## Not implemented yet + +- Normalized ABI schema for every `contractspecv0` entry type. +- Typed models for `getLedgerEntries`, `getTransaction(s)`, `getFeeStats`, and + paginated `getEvents`. +- Exponential backoff with jitter, cancellation, and `Retry-After` handling. +- Composite GitHub Action, baseline scanning, and SBOM/attestations. +- Tagged release, release binaries, and crates.io publication. +- Caching, persistence, and structured logging beyond static diagnostics. + +These are tracked as open issues; see [ISSUE_BACKLOG.md](ISSUE_BACKLOG.md). diff --git a/docs/ISSUE_BACKLOG.md b/docs/ISSUE_BACKLOG.md index f1d047a..e515c1f 100644 --- a/docs/ISSUE_BACKLOG.md +++ b/docs/ISSUE_BACKLOG.md @@ -3,9 +3,9 @@ Generated from `tools/backlog/issues_*.json`. Closed and superseded definitions are excluded. -**Total open issues:** 119 +**Total open issues:** 112 -Complexity: 7 trivial, 84 medium, 28 high. +Complexity: 7 trivial, 78 medium, 27 high. ## phase/01-foundation @@ -97,12 +97,10 @@ Complexity: 7 trivial, 84 medium, 28 high. | #17 | feat(testing): add a fixture loader and schema | testing | high | None. | | #18 | feat(testing): add mock RPC network scenarios | rpc | medium | Fixture loader issue. | | #19 | test(xdr): add property-based round-trip tests | xdr | medium | Encode helpers issue. | -| #89 | test(xdr): add a malformed XDR corpus | xdr | medium | None. | | #90 | test(rpc): add snapshot tests for RPC response models | rpc | medium | None. | | #91 | test: add cross-platform and endianness tests | testing | medium | None. | | #92 | test: add a regression corpus runner | testing | medium | Fixture loader issue. | | #93 | test(contracts): add fixture WASM contracts | contract-inspection | high | WASM spec extraction issue. | -| #94 | test(ci): add a scheduled fuzz smoke job | security | medium | Fuzz targets. | ## phase/07-security @@ -119,7 +117,6 @@ Complexity: 7 trivial, 84 medium, 28 high. | #83 | test(security): add false-negative regression tests | testing | medium | Rule engine issue. | | #84 | feat(security): validate contract metadata for consistency | contract-inspection | medium | WASM spec extraction issue. | | #85 | feat(security): add WASM safety checks | contract-inspection | high | WASM container validation issue. | -| #86 | feat(security): harden against untrusted RPC responses | rpc | high | Live transport issue. | | #88 | test(security): fuzz RPC response parsing | rpc | medium | Untrusted RPC response hardening issue. | ## phase/08-cli @@ -134,8 +131,6 @@ Complexity: 7 trivial, 84 medium, 28 high. | #96 | feat(cli): unify global flags across commands | cli | medium | None. | | #97 | feat(cli): improve error presentation with suggestions | cli | medium | Secret redaction issue. | | #98 | feat(cli): add verbosity control | cli | trivial | Structured logging issue. | -| #99 | feat(cli): add a JSON error output mode | cli | medium | Error taxonomy issue. | -| #100 | feat(cli): add stdin input for decode commands | cli | medium | None. | ## phase/09-github @@ -159,7 +154,6 @@ Complexity: 7 trivial, 84 medium, 28 high. | #28 | perf(observability): benchmark decode throughput | observability | medium | None. | | #107 | perf(rpc): measure and document RPC call overhead | rpc | medium | Local integration test server issue. | | #108 | perf(xdr): optimize SCVal decoding for large maps | scval | medium | SCVal collections issue. | -| #109 | perf: measure memory usage on large inputs | performance | medium | None. | | #110 | feat(core): add an optional decode cache | core | medium | None. | | #111 | perf: add performance regression tests to CI | performance | medium | Decode and RPC benchmarks. | @@ -171,7 +165,6 @@ Complexity: 7 trivial, 84 medium, 28 high. | #31 | ci(deps): configure automated dependency updates | release | trivial | None. | | #34 | ci(msrv): pin and test a minimum supported Rust version | release | medium | None. | | #112 | docs(release): define the versioning and compatibility policy | release | medium | None. | -| #113 | ci(release): automate changelog generation | release | medium | Versioning policy issue. | | #114 | feat(release): prepare crates.io packaging | release | high | MSRV pin. | | #115 | ci(release): generate an SBOM and artifact attestations | security | high | Release binaries issue. | | #116 | ci(release): add compatibility testing across toolchains | release | medium | MSRV pin. | @@ -195,10 +188,10 @@ Complexity: 7 trivial, 84 medium, 28 high. | phase/03-xdr-scval | 13 | | phase/04-analysis | 15 | | phase/05-contracts | 10 | -| phase/06-testing | 9 | -| phase/07-security | 13 | -| phase/08-cli | 10 | +| phase/06-testing | 7 | +| phase/07-security | 12 | +| phase/08-cli | 8 | | phase/09-github | 10 | -| phase/10-observability | 6 | -| phase/12-release | 8 | -| **Total** | **119** | +| phase/10-observability | 5 | +| phase/12-release | 7 | +| **Total** | **112** | diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index 6ed6204..bfc3afc 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -1,52 +1,100 @@ # Project Status -**Current phase:** Foundation and developer-tooling implementation in review +**Current phase:** Developer-tooling implementation merged on `main`; pre-release hardening **Repository:** https://github.com/StellarFoundry/stellar-devkit **Default branch:** `main` -**Status note:** The capabilities below are on an open pull-request branch and are not all merged into `main`. PR #133 includes PR #127's security-hardening head as a second parent for combined validation. Both PRs remain open; PR #127 is unmerged. +**Status note:** PR #127 (security/CI hardening) and PR #133 (RPC transport, WASM +inspection, analysis, and configuration) were merged into `main` on 2026-10-28. +The merge commit is `aec759c`. CI and the RustSec audit are green on `main`. -## Implemented in the combined feature branch +## Implemented on `main` - `devkit-core`: structured errors, network profiles, output formats. -- `devkit-xdr`: bounded decoding of base64 `ScVal`, `TransactionEnvelope`, and `ContractEvent`; strkey classification; malformed-input regression fixtures. -- `stellar-foundry` CLI: `version`, `doctor`, `strkey`, `scval`, `envelope`, `event`, `endpoint`, `inspect-wasm`, `analyze-wasm`, and `rpc-health`; terminal/JSON output, SARIF output for analysis, and exit codes 0/2/3. -- `devkit-rpc`: typed RPC protocol layer, deterministic mock transport, endpoint validation, typed health/network/latest-ledger results, retry policy, and bounded HTTP JSON-RPC transport. -- `devkit-contract`: bounded, non-executing WASM validation, import/export/custom-section metadata, and bounded `contractspecv0` XDR stream decoding into entry kind/name/definition records. -- `devkit-analysis`: deterministic structural findings with stable rule IDs and SARIF 2.1.0 serialization. -- `devkit-config`: strict TOML parsing, timeout validation, environment overrides, and static diagnostics. -- CI: pinned actions, locked dependency resolution, formatting, Clippy, Linux/Windows/macOS tests, and Rust 1.91.0 MSRV tests. -- Security: RustSec dependency audit workflow, bounded malformed-XDR regression corpus, and a manual SARIF upload workflow for GitHub code scanning. -- Release preparation: release-validation workflow, release checklist, implementation-capabilities documentation, updated changelog, and Drips readiness checklist. +- `devkit-xdr`: bounded decoding of base64 `ScVal`, `TransactionEnvelope`, and + `ContractEvent`; strkey classification; malformed-input regression fixtures. +- `stellar-foundry` CLI: `version`, `doctor`, `strkey`, `scval`, `envelope`, + `event`, `endpoint`, `inspect-wasm`, `analyze-wasm`, and `rpc-health`; + terminal/JSON output, SARIF output for analysis, and exit codes 0/2/3. +- `devkit-rpc`: typed RPC protocol layer, deterministic mock transport, endpoint + validation, typed health/network/latest-ledger results, retry policy, and + bounded HTTP JSON-RPC transport. +- `devkit-contract`: bounded, non-executing WASM validation, import/export/ + custom-section metadata, and bounded `contractspecv0` XDR stream decoding into + entry kind/name/definition records. +- `devkit-analysis`: deterministic structural findings with stable rule IDs and + SARIF 2.1.0 serialization. +- `devkit-config`: strict TOML parsing, timeout validation, environment + overrides, and static diagnostics. +- CI: pinned actions, locked dependency resolution, formatting, Clippy, + Linux/Windows/macOS tests, and Rust 1.91.0 MSRV tests. +- Security: RustSec dependency audit workflow, bounded malformed-XDR regression + corpus, fuzz targets, and a manual SARIF upload workflow for GitHub code + scanning. +- Release preparation: release-validation workflow, release checklist, + implementation-capabilities documentation, updated changelog, and Drips + readiness checklist. ## Verified CI status -The previously integrated branch passed formatting, Clippy, Linux, Windows, macOS, and Rust 1.91.0 MSRV tests, plus RustSec. New contract-spec decoding, CLI config wiring, and SARIF workflow changes are awaiting a fresh combined CI and audit run before merge. +The post-merge `main` run passed formatting, Clippy, Linux, Windows, macOS, and +Rust 1.91.0 MSRV tests: + +- CI: https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141880 +- Dependency Security Audit: + https://github.com/StellarFoundry/stellar-devkit/actions/runs/40690141721 + +## Release status + +The workspace version is `0.1.0`. There is **no tagged release**, no GitHub +Release with binaries, and no crates.io publication yet. The release-validation +workflow and checklist exist, but publishing remains outstanding work. ## Remaining limitations -- `contractspecv0` entries are decoded into XDR-JSON definitions with variant names and best-effort declared names; this is not yet a fully normalized ABI schema for every entry type. -- Security-analysis rules are structural heuristics, not a comprehensive vulnerability engine. -- SARIF upload is available through a manually triggered workflow; it requires a repository-relative WASM artifact and GitHub code-scanning permissions. -- RPC configuration is wired into `rpc-health`: command-line endpoint overrides environment, which overrides the TOML file. Other commands do not consume RPC configuration because they do not need it. -- Do not describe unmerged work as already released or available from `main`. +- `contractspecv0` entries are decoded into XDR-JSON definitions with variant + names and best-effort declared names; this is not yet a fully normalized ABI + schema for every entry type. +- Security-analysis rules are structural heuristics, not a comprehensive + vulnerability engine. +- SARIF upload is available through a manually triggered workflow; it requires a + repository-relative WASM artifact and GitHub code-scanning permissions. +- RPC configuration is wired into `rpc-health`: command-line endpoint overrides + environment, which overrides the TOML file. Other commands do not consume RPC + configuration because they do not make network requests. +- The project is pre-release. Do not describe the workspace version as a + published release. ## Security status - XDR and WASM inputs are bounded in the implemented paths. -- The HTTP transport uses a finite timeout, disables redirects, bounds response bytes before parsing, and validates JSON-RPC responses. -- Endpoint policy rejects embedded credentials and permits plaintext HTTP only for loopback. -- Security claims should be limited to behavior demonstrated by code and tests; no system is claimed to be vulnerability-free. +- The HTTP transport uses a finite timeout, disables redirects, bounds response + bytes before parsing, and validates JSON-RPC responses. +- Endpoint policy rejects embedded credentials and permits plaintext HTTP only + for loopback. +- Security claims should be limited to behavior demonstrated by code and tests; + no system is claimed to be vulnerability-free. ## Contributor backlog -The issue backlog is a roadmap, not a list of completed features. Audit counts, labels, and issue descriptions must not be presented as proof that the corresponding work is implemented. See [ISSUE_BACKLOG.md](ISSUE_BACKLOG.md) and [DRIPS_ISSUE_QUALITY_AUDIT.md](DRIPS_ISSUE_QUALITY_AUDIT.md). +There are 112 open issues: 82 Drips-ready, 24 blocked by dependencies, 3 needing +revision, and 3 deferred. Five of the 82 are implemented or partially +implemented on `main` and are excluded from the Wave board pending closure or +re-scope (#1, #7, #20, #25, #33). The backlog is a roadmap, not a list of +completed features. Audit counts, labels, and issue descriptions must not be presented as +proof that the corresponding work is implemented. + +See [ISSUE_BACKLOG.md](ISSUE_BACKLOG.md), +[DRIPS_ISSUE_QUALITY_AUDIT.md](DRIPS_ISSUE_QUALITY_AUDIT.md), and +[WAVE_BOARD.md](WAVE_BOARD.md). ## Drips documents - [Drips readiness checklist](DRIPS_READINESS.md) - [Drips application draft](DRIPS_APPLICATION_DRAFT.md) +- [Appeal summary](APPEAL.md) - [Issue audit](DRIPS_ISSUE_AUDIT.md) - [Contributing through Drips Wave](WAVE.md) +- [Why DevKit](WHY_DEVKIT.md) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 87d0ef9..3d9f4a8 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -5,40 +5,52 @@ This roadmap distinguishes **Completed** (works today), **In progress**, and ## Completed (works today) -- Workspace: `devkit-core`, `devkit-xdr`, `devkit-rpc`, `devkit-cli`. +- Workspace: `devkit-core`, `devkit-xdr`, `devkit-rpc`, `devkit-contract`, + `devkit-analysis`, `devkit-config`, and `devkit-cli`. - Bounded base64 decoding of `ScVal`, `TransactionEnvelope`, and `ContractEvent` to JSON via `stellar-xdr`. - Strkey classification via `stellar-strkey`. -- Endpoint security validation (https only; loopback http; no credentials). -- Typed RPC protocol layer with a deterministic mock transport and retry policy. -- CLI: `version`, `doctor`, `strkey`, `scval`, `envelope`, `event`, `endpoint`. -- CI (fmt, clippy, tests) on Linux, Windows, and macOS. +- Endpoint security validation (HTTPS; loopback HTTP; no credentials). +- Typed RPC protocol layer, deterministic mock transport, retry policy, and + bounded HTTP JSON-RPC transport with a finite timeout. +- Non-executing WASM validation, import/export/custom-section metadata, and + bounded `contractspecv0` decoding. +- Deterministic structural findings and SARIF 2.1.0 serialization. +- Strict TOML configuration with environment overrides, wired into `rpc-health`. +- CLI: `version`, `doctor`, `strkey`, `scval`, `envelope`, `event`, `endpoint`, + `inspect-wasm`, `analyze-wasm`, `rpc-health`. +- CI (fmt, Clippy, tests) on Linux, Windows, and macOS; Rust 1.91.0 MSRV; + RustSec audit; malformed-XDR corpus; fuzz targets. ## In progress -- Nothing is partially implemented; the next work item is the live RPC transport - (issue-backed). +- Release packaging: tag `v0.1.0`, publish release binaries with checksums, and + publish the workspace crates to crates.io. +- Typed RPC response models for `getLedgerEntries`, `getTransaction(s)`, and + `getFeeStats`, plus pagination for list methods. ## Planned (issue-backed phases) +There are 112 open issues. The counts below come from the current labels. + | Phase | Focus | Issues | | ----- | ----- | ------ | | 01 Foundation | Error taxonomy, shared models, output envelope, validation primitives | 5 | -| 02 RPC | Live transport, request construction, error taxonomy, pagination, rate limits, integration server | 13 | -| 03 XDR / SCVal | Collections, addresses, result/meta, diagnostic events, ledger entries, typed conversions, schema | 14 | -| 04 Analysis | Envelope/operation/fee/signature/memo/bounds/footprint/result analysis, events, ledger helpers | 17 | -| 05 Contracts | Contract IDs, WASM validation, spec inspection, storage, events-to-spec, environment, CLI | 12 | -| 06 Testing | Fixture loader, malformed corpus, snapshots, cross-platform, corpus runner, WASM fixtures, fuzz CI | 12 | -| 07 Security | Rule engine, findings, suppression, corpus, FP/FN tests, metadata/WASM/RPC hardening, SARIF catalog | 11 | -| 08 CLI / config | Configuration, profiles, global flags, error UX, verbosity, JSON errors, stdin | 12 | -| 09 GitHub / CI | Action, reusable workflow, SARIF upload, baseline, release validation, triage, auditing | 10 | -| 10 Performance / observability | RPC and decode benchmarks, memory, cache, regression tests, logging | 9 | -| 11 Developer experience | Docs and integration guides | 5 | -| 12 Release | Versioning policy, changelog automation, crates.io readiness, SBOM, compatibility matrix | 8 | +| 02 RPC | Typed models, request construction, error taxonomy, pagination, rate limits, integration server | 15 | +| 03 XDR / SCVal | Collections, addresses, result/meta, diagnostic events, ledger entries, typed conversions, schema | 13 | +| 04 Analysis | Envelope/operation/fee/signature/memo/bounds/footprint/result analysis, events, ledger helpers | 15 | +| 05 Contracts | Contract IDs, storage, events-to-spec, environment, CLI | 10 | +| 06 Testing | Fixture loader, snapshots, cross-platform, corpus runner, WASM fixtures | 7 | +| 07 Security | Rule engine, findings, suppression, corpus, FP/FN tests, metadata/WASM/RPC hardening, SARIF catalog | 12 | +| 08 CLI / config | Configuration, profiles, global flags, error UX, verbosity, JSON errors, stdin | 8 | +| 09 GitHub / CI | Action, reusable workflow, SARIF upload, baseline, triage, auditing | 10 | +| 10 Performance / observability | RPC and decode benchmarks, cache, regression tests, logging | 5 | +| 12 Release | Versioning policy, crates.io readiness, SBOM, compatibility matrix | 7 | | 13 Documentation | RPC, XDR/SCVal, contract, security authoring, configuration guides | 5 | -The exact issue counts per phase come from -[ISSUE_BACKLOG.md](ISSUE_BACKLOG.md). See also [PROJECT_STATUS.md](PROJECT_STATUS.md). +The exact issue numbers, titles, and dependencies are in +[ISSUE_BACKLOG.md](ISSUE_BACKLOG.md). See also [PROJECT_STATUS.md](PROJECT_STATUS.md) +and [WAVE_BOARD.md](WAVE_BOARD.md). ## Future (not yet specified) @@ -49,9 +61,13 @@ The exact issue counts per phase come from ## Dependency shape ``` -foundation ─▶ xdr/scval ─▶ transactions ─▶ contracts ─▶ security engine ─▶ SARIF/GitHub +foundation ─▶ xdr/scval ─▶ transactions ─▶ contracts ─▶ inspection └─────▶ rpc protocol ─▶ live transport ─▶ resilience ─▶ events/ledger ``` +Structural security analysis and SARIF are implemented for the checks the +project actually ships. Source-level vulnerability detection remains the +responsibility of `soroban-security-scanner`. + Issues state their dependencies explicitly. Many are independent and can be started in parallel. diff --git a/docs/WAVE_BOARD.md b/docs/WAVE_BOARD.md index 824f0ec..10a4fba 100644 --- a/docs/WAVE_BOARD.md +++ b/docs/WAVE_BOARD.md @@ -1,9 +1,12 @@ # Wave Board (first program) -A curated, single-cycle subset of the backlog for the first Drips Wave, chosen -from issues marked `status/ready`. Every issue here is **independent**, -**completable in one cycle**, and **representative** of the project. It is -deliberately a small subset of the full backlog, with a bounded points budget. +A curated, single-cycle subset of the backlog for a Drips Wave, chosen from +issues marked `status/ready`. Every issue here is **open**, **unassigned**, +**independent**, **completable in one cycle**, and **not already implemented on +`main`**. It is deliberately a small subset of the full backlog, with a bounded +points budget. + +Verified against `main` at commit `aec759c` on 2026-10-28. Point values are assigned in the Drips Wave maintainer dashboard (Trivial 100 / Medium 150 / High 200). The labels here are the honest pre-estimate. @@ -12,10 +15,13 @@ Medium 150 / High 200). The labels here are the honest pre-estimate. | Complexity | Issues | Points each | Subtotal | | ---------- | -----: | ----------: | -------: | -| Trivial | 6 | 100 | 600 | -| Medium | 10 | 150 | 1,500 | +| Trivial | 3 | 100 | 300 | +| Medium | 13 | 150 | 1,950 | | High | 4 | 200 | 800 | -| **Total** | **20** | | **2,900** | +| **Total** | **20** | | **3,050** | + +The repository budget is 25,000 points per Wave, so this board uses about 12% +of it and leaves room to add more later. ## Trivial (100 points) @@ -24,40 +30,57 @@ Medium 150 / High 200). The labels here are the honest pre-estimate. | [#6](https://github.com/StellarFoundry/stellar-devkit/issues/6) | feat(rpc): add a typed model for getFeeStats | | [#30](https://github.com/StellarFoundry/stellar-devkit/issues/30) | feat(cli): add shell completion generation | | [#31](https://github.com/StellarFoundry/stellar-devkit/issues/31) | ci(deps): configure automated dependency updates | -| [#33](https://github.com/StellarFoundry/stellar-devkit/issues/33) | test(cli): assert the exit-code contract | -| [#40](https://github.com/StellarFoundry/stellar-devkit/issues/40) | test(core): add deterministic snapshot tests for core types | -| [#98](https://github.com/StellarFoundry/stellar-devkit/issues/98) | feat(cli): add verbosity control | ## Medium (150 points) | # | Title | | - | ----- | -| [#2](https://github.com/StellarFoundry/stellar-devkit/issues/2) | feat(rpc): add timeouts and cancellation to RPC calls | -| [#4](https://github.com/StellarFoundry/stellar-devkit/issues/4) | feat(rpc): add a typed model for getLedgerEntries | -| [#5](https://github.com/StellarFoundry/stellar-devkit/issues/5) | feat(rpc): add typed models for getTransaction and getTransactions | -| [#7](https://github.com/StellarFoundry/stellar-devkit/issues/7) | feat(core): add a configuration system with file and environment support | +| [#3](https://github.com/StellarFoundry/stellar-devkit/issues/3) | feat(rpc): add exponential backoff with jitter to retries | | [#10](https://github.com/StellarFoundry/stellar-devkit/issues/10) | feat(core): add structured logging with levels | -| [#13](https://github.com/StellarFoundry/stellar-devkit/issues/13) | feat(security): make XDR decode limits configurable and strict | +| [#15](https://github.com/StellarFoundry/stellar-devkit/issues/15) | feat(cli): add batch decoding from files and directories | | [#26](https://github.com/StellarFoundry/stellar-devkit/issues/26) | feat(transactions): add an envelope summary command | -| [#36](https://github.com/StellarFoundry/stellar-devkit/issues/36) | feat(core): define a categorized error taxonomy | -| [#43](https://github.com/StellarFoundry/stellar-devkit/issues/43) | feat(rpc): add cursor-based pagination for list methods | -| [#48](https://github.com/StellarFoundry/stellar-devkit/issues/48) | feat(scval): fully decode and render maps and vectors | +| [#37](https://github.com/StellarFoundry/stellar-devkit/issues/37) | feat(core): add shared Severity and Confidence models | +| [#38](https://github.com/StellarFoundry/stellar-devkit/issues/38) | feat(core): add a versioned output envelope for machine-readable commands | +| [#39](https://github.com/StellarFoundry/stellar-devkit/issues/39) | refactor(core): add validation primitives for untrusted strings | +| [#59](https://github.com/StellarFoundry/stellar-devkit/issues/59) | feat(transactions): inspect signatures and signer hints | +| [#60](https://github.com/StellarFoundry/stellar-devkit/issues/60) | feat(transactions): handle memo and time/ledger bounds | +| [#105](https://github.com/StellarFoundry/stellar-devkit/issues/105) | chore(ci): add triage automation for issues and pull requests | +| [#112](https://github.com/StellarFoundry/stellar-devkit/issues/112) | docs(release): define the versioning and compatibility policy | +| [#117](https://github.com/StellarFoundry/stellar-devkit/issues/117) | docs: add an RPC guide | +| [#118](https://github.com/StellarFoundry/stellar-devkit/issues/118) | docs: add an XDR and SCVal guide | ## High (200 points) | # | Title | | - | ----- | -| [#1](https://github.com/StellarFoundry/stellar-devkit/issues/1) | feat(rpc): implement a live HTTP transport over the official client | | [#12](https://github.com/StellarFoundry/stellar-devkit/issues/12) | feat(xdr): define a versioned JSON schema for decoded values | -| [#20](https://github.com/StellarFoundry/stellar-devkit/issues/20) | test(security): add a fuzz target for XDR and SCVal decoding | -| [#25](https://github.com/StellarFoundry/stellar-devkit/issues/25) | feat(contracts): inspect WASM contract specs via soroban-spec | +| [#24](https://github.com/StellarFoundry/stellar-devkit/issues/24) | feat(github): add a composite Action to run DevKit checks | +| [#53](https://github.com/StellarFoundry/stellar-devkit/issues/53) | feat(scval): add type-safe conversions between SCVal and Rust primitives | +| [#57](https://github.com/StellarFoundry/stellar-devkit/issues/57) | feat(transactions): inspect operations with type-specific detail | ## Notes -- No issue in this set depends on another; each can be merged independently. -- All issues are `status/ready`. Issues marked `status/blocked` are intentionally - excluded until their dependency lands. +- No issue in this set depends on another issue in this set; each can be merged + independently. +- All issues are `status/ready`, open, and unassigned. - Contributors must request assignment before starting; see [`WAVE.md`](WAVE.md). - After repository approval, add these issues to the Program. Apply the `Stellar Wave` label or select them in the **Maintainers → Issues** dashboard. - Keep the budget bounded; do not add every open issue to a single Wave. + +## Excluded after the post-merge audit + +These issues were on older board drafts but are implemented or partially +implemented on `main`. They are excluded until a maintainer closes or re-scopes +them: + +| # | Status | +| - | ------ | +| #1 | Bounded HTTP transport exists; official `stellar-rpc-client` integration remains | +| #7 | Configuration exists and is wired into `rpc-health`; `docs/CONFIGURATION.md` now documents it; precedence tests remain | +| #20 | Fuzz crate, three targets, and a scheduled workflow exist | +| #25 | `contractspecv0` decoding exists; a fixture-WASM spec test and normalized ABI remain | +| #33 | CLI exit-code assertions exist in `crates/devkit-cli/tests/json_errors.rs` | + +`#40` and `#98` are also excluded from this board because they depend on issues +not in this set (error taxonomy and structured logging respectively). diff --git a/docs/WHY_DEVKIT.md b/docs/WHY_DEVKIT.md new file mode 100644 index 0000000..24c4e4c --- /dev/null +++ b/docs/WHY_DEVKIT.md @@ -0,0 +1,86 @@ +# Why DevKit + +This page explains what StellarFoundry DevKit is, what it is not, and how it +relates to existing Stellar tooling. It exists so maintainers, reviewers, and +contributors can judge scope without guessing. + +## One sentence + +DevKit is a **developer workflow and inspection layer** for Stellar and Soroban: +it turns XDR, transactions, events, contract artifacts, and RPC responses into +stable, structured output that developers can use in scripts, tests, and CI. + +## What DevKit is + +- A Rust workspace with reusable library APIs and a `stellar-foundry` CLI. +- A bounded, offline-by-default decoder for `ScVal`, `TransactionEnvelope`, and + `ContractEvent`. +- A safe RPC layer: endpoint policy, typed protocol models, deterministic mocks, + retries, timeouts, and a bounded HTTP transport. +- A read-only contract inspector: WASM container validation, imports/exports, + custom sections, and `contractspecv0` metadata. No contract code is executed. +- A deterministic structural analysis and SARIF emitter for the checks it + actually implements. + +## What DevKit is not + +- Not a replacement for `stellar-cli` (build, deploy, invoke). +- Not a reimplementation of `stellar-xdr`, `stellar-strkey`, or a JSON-RPC + client. +- Not an indexer or a Horizon replacement. +- Not a source-level vulnerability scanner. +- Not a guarantee that a contract is safe. +- Not an AI product; AI is never required. + +## Boundary with `soroban-security-scanner` + +Both projects live in the StellarFoundry organization and both care about +security. They operate at different layers: + +| Concern | DevKit | `soroban-security-scanner` | +| ------- | ------ | -------------------------- | +| Primary input | XDR, transactions, events, RPC responses, compiled WASM | Soroban/Rust **source code** and project layout | +| Primary job | Decode, inspect, validate, and explain developer data | Detect source-level vulnerability patterns | +| Analysis depth | Structural metadata and a small set of honest heuristics | Rule engine with a detector corpus, baselines, and suppressions | +| Output | Terminal/JSON, SARIF for implemented checks | Findings, SARIF, GitHub Action, reports | +| Typical user | Developer debugging a transaction, event, or contract artifact | Security reviewer or CI pipeline scanning a contract repo | +| Execution | Read-only; never runs contract code | Static analysis; does not execute the contract | + +The overlap is deliberate but narrow: both can emit SARIF and both understand +contract artifacts. DevKit does **not** claim to replace the scanner, and the +scanner does **not** replace DevKit's decode/RPC workflow. Changes that belong +to source-level detection should go to `soroban-security-scanner`; changes that +belong to XDR/RPC/transaction inspection belong here. + +## Boundary with official Stellar tooling + +| Tool | Relationship | +| ---- | ------------ | +| `stellar-xdr` | DevKit depends on it for XDR types and base64 decoding. | +| `stellar-strkey` | DevKit depends on it for address classification. | +| `stellar-cli` | DevKit complements it. Use `stellar-cli` to build/deploy/invoke; use DevKit to inspect and script the resulting data. | +| Stellar RPC | DevKit validates endpoints, models responses, and provides bounded transport plus mocks. It does not replace the official client. | + +## Workflows DevKit is designed for + +1. **Debug a failing transaction** — decode the envelope, inspect operations and + signatures, and compare the result with the RPC response. +2. **Triage a contract event** — decode `ContractEvent` values and correlate + them with the ledger/transaction that produced them. +3. **Inspect a contract artifact before deployment** — list imports/exports, + custom sections, and declared spec entries without executing the WASM. +4. **Test RPC-dependent tooling offline** — use the deterministic mock transport + and fixtures instead of a live network. +5. **Emit machine-readable evidence in CI** — stable JSON and SARIF for the + checks that are actually implemented. + +## Honest limitations + +- `contractspecv0` decoding is XDR-JSON plus best-effort names, not a normalized + ABI. +- Structural analysis is heuristic, not a vulnerability proof. +- RPC configuration currently applies to `rpc-health`. +- No tagged release or crates.io publication exists yet. + +If a workflow needs something not listed here, treat it as planned work only +when an open issue says so. diff --git a/tools/audit_backlog.py b/tools/audit_backlog.py index 6eca599..31fd1e0 100644 --- a/tools/audit_backlog.py +++ b/tools/audit_backlog.py @@ -11,14 +11,24 @@ from __future__ import annotations import argparse +import datetime import json import re +import subprocess from collections import Counter from pathlib import Path ROOT = Path(__file__).resolve().parent.parent OUT = ROOT / "docs" / "DRIPS_ISSUE_QUALITY_AUDIT.md" + +def repository_commit() -> str: + result = subprocess.run( + ["git", "rev-parse", "--short", "HEAD"], + capture_output=True, text=True, encoding="utf-8", + ) + return result.stdout.strip() or "unknown" + # Duplicate issue -> canonical issue. DUPLICATES = {51: 73} # Issue that should be merged into another (no independent value). @@ -155,9 +165,9 @@ def dep_number(phrase: str): lines = [ "# Drips Issue Quality Audit", "", - "- **Audit date:** 2026-09-22", - "- **Repository commit audited:** 07bef9e", - "- **Issues classified:** " + str(len(rows)) + " (1 duplicate and 1 merge closed during remediation; 119 open).", + f"- **Audit date:** {datetime.date.today().isoformat()}", + f"- **Repository commit audited:** {repository_commit()}", + f"- **Issues classified:** {len(rows)} open issues.", "", "Standard applied: Drips *Creating Meaningful Issues* and the Wave maintainer", "documentation. Classification is evidence-based; weak issues are flagged, not", @@ -175,6 +185,10 @@ def dep_number(phrase: str): f"| Defer | {counts.get('Defer / future work', 0)} |", f"| Blocked | {counts.get('Blocked by dependency', 0)} |", "", + f"> **Post-merge note ({datetime.date.today().isoformat()}):** #1, #7, #20, #25,", + "> and #33 have merged or partial implementation on `main` and are excluded", + "> from `docs/WAVE_BOARD.md` pending maintainer closure or re-scope.", + "", "No issue required splitting: the largest issues are already scoped to a single", "capability, and the previously broad areas had already been decomposed.", "", diff --git a/tools/generate_issue_audit.py b/tools/generate_issue_audit.py index d232abc..df16133 100644 --- a/tools/generate_issue_audit.py +++ b/tools/generate_issue_audit.py @@ -5,9 +5,12 @@ import glob import json +import subprocess +import sys from pathlib import Path ROOT = Path(__file__).resolve().parent.parent +REPO = "StellarFoundry/stellar-devkit" OUT = ROOT / "docs" / "DRIPS_ISSUE_AUDIT.md" COMPLEXITY_RANK = {"trivial": 0, "medium": 1, "high": 2} @@ -31,13 +34,29 @@ def area(labels: list[str]) -> str: return "area/other" +def open_numbers() -> dict[str, int]: + result = subprocess.run( + ["gh", "issue", "list", "--repo", REPO, "--state", "open", "--limit", "2000", + "--json", "number,title"], + capture_output=True, text=True, encoding="utf-8", + ) + if result.returncode != 0: + print(result.stderr, file=sys.stderr) + sys.exit(1) + return {i["title"]: i["number"] for i in json.loads(result.stdout or "[]")} + + def main() -> int: + numbers = open_numbers() issues = [] for path in sorted(glob.glob(str(ROOT / "tools" / "backlog" / "issues_*.json"))): for issue in json.loads(Path(path).read_text(encoding="utf-8")): if issue["title"] in CLOSED_TITLES: continue - issues.append(issue) + number = numbers.get(issue["title"]) + if number is None: + continue + issues.append({**issue, "number": number}) issues.sort(key=lambda i: (COMPLEXITY_RANK.get(i.get("complexity", "medium"), 1), i["title"])) @@ -64,7 +83,7 @@ def main() -> int: "| # | Title | Area | Complexity | Dependencies | Acceptance | Tests | Security |", "| - | ----- | ---- | ---------- | ------------ | ---------- | ----- | -------- |", ] - for idx, issue in enumerate(issues, start=1): + for issue in issues: labels = issue.get("labels", []) complexity = issue.get("complexity", "medium") has_acceptance = "yes" if issue.get("acceptance") else "no" @@ -72,7 +91,7 @@ def main() -> int: has_security = "yes" if issue.get("security") else "no" deps = issue.get("deps", "None.") lines.append( - f"| {idx} | {issue['title']} | {area(labels).removeprefix('area/')} | " + f"| #{issue['number']} | {issue['title']} | {area(labels).removeprefix('area/')} | " f"{complexity} | {deps} | {has_acceptance} | {has_tests} | {has_security} |" )