README.md

---
license: apache-2.0
pretty_name: Sentinel-Witness
tags:
  - trading
  - dashboard
  - ledger
  - crypto
---

# Ledger Trading Dashboard

Phone-first PWA: Ledger hardware wallet + Coinbase/Kraken/Crypto.com, staged
dashboard → manual-approval → automated execution, driven by walk-forward-
validated grid/bracket strategy parameters (see the companion `strategy/`
Python project) with a real-time adaptive layer on top.

## What's actually tested vs. what needs your device

This was built in a sandboxed environment with no access to Coinbase/
Kraken/Crypto.com's APIs, no WebHID, no real Ledger. That shaped what
"tested" can honestly mean here:

| Module | Tested | How |
|---|---|---|
| `secureStorage.js` | Yes | Full encrypt/decrypt round trip, wrong-passphrase-fails-closed, fresh salt/IV per save — real IndexedDB via `fake-indexeddb`, not mocked |
| `gridMath.js` | Yes | Lookahead safety, capital-safety invariant, parity against the Python engine's validated $12 dead-weight case, throttle-never-hits-zero |
| `exchanges/kraken.js`, `cryptocom.js` signing | Yes | Determinism, structural correctness (output length/format), key-order invariance |
| `exchanges/coinbase.js` JWT | Partially | ES256 JWT structure and signature cryptographically verified against a generated key pair — confirms the *mechanism* is right. Does **not** confirm a real Coinbase CDP key imports cleanly; that needs your actual key |
| `tradeGate.js` tier enforcement | Yes | Every limit-rejection path, tier-gating path, and the "no unlimited option" guarantee, via a mock exchange |
| `ledger.js` | No — cannot be | Needs a real browser (WebHID) and a real device |
| Live exchange calls (balances, order placement) | No — cannot be | This sandbox's network can't reach any of the three exchanges |
| UI (`Dashboard.jsx`, `App.jsx`) | No — cannot be | Needs a real browser |

Run `npm test` to re-run everything that *can* run outside a browser.

## Setup

```
npm install
npm run dev      # local dev server
npm run build    # production build, output in dist/
```

### Exchange credentials
- **Kraken**: create an API key with Query Funds + Create/Cancel orders
  permissions (not Withdraw). Enter the key + secret in the app; they're
  encrypted with your passphrase and stored only in this browser's
  IndexedDB.
- **Crypto.com**: same shape (API key + secret), trading permissions only.
- **Coinbase**: create a CDP API key (Advanced Trade). The downloaded
  private key must be PKCS8 PEM (`-----BEGIN PRIVATE KEY-----`). If yours
  says `-----BEGIN EC PRIVATE KEY-----`, convert it first:
  `openssl pkcs8 -topk8 -nocrypt -in your-key.pem -out converted.pem`

None of these should ever have withdrawal permission. This app only ever
needs to read balances and place/cancel limit orders.

## Security model

- **Ledger**: signing happens on-device with a physical confirmation.
  This code never sees a seed phrase or private key — see `ledger.js`'s
  docstring. WebHID (required for the Ledger connection) works in Chrome/
  Edge on desktop and Android; it does **not** work in any iOS browser,
  including Safari-based ones on iPhone. On iOS, this needs a native app
  with Ledger's Bluetooth SDK instead — flagged, not built here.
- **Exchange credentials**: AES-GCM encrypted with a key derived from
  your passphrase (PBKDF2, 210k iterations), stored in this browser's
  IndexedDB. This is real protection against someone reading files off
  disk. It is **not** equivalent to a native app's OS Keychain/Keystore —
  a PWA can't reach either. See `secureStorage.js` and the in-app
  `SecurityNotice` component.
- **Trade execution guardrails**: all enforced in `tradeGate.js`, not
  just documented — automated tier refuses to start without finite,
  positive `maxPerTradeUsd` and `maxDailyTradesCount` (no unlimited
  option), both re-checked on every signal, not just at setup. Every
  execution path requires the Ledger confirmation step; there is no
  code path that skips it.

## What's genuinely not built yet

- **XRP unsigned-transaction-blob assembly.** `tradeGate.executeApprovedSignal()`
  gets all the way to calling the Ledger and reading the address, then
  throws an explicit `not_implemented` error rather than faking a
  completed trade. Turning a `{pair, price, quantity}` signal into the
  actual bytes `signXrpTransaction()` needs to sign (proper XRP Ledger
  transaction encoding, sequence numbers, fees, submission to a node)
  is real protocol work not done in this pass — flagged loudly rather
  than stubbed quietly, per this whole project's standing rule about
  silent failures being the dangerous kind.
- PWA icons (`icon-192.png`, `icon-512.png` referenced in `vite.config.js`)
  aren't generated.
- Only XRP is wired through the UI/gate end-to-end; the strategy guide
  covers DOGE too (see `src/lib/strategyGuide.js`) but the app only
  asks for one asset right now.

## Automated-tier setup

`AutomatedSetupModal.jsx` replaced the earlier `prompt()`/`alert()`
placeholder. Real form, real inline validation (mirrors
`tradeGate.js`'s own `enableAutomated()` check exactly — see
`src/lib/automatedLimits.js` — so the UI never blocks something the gate
would allow or vice versa), and a live "worst-case daily deployment"
figure (`maxPerTradeUsd × maxDailyTradesCount`, related to current USD
balance when known) so the two numbers you're locking in mean something
concrete before you confirm, not just two blank fields. Covered by
`src/lib/__tests__/automatedLimits.test.js`.

While wiring this in, found and fixed a second bug: the "Dashboard" tier
button rendered clickable while at manual/automated tier (stepping down
is deliberately always open, from any tier — see `tierNavigation.js`),
but `handleTierChange` had no branch for it, so tapping it silently did
nothing. Confirmed empirically before fixing (not assumed), and now
covered by `src/lib/__tests__/tierNavigation.test.js`, which asserts the
dashboard-tier case directly rather than just the fields it happened to
break in.

## Re-generating the strategy guide

`src/lib/strategyGuide.js` embeds a snapshot from
`recursive_strategy_optimizer.py` (the Python walk-forward optimizer, in
the companion `strategy/` project — re-run that periodically, it's
designed for it). Either replace the `BAKED_IN_GUIDE` constant with fresh
output, or host the JSON somewhere and call `refreshGuide(url)` so the
app picks up updates without a rebuild.


---

## Part of one system — each piece usable on its own

These repositories are independent instruments that also compose into a single apparatus for **building and honestly auditing trustworthy multi-intelligence systems**. Any one can be used standalone; together they form the stack:

- **Governed core** — [covenant](https://huggingface.co/Lawless1987/covenant): a self-governing multi-agent system with an ethics gate inside the transaction path.
- **Observability & provenance** — [threefold](https://huggingface.co/Lawless1987/threefold) (the L-lens layer over Jacobian Lens) and [threefold-memory](https://huggingface.co/Lawless1987/threefold-memory) (its persistent, provenance-tracked memory): every action measured and recorded under one task identity.
- **Measurement instruments** — [contradiction-probe](https://huggingface.co/Lawless1987/contradiction-probe) and [flinch-observability](https://huggingface.co/Lawless1987/flinch-observability), with the session records [flinch-record](https://huggingface.co/Lawless1987/flinch-record) and [grokflinch](https://huggingface.co/Lawless1987/grokflinch): preregistered, blind-scored tests of AI behaviour that embody the covenant's rule — *investigate a signal, never convict on one*.
- **Neuromorphic research** — [spiking-experiments](https://huggingface.co/Lawless1987/spiking-experiments): from-scratch spiking-network experiments with the pass/fail bar declared before each run.
- **Ledger surface** — [Sentinel-Witness](https://huggingface.co/Lawless1987/Sentinel-Witness): the trading / ledger dashboard.

**This repository's place in it:** the ledger / trading-dashboard surface.