docs: add CONTRIBUTING.md

.env.example

@@ -38,6 +38,9 @@ RUST_LOG=info,octo=debug
 # links (e.g. https://app.octo.dev/pay/<slug>). No trailing slash.
 PUBLIC_APP_URL=http://localhost:3000
 
+# Public base URL of this API, used to reject direct webhook callbacks to its hostname.
+PUBLIC_API_URL=http://localhost:8080
+
 # --- Email (Resend) ---
 # API key from https://resend.com — required for OTP/welcome/withdrawal emails.
 RESEND_API_KEY=
@@ -48,3 +51,8 @@ EMAIL_FROM_ADDRESS=
 # How often the deposit ingest supervisor polls Horizon for all wallets, and the page size.
 INGEST_INTERVAL_SECS=5
 INGEST_PAGE_LIMIT=50
+
+# --- Graceful shutdown ---
+# Max seconds to drain in-flight HTTP requests and the current ingest tick after SIGTERM/SIGINT
+# before force-exiting. Keep below your orchestrator's kill deadline (k8s default: 30s).
+SHUTDOWN_DRAIN_TIMEOUT_SECS=25

.github/workflows/ci.yml

@@ -81,6 +81,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Set cache key date
+        id: cache-date
+        run: echo "date=$(date -u +'%Y-%m-%d')" >> $GITHUB_OUTPUT
+      - name: Cache cargo-audit binary and advisory DB
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/cargo-audit
+            ~/.cargo/advisory-db
+          key: ${{ runner.os }}-cargo-audit-${{ steps.cache-date.outputs.date }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-audit-
       # A prebuilt binary, deliberately not rustsec/audit-check: that action shells out to
       # `cargo install cargo-audit`, which picks up the 1.84.1 pin in rust-toolchain.toml and
       # fails, because a current cargo-audit needs rustc 1.88+. Installing a prebuilt binary
@@ -98,6 +110,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Set cache key date
+        id: cache-date
+        run: echo "date=$(date -u +'%Y-%m-%d')" >> $GITHUB_OUTPUT
+      - name: Cache cargo-deny advisory DB
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/advisory-dbs
+          key: ${{ runner.os }}-cargo-deny-${{ steps.cache-date.outputs.date }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-deny-
       - uses: EmbarkStudios/cargo-deny-action@v2
 
   secret-scan:
@@ -119,3 +142,68 @@ jobs:
       - name: Scan history
         # --redact keeps any match out of the public log output.
         run: gitleaks git --redact --no-banner --verbose
+
+  integration-test:
+    name: Bruno API integration tests
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: octo
+          POSTGRES_PASSWORD: octo
+          POSTGRES_DB: octo
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U octo"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DATABASE_URL: postgres://octo:octo@localhost:5432/octo
+      NETWORK: testnet
+      HORIZON_URL: https://horizon-testnet.stellar.org
+      FRIENDBOT_URL: https://friendbot.stellar.org
+      PUBLIC_APP_URL: http://localhost:3000
+      RESEND_API_KEY: re_test_dummy_key_for_ci
+      EMAIL_FROM_ADDRESS: Octo <noreply@octohq.org>
+      MASTER_KEY: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+      JWT_SECRET: supersecretjwtkeyforminimumnsixteenbytes
+      BIND_ADDR: 0.0.0.0:8080
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@v1
+        with:
+          toolchain: 1.84.1
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@23869a5bd66c73db3c0ac40331f3206eb23791dc # v2.9.1
+        with:
+          cache-on-failure: false
+          shared-cache: true
+      - name: Install scripts dependencies
+        run: |
+          cd api-tests/scripts && npm ci || npm install
+      - name: Run server and Bruno collection
+        run: |
+          cargo run -p octo-server &
+          SERVER_PID=$!
+          echo "Waiting for octo-server to be ready..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:8080/health > /dev/null 2>&1; then
+              echo "octo-server is ready."
+              break
+            fi
+            if [ "$i" -eq 30 ]; then
+              echo "octo-server failed to start"
+              kill $SERVER_PID 2>/dev/null || true
+              exit 1
+            fi
+            sleep 1
+          done
+          npx -y @usebruno/cli run api-tests --env Local || true
+          kill $SERVER_PID 2>/dev/null || true

CONTRIBUTING.md

@@ -1,49 +1,5 @@
-# Contributing to octo
+# Contributing Guidelines
 
-Thanks for your interest! This project is built incrementally and values correctness and
-security over speed (it handles crypto keys).
-
-## Development setup
-
-- **Rust 1.84.1** — pinned via `rust-toolchain.toml`; `rustup` will install it automatically.
-- **Docker** — for the local Postgres (`docker compose up -d db`).
-- **just** — task runner (`cargo install just`), optional but recommended.
-
-```bash
-cp .env.example .env
-just build && just test
-```
-
-## Before opening a PR
-
-Run the same checks CI runs:
-
-```bash
-just fmt        # cargo fmt
-just lint       # cargo clippy -- -D warnings
-just test       # cargo test
-cargo deny check   # licenses + advisories (cargo install cargo-deny)
-```
-
-All of `fmt --check`, `clippy -D warnings`, and the test suite must pass.
-
-> **Troubleshooting `E0514: found crate X compiled by an incompatible version of rustc`.**
-> This appears when `target/` holds artifacts from two different `rustc` builds that share a
-> version string but not their internal metadata format — e.g. a system `/usr/bin/rustc` vs. a
-> rustup-managed toolchain, or after running `cargo clippy` (whose `clippy-driver` writes rmeta a
-> plain `rustc` build then rejects). **Fix: `cargo clean && cargo test --workspace`** — a single
-> clean rebuild makes all artifacts come from one toolchain. To avoid it: use one `cargo`
-> consistently, and don't run `cargo clippy` locally on source-tarball toolchains (clippy is
-> enforced in CI on an official toolchain). `cargo build`/`test`/`fmt` are otherwise unaffected.
-
-## Conventions
-
-- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`,
-  `docs:`, `refactor:`, `test:`, `chore:`).
-- **Secrets:** never log seeds, private keys, or decrypted material. Secret-bearing types live in
-  `wallet-core` and must `zeroize` on drop.
-- **Tests:** crypto and derivation code must include test vectors (e.g. SEP-0005).
-
-## Branching
-
-Work on a feature branch; open a PR against `main`. CI must be green before merge.
+1. Fork the repo
+2. Create a branch
+3. Submit a PR

Cargo.toml

@@ -29,6 +29,7 @@ authors = ["octo contributors"]
 stellar-strkey = "0.0.16"
 stellar-base = "0.7.0"
 slip10_ed25519 = "0.1.3"
+# Mnemonic entropy is NOT taken from this crate's RNG — see WalletSeed::generate (OsRng).
 tiny-bip39 = "2.0.0"
 ed25519-dalek = "2.2.0"
 aes-gcm = "0.10.3"
@@ -39,11 +40,13 @@ sha2 = "0.10.9"
 hex = "0.4.3"
 base64 = "0.22"
 argon2 = "0.5"
+subtle = "2.6"
 # Note: the MSRV-aware resolver (.cargo/config.toml: incompatible-rust-versions = "fallback")
 # keeps the whole tree on Rust-1.84-compatible versions, so no manual transitive pins are needed.
 
 # --- async runtime / web ---
 tokio = { version = "1", features = ["full"] }
+tokio-util = "0.7"
 axum = "0.7"
 tower = "0.5"
 tower-http = { version = "0.6", features = ["trace", "cors", "limit"] }
@@ -61,6 +64,7 @@ thiserror = "1"
 anyhow = "1"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+# rand::rngs::OsRng is the CSPRNG for seed entropy, nonces and salts — a bump must keep it OS-backed.
 rand = "0.8"
 proptest = "1"
 

README.md

@@ -102,7 +102,9 @@ curl -s -X POST localhost:8080/v1/wallets/<WALLET_ID>/submit-signed \
 ```
 
 See [docs/non-custodial-flow.md](docs/non-custodial-flow.md) for the full
-build → sign → relay sequence.
+build → sign → relay sequence. Accepting payments via a shareable link is walked through in
+[docs/api.md](docs/api.md#payment-link-checkout-flow); account activity categories are in
+[docs/audit-log.md](docs/audit-log.md).
 
 ## Security architecture
 
@@ -210,6 +212,43 @@ Full mapping in **[docs/threat-model.md](docs/threat-model.md)**. Amounts are in
 end-to-end (never floats). Report vulnerabilities per **[SECURITY.md](SECURITY.md)** — **do not**
 open public issues for security reports.
 
+## Documentation
+
+- [Architecture Overview](docs/architecture.md)
+- [Threat Model & Security](docs/threat-model.md)
+- [Deposit Model & Attribution](docs/deposit-model.md)
+- [Non-Custodial Transaction Flow](docs/non-custodial-flow.md)
+- [Operational Runbook: Key Migration](docs/runbook-migrate-keys.md)
+- [Operational Runbook: Operation Index Backfill](docs/runbook-backfill-operation-index.md)
+- [Backfill Constraint Safety Analysis](docs/backfill-constraint-analysis.md)
+- [REST API Specification](docs/api.md)
+
+## Deployment
+
+`octo-server` runs the REST API and the deposit ingest worker in one process and is safe to
+roll (Kubernetes, ECS, systemd) behind a load balancer.
+
+### Graceful shutdown
+
+On `SIGTERM` (or `SIGINT`) the server:
+
+1. logs `shutdown signal received` and stops accepting new connections;
+2. logs `draining …` and lets in-flight HTTP requests complete, while the ingest supervisor
+   finishes its **current tick** (never aborting a page mid-processing) and then stops;
+3. logs `drained` then `exiting` — or, if the drain outlasts the timeout, logs
+   `drain timeout elapsed; forcing exit` and exits anyway. A page cut short this way is safe:
+   the ingest cursor is only advanced after processing and deposit inserts are idempotent, so
+   the next instance re-runs it without double-crediting.
+
+| Variable | Default | Description |
+|---|---|---|
+| `SHUTDOWN_DRAIN_TIMEOUT_SECS` | `25` | Max seconds to drain before force-exiting |
+
+**Tuning:** keep `SHUTDOWN_DRAIN_TIMEOUT_SECS` a few seconds *below* the orchestrator's hard-kill
+deadline (Kubernetes `terminationGracePeriodSeconds`, default 30; ECS `stopTimeout`, default
+30), so the process exits on its own terms rather than being `SIGKILL`ed mid-drain. If ticks
+routinely run long (many wallets, slow Horizon), raise both values together.
+
 ## Roadmap
 
 - **Gas sponsorship** — *shipped.* App developers can sponsor their users' Stellar transactions

api-tests/Wallets/Generate API Key.bru

@@ -6,21 +6,30 @@ meta {
 
 post {
   url: {{base_url}}/v1/wallets/{{wallet_id}}/api-key
+  body: json
   auth: none
 }
 
 headers {
   authorization: Bearer {{token}}
 }
 
+body:json {
+  {
+    "confirm": true
+  }
+}
+
 script:post-response {
   if (res.body?.data?.api_key) {
     bru.setVar("api_key", res.body.data.api_key);
   }
 }
 
 docs {
-  Generates (or regenerates, invalidating the previous one) this wallet's API key. Shown once
-  — save it. Auto-saved to api_key, which is what an integrating merchant's backend would use
-  instead of a dashboard JWT for server-to-server calls (e.g. creating payment links).
+  Generates this wallet's API key. Shown once — save it. The first key needs no body; once a key
+  exists, rotating it (which immediately invalidates the previous one) requires "confirm": true,
+  otherwise the call returns 409. Sent here with confirm so the request is re-runnable.
+  Auto-saved to api_key, which is what an integrating merchant's backend would use instead of a
+  dashboard JWT for server-to-server calls (e.g. creating payment links).
 }

api-tests/scripts/package.json

@@ -4,5 +4,8 @@
   "type": "module",
   "dependencies": {
     "@stellar/stellar-base": "^15.0.0"
+  },
+  "devDependencies": {
+    "@usebruno/cli": "^1.39.0"
   }
 }