WikiDeck/wikideck
3
0
Fork 1
Code Issues 8 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

Observer integration step

Browse Source
This commit is contained in:
eric
2026-10-23 10:20:58 -04:00
parent bd3d36a7e1
commit 216a419c0b
7 changed files with 161 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/real-xmr-pilot-deployment.md
+10 -4
View File
@@ -1,6 +1,6 @@
# Private pilot deployment: mock-only foundation
Status: **application and isolated PostgreSQL sandbox only**. This is not a real-XMR stack, a public node, or an approval to accept deposits. The operator already hosts a Monero full node on the network and intends the pilot to reuse it; this Compose profile neither starts nor connects to that daemon yet. Wallet-RPC, observer, deposit enrollment, and withdrawal execution are not included.
Status: **application, isolated PostgreSQL sandbox, and opt-in one-shot observer definition**. This is not a real-XMR stack, a public node, or approval to accept deposits. The operator already hosts a Monero full node and intends the pilot to reuse it; Compose does not start a daemon or connect to a Wallet-RPC gateway by default. Observer execution requires separately provisioned external services and protected files. Deposit enrollment and withdrawal execution remain unavailable.
## Start the isolated profile
@@ -16,7 +16,7 @@ To stop while preserving pilot data, run `docker compose -p wikideck-xmr-pilot -
The independent private chain uses a fixed pilot genesis time and its own deterministic chain/genesis identity. The app can run with the current sandbox features and mock balances while test cards and UI flows are exercised. Testnet and mainnet candidate identities and launch gates remain unchanged.
This stack does **not** connect to the operator's Monero daemon, create real Monero deposit addresses, scan a wallet, approve real credits, construct or relay withdrawals, or settle NFT sales against active consensus. Having a full node supplies only the blockchain daemon; it is not a Wallet-RPC service, watch-only deposit wallet, or spending wallet. Deposit enrollment and withdrawal request flags remain rejected outside the mainnet profile, and mainnet remains separately gated. Do not expose the service publicly or solicit funds.
The default stack does **not** connect to the operator's Monero daemon, create deposit addresses, scan a wallet, approve credits, construct or relay withdrawals, or settle NFT sales against active consensus. An opt-in one-shot observer service is defined below, but it cannot run without a separately provisioned watch-only Wallet-RPC gateway, external pilot custody database, and protected credentials. Having a full node supplies only the blockchain daemon; it is not Wallet-RPC, a watch-only deposit wallet, or a spending wallet. Do not expose the service publicly or solicit funds.
### Pilot custody identity and deposit reservations (schema v14)
@@ -61,7 +61,7 @@ From the pilot Compose project, run `docker compose -p wikideck-xmr-pilot -f com
Before wiring it into observer/gateway services, also verify the daemon's software version and operation policy. Mainnet is required for the real-XMR run; Stagenet rehearsal needs a separate Stagenet daemon endpoint. A daemon that is reachable on the operator's LAN is not automatically reachable from Docker containers.
Keep daemon RPC private to the pilot/operator network, bound to an appropriate private interface, and firewall-allowlisted to the pilot host. Prefer a supported authenticated TLS boundary; do not publish daemon RPC or Wallet-RPC to the Internet. The probe's HTTP option has no credentials and relies on private-network isolation; it is only for an explicitly trusted/firewalled route. Store any later gateway credentials/certificates in protected secret files, never in source, Compose literals, or browser settings. The observer should use a watch-only wallet/RPC boundary; transaction signing and spend keys remain separate and out of the app/observer. The eventual flow still needs a private Wallet-RPC gateway, observer, schema/role integration, reviewed credits, actual withdrawal execution, recovery, and active sale settlement, as described in [the implementation plan](real-xmr-pilot-plan.md).
Keep daemon RPC private to the pilot/operator network, bound to an appropriate private interface, and firewall-allowlisted to the pilot host. Prefer a supported authenticated TLS boundary; do not publish daemon RPC or Wallet-RPC to the Internet. The probe's HTTP option has no credentials and relies on private-network isolation; it is only for an explicitly trusted/firewalled route. Store gateway credentials/certificates in protected secret files, never in source, Compose literals, or browser settings. The observer must use a watch-only wallet/RPC boundary; transaction signing and spend keys remain separate and out of the app/observer. The gateway config now assigns each client-certificate fingerprint explicit roles: `observer` permits only height/address reads and bounded incoming-transfer scans; `address-allocator` permits only address reads/validation and one-subaddress creation. Keep the observer certificate separate from the allocator certificate. Neither role can invoke transaction construction, signing, relay, or sweep methods. The eventual flow still needs reviewed credits, actual withdrawal execution, recovery, and active sale settlement, as described in [the implementation plan](real-xmr-pilot-plan.md).
This probe does not establish that the node is honest or independently canonical, and `synchronized: true` is a point-in-time daemon report—not a finality guarantee or credit authorization. No deposit addresses are issued and no financial API is enabled by a successful result.
@@ -69,7 +69,13 @@ This probe does not establish that the node is honest or independently canonical
Pilot Wallet-RPC output scans are stored in separate pilot tables, not the existing mainnet-custody observation tables. The one-shot observer verifies the configured wallet fingerprint, resumes a bounded durable cursor with overlap, binds recognized outputs only to an exact registered reservation, and records unknown-wallet outputs as `unallocated` suspense observations. Replays are idempotent; missing, changed, and reappeared outputs produce append-only events for operator reorg review. This pipeline never posts a journal, creates a credit, or changes a balance.
The pilot observer role is separate from reservation/address roles and cannot read custody balances/journals or write credit records. Use `custody:db grant-pilot-monero-observer-runtime <ROLE>` with `WIKIDECK_PILOT_CUSTODY_OPERATIONS=pilot-observation-only-no-credit` after schema migration and identity initialization. Run one operator-controlled scan with `npm run monero:pilot-observe`; it requires the protected pilot observer PostgreSQL URL/CA, Mainnet Wallet-RPC config, matching mTLS gateway config, and wallet generation/fingerprint settings. `WIKIDECK_PILOT_OBSERVER_MAX_BLOCKS` (default 5000; max 100000) bounds each pass; `WIKIDECK_PILOT_OBSERVER_OVERLAP` (default 100; max 10000) requests a rescan window. Re-run manually to advance the cursor. No background service or HTTP endpoint is enabled.
The pilot observer role is separate from reservation/address roles and cannot read custody balances/journals or write credit records. Use `custody:db grant-pilot-monero-observer-runtime <ROLE>` with `WIKIDECK_PILOT_CUSTODY_OPERATIONS=pilot-observation-only-no-credit` after schema migration and identity initialization. The Compose profile `pilot-observer` runs one bounded scan and exits; invoke it with `docker compose -p wikideck-xmr-pilot -f compose.custody-pilot.yaml --profile pilot-observer run --rm pilot-observer`. It is not part of normal `up`, publishes no ports, uses a separate egress network, and mounts only explicitly supplied observer database and mTLS files read-only. Compose does not enforce outbound host allowlists: firewall policy must limit access to the configured private gateway and external observer database. Do not reuse the mock pilot app database or its credentials.
The gateway's protected JSON config uses per-certificate policies, for example `clientPolicies: [{"fingerprint":"<lowercase SHA-256 of certificate DER>","roles":["observer"]}]`. Issue a different client certificate/fingerprint to the address allocator and assign only `address-allocator`; do not give the observer certificate that role. A combined role list is only for isolated rehearsals that intentionally exercise both capabilities with one disposable identity. Neither policy includes transaction signing, transfer, relay, or sweep methods.
Provide these non-secret identity values in the local Compose environment: `WIKIDECK_PILOT_CUSTODIAN_ID`, `WIKIDECK_MONERO_WALLET_GENERATION_ID`, and `WIKIDECK_MONERO_WALLET_FINGERPRINT`. Point the following host-path variables at protected files outside the repository: `WIKIDECK_PILOT_OBSERVER_PG_URL_HOST`, `WIKIDECK_PILOT_OBSERVER_PG_CA_HOST`, `WIKIDECK_PILOT_OBSERVER_WALLET_CONFIG_HOST`, `WIKIDECK_PILOT_OBSERVER_MTLS_CONFIG_HOST`, `WIKIDECK_PILOT_OBSERVER_CLIENT_CERT_HOST`, `WIKIDECK_PILOT_OBSERVER_CLIENT_KEY_HOST`, and `WIKIDECK_PILOT_OBSERVER_GATEWAY_CA_HOST`. The mounted Wallet-RPC config must explicitly say `network: mainnet` and point to the private gateway. The mounted mTLS JSON must reference the container paths `/run/secrets/observer-client.crt`, `/run/secrets/observer-client.key`, and `/run/secrets/observer-gateway-ca.crt`; its URL must match the Wallet-RPC config. The PostgreSQL URL must use the dedicated `pilot_monero_observer` role on the distinct pilot custody database, not the app runtime, schema owner, review, reservation, or allocator role.
`WIKIDECK_PILOT_OBSERVER_MAX_BLOCKS` (default 5000; max 100000) bounds each pass; `WIKIDECK_PILOT_OBSERVER_OVERLAP` (default 100; max 10000) requests a rescan window. Re-run manually to advance the cursor. There is no background observer, public HTTP endpoint, address issuance, or credit side effect. The Compose service definition is only wiring; connectivity is not verified until an operator supplies the private files and runs the one-shot command.
### Pilot deposit review preparation (read-only, no credit)