[cephascenturion]

Summary

Docs: onboarding guide, ZK ADR, metrics reference, and escrow contract fuzzing

What was solved

#377 — feat(contract): Fuzz testing suite for escrow input validation

Add a cargo-fuzz based property/fuzz testing suite for the escrow contract's input validation, covering escrow creation inputs (amount, memo, TTL) and ZK proof verification, with committed seed corpora, CI integration running each target for 60 seconds, and local run documentation in the contract README.

Addressed:

• Changed: .github/workflows/contract.yml, app/contract/README.md, app/contract/fuzz/Cargo.toml, app/contract/fuzz/fuzz_targets/fuzz_escrow_create.rs
• Add cargo fuzz target fuzz_escrow_create that fuzzes amount, memo, and TTL inputs
• Add cargo fuzz target fuzz_proof_verify that fuzzes the ZK proof byte array
• Update .github/workflows/contract.yml to run each fuzz target for 60 seconds using -max_total_time=60

#378 — docs: Create developer onboarding guide — from clone to first payment in 15 minutes

Create docs/DEVELOPER-ONBOARDING.md, a chronological 15-minute guide taking a new contributor from git clone to a testnet payment, with expected-output snippets per step and a troubleshooting section, then link it from the README's Setup Instructions section.

Addressed:

• Changed: docs/DEVELOPER-ONBOARDING.md, docs/DEVELOPER-ONBOARDING.md, docs/DEVELOPER-ONBOARDING.md, docs/DEVELOPER-ONBOARDING.md
• Create new file docs/DEVELOPER-ONBOARDING.md
• Cover exactly these steps in order: (1) prerequisites check (Node 20, pnpm 10, Stellar testnet account), (2) clone + pnpm install, (3) copy .env.example to app/backend/.env and fill the two mandatory fields, (4) pnpm dev with expected console output, (5) fund a testnet account at laboratory.stellar.org, (6) claim a username in the running app, (7) generate a payment link, (8) send a test payment and see it in the dashboard
• Each step must include an expected output snippet (console output, URL to open, etc.)

#379 — docs: Write Architecture Decision Record for X-Ray privacy ZK scheme selection

Create a new Architecture Decision Record documenting the ZK proof scheme selection for X-Ray privacy, following the existing ADR template, and update the ADR index. The ADR will cover context, decision, alternatives, consequences, and security considerations, including proving system, circuit framework, trusted setup, and Soroban instruction cost estimates, with a link to the contract implementation issue.

Addressed:

• Changed: docs/adr/0007-xray-privacy-zk-scheme.md, docs/adr/0007-xray-privacy-zk-scheme.md, docs/adr/README.md, docs/adr/0007-xray-privacy-zk-scheme.md
• Create new ADR file at docs/adr/0007-xray-privacy-zk-scheme.md using the next available number
• Follow the structure/template in docs/adr/TEMPLATE.md
• Include sections: Context, Decision, Alternatives Considered, Consequences, Security Considerations

#380 — docs: Document all Prometheus metrics exposed by the backend with descriptions and alert thresholds

Add a Prometheus metrics reference to the backend observability docs, enumerating every metric exported via prom-client with name, type, labels, description, example PromQL, and recommended P0/P1 alert thresholds, plus a Grafana dashboard JSON, and link it from the backend README.

Addressed:

• Changed: app/backend/docs/METRICS-REFERENCE.md, app/backend/docs/grafana-dashboard.json, app/backend/README.md, docs/OBSERVABILITY-OPERATIONS.md
• Create a new section in docs/OBSERVABILITY-OPERATIONS.md or a new file docs/METRICS-REFERENCE.md listing every metric exported by the NestJS backend via prom-client.
• For each metric document: name, type (counter/gauge/histogram), labels, description, and an example Prometheus query.
• Add an alert thresholds section with recommended PromQL alert rules for P0/P1 scenarios (e.g., error rate > 1% for 5 minutes, p99 latency > 2s).

Changes

• app/contract/fuzz/Cargo.toml (create)
• docs/adr/0007-xray-privacy-zk-scheme.md (create)
• app/contract/README.md (modify)
• docs/DEVELOPER-ONBOARDING.md (create)
• app/backend/docs/METRICS-REFERENCE.md (create)
• .github/workflows/contract.yml (modify)
• app/contract/fuzz/fuzz_targets/fuzz_escrow_create.rs (create)
• docs/adr/README.md (modify)
• app/backend/README.md (modify)
• app/backend/docs/grafana-dashboard.json (create)
• docs/OBSERVABILITY-OPERATIONS.md (modify)

Approach

1. feat(contract): Fuzz testing suite for escrow input validation #377 — feat(contract): Fuzz testing suite for escrow input validation (Changed: .github/workflows/contract.yml, app/contract/README.md, app/contract/fuzz/Cargo.toml, app/contract/fuzz/fuzz_targets/fuzz_escrow_create.rs)
2. docs: Create developer onboarding guide — from clone to first payment in 15 minutes #378 — docs: Create developer onboarding guide — from clone to first payment in 15 minutes (Changed: docs/DEVELOPER-ONBOARDING.md, docs/DEVELOPER-ONBOARDING.md, docs/DEVELOPER-ONBOARDING.md, docs/DEVELOPER-ONBOARDING.md)
3. docs: Write Architecture Decision Record for X-Ray privacy ZK scheme selection #379 — docs: Write Architecture Decision Record for X-Ray privacy ZK scheme selection (Changed: docs/adr/0007-xray-privacy-zk-scheme.md, docs/adr/0007-xray-privacy-zk-scheme.md, docs/adr/README.md, docs/adr/0007-xray-privacy-zk-scheme.md)
4. docs: Document all Prometheus metrics exposed by the backend with descriptions and alert thresholds #380 — docs: Document all Prometheus metrics exposed by the backend with descriptions and alert thresholds (Changed: app/backend/docs/METRICS-REFERENCE.md, app/backend/docs/grafana-dashboard.json, app/backend/README.md, docs/OBSERVABILITY-OPERATIONS.md)

Issues

Closes #377
Closes #378
Closes #379
Closes #380

[drips-wave]

@cephascenturion Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits