docs(contracts): add Rust doc comments to all public contract functions by pauljacobb · Pull Request #3 · pauljacobb/solarproof

pauljacobb · 2026-05-31T05:06:28Z

Summary

Ensures every public function across all three Soroban contracts has complete /// doc comments covering arguments, authorization, panics, errors, and example invocations.

Changes

apps/contracts/energy_token/src/lib.rs — enhanced balance(), total_supply()
apps/contracts/audit_registry/src/lib.rs — enhanced anchor(), verify(), api_signer(), admin()
apps/contracts/community_governance/src/lib.rs — enhanced set_quorum_bps(), get_quorum_bps(), set_threshold_bps(), get_threshold_bps(), pending_upgrade(), get_execution_timelock(), proposal_count()

Acceptance criteria

All public functions in all three contracts have /// doc comments
cargo doc generates without warnings (no undocumented public items)
Panics and error conditions documented
Example invocations added where helpful

Closes AnnabelJoe#319

- docs/runbooks/contract-deployment.md: testnet/mainnet deploy, verify, rollback - docs/runbooks/meter-key-rotation.md: scheduled and emergency key rotation - docs/runbooks/failed-mint-investigation.md: diagnose and retry failed mints - docs/runbooks/incident-response.md: triage, containment, resolution, postmortem - docs/runbooks/README.md: index of all runbooks Closes AnnabelJoe#315

…nnabelJoe#260) - WebSocket connection established on dashboard load - Chart updates automatically when new meter readings arrive - Graceful fallback to polling (30s interval) if WebSocket unavailable - Connection status indicator: Live / Polling / Offline / Connecting Closes AnnabelJoe#260

AnnabelJoe#319) - energy_token: enhanced balance() and total_supply() with examples - audit_registry: enhanced anchor(), verify(), api_signer(), admin() with full Arguments/Errors/Example sections - community_governance: enhanced set_quorum_bps, get_quorum_bps, set_threshold_bps, get_threshold_bps, pending_upgrade, get_execution_timelock, proposal_count with Panics/Arguments/Examples All public functions now have /// doc comments with Panics, Arguments, Authorization, and example invocations where applicable. Closes AnnabelJoe#319

- Add docs/USER_GUIDE.md covering all acceptance criteria: wallet connection, dashboard overview, meter readings, certificates (view + retire), governance (view/vote/create), and the public verifier - Include screenshot placeholders for each step - Link guide from dashboard page header via BookOpen icon

…oe#274) - Enable RLS on cooperatives, meters, readings, certificates - Members can only read rows belonging to their cooperative (cooperative_id sourced from JWT app_metadata) - Readings isolated via meter → cooperative join - Admin JWT role bypasses all policies for support operations - Policy tester SQL covers member isolation + admin bypass cases

- Add CertificateListSkeleton component to skeleton.tsx - Create /certificates page with skeleton loader during data fetch - Add GET /api/certificates list endpoint - Dashboard and verify pages already had skeletons (StatCardSkeleton, ChartSkeleton, TableRowSkeleton, SectionSkeleton) Closes AnnabelJoe#255

- Runs cargo fmt, clippy, and cargo test --all on every PR - Scoped to apps/contracts/** path changes - Uses Swatinem/rust-cache for faster Rust compilation - Fails PR merge if any check fails Closes AnnabelJoe#287

…es (AnnabelJoe#331) - Add cargo-mutants config targeting audit_registry and energy_token with 70% minimum score threshold - Add Stryker config for packages/stellar with vitest runner and 70% break threshold - Add vitest setup and unit tests for kwhToStroops, stroopsToKwh, NETWORKS, CONTRACT_IDS - Add weekly scheduled GH Actions workflow (Sunday 02:00 UTC) with manual dispatch and per-target filtering - Add docs/MUTATION_TESTING.md with local run instructions, thresholds, scope, and result interpretation guide Closes AnnabelJoe#331

- POST /api/certificates/:id/retire calls energy_token burn on Soroban - Records retirement timestamp, beneficiary, and retire_tx_hash in certificates table - Returns 409 if certificate already retired - Emits retirement_events record for audit log - Add migration 005: retire_tx_hash column + retirement_events table - Update database.types.ts with new fields Closes AnnabelJoe#270

…edge-case tests - initialize() now stores the passed quorum param instead of hardcoded default - set_quorum_bps / set_threshold_bps now verify caller == stored admin - Added tests: initialize configures quorum, zero quorum rejected, exactly-at-quorum passes, one-below-quorum expires, admin update paths, non-admin rejection

- Export verifyReadingSignature() from crypto.ts (wraps @noble/ed25519 verifyAsync, never throws — returns false on malformed input) - Tests cover: valid sig, invalid sig, tampered payload, wrong key, malformed sig bytes, malformed pubkey, hash determinism, hash sensitivity

…ersion header - middleware: change unversioned redirect from 308 to 301 (Moved Permanently) - middleware: inject API-Version: v1 header on all /api/* responses - openapi.yaml: document /api/v1/ canonical paths, legacy 301 redirect paths, API-Version response header component, and versioning policy in description

- ci.yml: add image-scan job (runs after web job) - builds Docker image from apps/web/Dockerfile - scans with aquasecurity/trivy-action@0.28.0 - exit-code 1 blocks image promotion on CRITICAL CVEs - uploads SARIF as CI artifact (30-day retention) - uploads SARIF to GitHub Security tab - Dockerfile: add comment guiding digest pinning procedure

- Composite index on readings(meter_id, timestamp) - Composite index on certificates(status, created_at) - Index on audit_anchors(tx_hash) - Rollback script included

- deploy-production.yml: deploys to Vercel on every main merge only after CI (lint/type-check/test/build/contracts) passes - preview.yml: gate PR preview deploys on CI passing - Deployment URL written to job summary and GitHub environment

dashboard/page.tsx: - Remove 3 stray </SectionErrorBoundary> closing tags with no opening match - Fix 2 unclosed JSX comments {/* ... */} missing closing brace verify/page.tsx: - Remove duplicate Row function fragment dangling after closing brace - Add missing Section component - Import and wire useToast hook to replace undefined pushToast calls - Guard result?.meter_proof null access

- Add 'action' field to FormState and EMPTY defaults - Validate proposed_action is required - Render Proposed action input above voting deadline - Matches acceptance criteria: title, description, voting deadline, proposed action

…#340) - X-Frame-Options: DENY - X-Content-Type-Options: nosniff - Referrer-Policy: strict-origin-when-cross-origin - Permissions-Policy restricts camera, mic, geolocation, payment, usb

) - Nonce-based CSP via middleware (no unsafe-inline/unsafe-eval for scripts) - Restricts connect-src to Supabase and Stellar endpoints - frame-ancestors: none prevents clickjacking - CSP violations reported to /api/csp-report endpoint

- license-checker runs in CI on every push/PR - Approved license list in .license-checker.json (MIT, Apache-2.0, BSD, ISC, etc.) - CI fails on any unapproved license (GPL and other copyleft blocked)

…belJoe#341) - audit_logs table: id, timestamp, actor, action, resource, resource_id, ip, metadata - Append-only: UPDATE/DELETE revoked at DB level - writeAuditLog() utility in src/lib/audit.ts - readings route logs: reading.submitted, reading.anchored, certificate.minted - Admin API: GET /api/admin/audit-logs (paginated, service_role only) - Supabase migration: supabase/migrations/20260601000000_create_audit_logs.sql

- POST /api/certificates/:id/transfer with Stellar address validation - transferCertificate() in stellar.ts using SEP-41 transfer call - Audit log entry for certificate.transfer action - TransferModal component matching RetireModal pattern - Transfer button added to certificates dashboard table - v1 redirect at /api/v1/certificates/:id/transfer

- createMockFreighter() / installMockFreighter() / uninstallMockFreighter() utilities in src/tests/mock-freighter.ts - Supports connection, signing, disconnection, requiresAccess flag - wallet.test.ts covers connect, disconnect, session restore, revoked session, missing extension, and production isolation - vitest config updated to run wallet tests in jsdom environment

- Failed mint triggers tracer-sim diagnosis via /replay endpoint - Diagnosis result stored on reading record and matches returned value - TRACER_SIM_URL unset returns TRACER_SIM_UNAVAILABLE stub gracefully - HTTP error (503), network failure (ECONNREFUSED), and timeout all return REPLAY_ERROR without throwing - Partial tracer-sim responses filled with sensible defaults - Mock tracer-sim via vi.fn() — no real service required in CI

- buildIRecXml() in src/lib/irec-xml.ts maps certificate fields to I-REC Standard v3 XML including on-chain AnchorProof extension - GET /api/certificates/:id/irec-export returns XML with Content-Disposition: attachment for direct download - v1 redirect at /api/v1/certificates/:id/irec-export - I-REC export button added to certificates dashboard table - XML escaping prevents injection via certificate/meter data

…d public verifier - dashboard.spec.ts: wallet-connected and connect-prompt flows via Freighter mock - certificate.spec.ts: certificate detail page with Supabase route interception + 404 case - playwright.yml: CI workflow running against staging, uploads screenshots on failure - playwright.config.ts: support BASE_URL env var for staging; skip local server when remote

- supabase/config.toml: jwt_expiry 3600→900 (15 min access tokens) - refresh_token_rotation_enabled=true, reuse_interval=10s - migration: revoked_tokens table with JTI primary key + auto-expiry - auth.ts: revokeToken() helper + revocation-list check in requireAuth() - logout route: revokes access token JTI before signing out

- middleware.ts: 301 redirect HTTP→HTTPS in production (x-forwarded-proto check) - middleware matcher: expanded to all routes (excl. static assets) so redirect fires on page requests, not just API calls - next.config.ts: Strict-Transport-Security max-age=31536000; includeSubDomains; preload plus X-Content-Type-Options, X-Frame-Options, Referrer-Policy on all routes - Submit domain to HSTS preload list at https://hstspreload.org after deploy

- GET /api/v1/verify/:certificateId returns full chain of custody - No authentication required (security: []) - Response includes meter ID, reading, signature, anchor tx, certificate, retirement status - Rate limited (60 req/min per IP via middleware) - Documented in OpenAPI spec with 200/400/404/429 responses - v1 route re-exports from existing /api/verify/[id] handler Closes AnnabelJoe#352

- docs/security/pentest-scope.md: defines in-scope targets (web app, API, auth, webhooks), out-of-scope (Stellar network), methodology (OWASP Top 10 + API Security Top 10), tester requirements, and timeline - docs/security/pentest-report-2026-07.md: placeholder for final report to be filled after engagement Closes AnnabelJoe#342

feat: add pentest scope and report placeholder (AnnabelJoe#342)

…ic-verify-api feat: add public v1 verify API and OpenAPI spec (AnnabelJoe#352)

…fer-wallet-tracer-irec Feature/issues transfer wallet tracer irec

fix(security): implement audit logging for sensitive operations

…pliance fix(ci): add dependency license compliance check

fix(security): implement CSP headers for Next.js web app

…aders fix(security): add security headers to all HTTP responses

Jobsunday

Sundayjob

…-retirement feat: implement certificate retirement API endpoint

feat(security): add RLS policies for multi-tenant isolation (AnnabelJoe#274)

…n-testing feat(testing): add mutation testing for Rust contracts and TS utiliti…

docs: add user guide for web dashboard (closes AnnabelJoe#317)

…s-ci ci: add dedicated Contracts CI workflow (AnnabelJoe#287)

…letons feat: add loading skeletons for async data fetches (AnnabelJoe#255)

…nbooks-315 docs: add operational runbooks

…hart-websocket feat(web): real-time energy chart with WebSocket + polling fallback


 const withNextIntl = createNextIntlPlugin('./src/i18n.ts')

+const securityHeaders = [


+  },
+]
+
+const securityHeaders = [


+ * Tests for useWallet hook using the mock Freighter wallet.
+ * Runs headlessly in CI — no browser extension required.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'


github-actions · 2026-06-03T06:02:18Z

✅ cargo audit

�[1m�[32m    Updating�[0m crates.io index
�[1m�[32m     Locking�[0m 188 packages to latest compatible versions
�[1m�[36m      Adding�[0m arbitrary v1.3.2 �[1m�[33m(available: v1.4.2)�[0m
�[1m�[36m      Adding�[0m crypto-common v0.1.6 �[1m�[33m(available: v0.1.7)�[0m
�[1m�[36m      Adding�[0m derive_arbitrary v1.3.2 �[1m�[33m(available: v1.4.2)�[0m
�[1m�[36m      Adding�[0m soroban-builtin-sdk-macros v23.0.1 �[1m�[33m(available: v23.0.2)�[0m
�[1m�[36m      Adding�[0m soroban-env-common v23.0.1 �[1m�[33m(available: v23.0.2)�[0m
�[1m�[36m      Adding�[0m soroban-env-guest v23.0.1 �[1m�[33m(available: v23.0.2)�[0m
�[1m�[36m      Adding�[0m soroban-env-host v23.0.1 �[1m�[33m(available: v23.0.2)�[0m
�[1m�[36m      Adding�[0m soroban-env-macros v23.0.1 �[1m�[33m(available: v23.0.2)�[0m
�[1m�[36m      Adding�[0m soroban-sdk v23.5.3 �[1m�[33m(available: v25.3.0)�[0m
�[0m�[0m�[1m�[32m    Fetching�[0m advisory database from `https://github.com/RustSec/advisory-db.git`
�[0m�[0m�[1m�[32m      Loaded�[0m 1102 security advisories (from /home/runner/.cargo/advisory-db)
�[0m�[0m�[1m�[32m    Updating�[0m crates.io index
�[0m�[0m�[1m�[32m    Scanning�[0m Cargo.lock for vulnerabilities (192 crate dependencies)
�[0m�[0m�[1m�[33mCrate:    �[0m derivative
�[0m�[0m�[1m�[33mVersion:  �[0m 2.2.0
�[0m�[0m�[1m�[33mWarning:  �[0m unmaintained
�[0m�[0m�[1m�[33mTitle:    �[0m `derivative` is unmaintained; consider using an alternative
�[0m�[0m�[1m�[33mDate:     �[0m 2024-06-26
�[0m�[0m�[1m�[33mID:       �[0m RUSTSEC-2024-0388
�[0m�[0m�[1m�[33mURL:      �[0m https://rustsec.org/advisories/RUSTSEC-2024-0388
�[0m�[0m�[1m�[33mDependency tree:
�[0mderivative 2.2.0
├── ark-poly 0.4.2
│   └── ark-ec 0.4.2
│       ├── soroban-env-host 23.0.1
│       │   ├── soroban-sdk 23.5.3
│       │   │   ├── multisig-admin 1.0.0
│       │   │   ├── energy-token 1.0.0
│       │   │   ├── community-governance 1.0.0
│       │   │   └── audit-registry 1.0.0
│       │   └── soroban-ledger-snapshot 23.5.3
│       │       └── soroban-sdk 23.5.3
│       └── ark-bls12-381 0.4.0
│           └── soroban-env-host 23.0.1
├── ark-ff 0.4.2
│   ├── soroban-env-host 23.0.1
│   ├── ark-poly 0.4.2
│   ├── ark-ec 0.4.2
│   └── ark-bls12-381 0.4.0
└── ark-ec 0.4.2

�[0m�[0m�[1m�[33mCrate:    �[0m paste
�[0m�[0m�[1m�[33mVersion:  �[0m 1.0.15
�[0m�[0m�[1m�[33mWarning:  �[0m unmaintained
�[0m�[0m�[1m�[33mTitle:    �[0m paste - no longer maintained
�[0m�[0m�[1m�[33mDate:     �[0m 2024-10-07
�[0m�[0m�[1m�[33mID:       �[0m RUSTSEC-2024-0436
�[0m�[0m�[1m�[33mURL:      �[0m https://rustsec.org/advisories/RUSTSEC-2024-0436
�[0m�[0m�[1m�[33mDependency tree:
�[0mpaste 1.0.15
├── wasmi_core 0.13.0
│   └── soroban-wasmi 0.31.1-soroban.20.0.1
│       ├── soroban-env-host 23.0.1
│       │   ├── soroban-sdk 23.5.3
│       │   │   ├── multisig-admin 1.0.0
│       │   │   ├── energy-token 1.0.0
│       │   │   ├── community-governance 1.0.0
│       │   │   └── audit-registry 1.0.0
│       │   └── soroban-ledger-snapshot 23.5.3
│       │       └── soroban-sdk 23.5.3
│       └── soroban-env-common 23.0.1
│           ├── soroban-sdk-macros 23.5.3
│           │   └── soroban-sdk 23.5.3
│           ├── soroban-ledger-snapshot 23.5.3
│           ├── soroban-env-host 23.0.1
│           └── soroban-env-guest 23.0.1
│               └── soroban-sdk 23.5.3
└── ark-ff 0.4.2
    ├── soroban-env-host 23.0.1
    ├── ark-poly 0.4.2
    │   └── ark-ec 0.4.2
    │       ├── soroban-env-host 23.0.1
    │       └── ark-bls12-381 0.4.0
    │           └── soroban-env-host 23.0.1
    ├── ark-ec 0.4.2
    └── ark-bls12-381 0.4.0

�[0m�[0m�[1m�[33mwarning:�[0m 2 allowed warnings found

devnWisdom and others added 30 commits May 29, 2026 12:17

ci: add dedicated Contracts CI workflow (AnnabelJoe#287)

b1d6e5f

- Runs cargo fmt, clippy, and cargo test --all on every PR - Scoped to apps/contracts/** path changes - Uses Swatinem/rust-cache for faster Rust compilation - Fails PR merge if any check fails Closes AnnabelJoe#287

feat(db): add perf indexes on readings, certificates, audit_anchors

7e37584

- Composite index on readings(meter_id, timestamp) - Composite index on certificates(status, created_at) - Index on audit_anchors(tx_hash) - Rollback script included

fix(security): add security headers to all HTTP responses (AnnabelJoe…

1d6db6b

…#340) - X-Frame-Options: DENY - X-Content-Type-Options: nosniff - Referrer-Policy: strict-origin-when-cross-origin - Permissions-Policy restricts camera, mic, geolocation, payment, usb

fix(ci): add dependency license compliance check (AnnabelJoe#344)

ab4b39e

- license-checker runs in CI on every push/PR - Approved license list in .license-checker.json (MIT, Apache-2.0, BSD, ISC, etc.) - CI fails on any unapproved license (GPL and other copyleft blocked)

AnnabelJoe added 26 commits June 3, 2026 06:18

Merge pull request AnnabelJoe#438 from Sammy-Samy/feat/issue-342-pentest

315cb59

feat: add pentest scope and report placeholder (AnnabelJoe#342)

Merge pull request AnnabelJoe#437 from Sammy-Samy/feat/issue-352-publ…

c74344f

…ic-verify-api feat: add public v1 verify API and OpenAPI spec (AnnabelJoe#352)

Merge branch 'main' into feature/issues-transfer-wallet-tracer-irec

1cb7897

Merge pull request AnnabelJoe#436 from jhayniffy/feature/issues-trans…

049b764

…fer-wallet-tracer-irec Feature/issues transfer wallet tracer irec

Merge branch 'main' into fix/341-audit-logging

1b86703

Merge pull request AnnabelJoe#435 from JosephOnuh/fix/341-audit-logging

4c6cc64

fix(security): implement audit logging for sensitive operations

Merge pull request AnnabelJoe#434 from JosephOnuh/fix/344-license-com…

b89dd7e

…pliance fix(ci): add dependency license compliance check

Merge branch 'main' into fix/333-csp-headers

7367043

Merge pull request AnnabelJoe#433 from JosephOnuh/fix/333-csp-headers

abd9139

fix(security): implement CSP headers for Next.js web app

Merge branch 'main' into fix/340-security-headers

2019cd8

Merge pull request AnnabelJoe#432 from JosephOnuh/fix/340-security-he…

e061c41

…aders fix(security): add security headers to all HTTP responses

Merge pull request AnnabelJoe#431 from josunday002/jobsunday

578c482

Jobsunday

Merge pull request AnnabelJoe#430 from sundayjob996/sundayjob

ac14fb9

Sundayjob

Merge branch 'main' into feat/270-certificate-retirement

d279de3

Merge pull request AnnabelJoe#429 from devAgatha/feat/270-certificate…

455bc44

…-retirement feat: implement certificate retirement API endpoint

Merge pull request AnnabelJoe#420 from Magada06/feature/274-rls-policies

b20cb8e

feat(security): add RLS policies for multi-tenant isolation (AnnabelJoe#274)

Merge branch 'main' into issue-331-mutation-testing

c4c4466

Merge pull request AnnabelJoe#425 from Philzwrist07/issue-331-mutatio…

cecac18

…n-testing feat(testing): add mutation testing for Rust contracts and TS utiliti…

Merge branch 'main' into docs/317-user-guide

ca0a76d

Merge pull request AnnabelJoe#419 from Magada06/docs/317-user-guide

4f6c85c

docs: add user guide for web dashboard (closes AnnabelJoe#317)

Merge pull request AnnabelJoe#422 from Philzwrist07/feat/287-contract…

acdb9b2

…s-ci ci: add dedicated Contracts CI workflow (AnnabelJoe#287)

Merge branch 'main' into issue-255-loading-skeletons

20f951f

Merge pull request AnnabelJoe#421 from Magada06/issue-255-loading-ske…

d9a528d

…letons feat: add loading skeletons for async data fetches (AnnabelJoe#255)

Merge pull request AnnabelJoe#389 from devnWisdom/docs/operational-ru…

2b0a164

…nbooks-315 docs: add operational runbooks

Merge pull request AnnabelJoe#416 from pauljacobb/feat/260-realtime-c…

7a94632

…hart-websocket feat(web): real-time energy chart with WebSocket + polling fallback

Merge branch 'main' into docs/319-rust-doc-comments

6be6abf

AnnabelJoe had a problem deploying to staging June 3, 2026 05:59 — with GitHub Actions Failure

AnnabelJoe had a problem deploying to testnet June 3, 2026 05:59 — with GitHub Actions Failure

github-advanced-security AI found potential problems Jun 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(contracts): add Rust doc comments to all public contract functions#3

docs(contracts): add Rust doc comments to all public contract functions#3
pauljacobb wants to merge 90 commits into
mainfrom
docs/319-rust-doc-comments

pauljacobb commented May 31, 2026

Uh oh!

github-actions Bot commented Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

16 participants


		const withNextIntl = createNextIntlPlugin('./src/i18n.ts')

		const securityHeaders = [

Conversation

pauljacobb commented May 31, 2026

Summary

Changes

Acceptance criteria

Uh oh!

github-actions Bot commented Jun 3, 2026

✅ cargo audit

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

16 participants