Nym linear

AGENTS.md

@@ -131,3 +131,10 @@ without losing meaning, the "so" was decorative. Delete it.
 ### Tooling
 
 - No heredocs (<< EOF, << 'EOF') in bash or other shell scripts. They're hard to read, break on escaping, and bury content that should be its own file. Use a real file, a templating step, or printf with explicit lines instead.
+
+## Pending plans
+
+Coordinated work ready for implementation lives in `docs/agents/`.
+Current: `docs/agents/nym-diagnostics-plan.md`, the Connection Doctor
+debug APK for Nym connectivity triage (issue #1221) and the pin
+collaboration protocol for agents updating the zingolib pin.

App.tsx

@@ -130,7 +130,7 @@ export const basicTheme: ThemeType = {
 
 const Stack = createStackNavigator<AppStackParamList>();
 
-export const navigationRef = createNavigationContainerRef();
+const navigationRef = createNavigationContainerRef();
 
 const App: React.FunctionComponent = () => {
   const [theme, setTheme] = useState<ThemeType>(advancedTheme);

CONTEXT.md

@@ -55,8 +55,8 @@ The group of parts broadcast together in one window. UI-facing term.
 _Avoid_: bucket (API-internal), shipment
 
 **Window**:
-One 144-block (3h) anchor-height bucket during which a batch may be sent.
-UI-facing term.
+One bucket-modulus span of anchor heights (144 blocks, ~3h provisionally)
+during which a batch may be sent. UI-facing term.
 _Avoid_: bucket, epoch
 
 **Boundary**:
@@ -65,10 +65,10 @@ anchors to. Sharing one anchor is what keeps a send free of per-wallet timing
 information. A window can only carry notes that already existed at its
 boundary, so a batch of freshly split notes waits for the next one.
 
-**Cadence**:
-How many parts share each window (`per_bucket`). Chosen once, after splitting
-completes and before any part is signed; only re-buckets existing parts, never
-re-cuts notes. UI frame: "How many batches?"
+**Cadence** (retired):
+Formerly the user-chosen parts-per-window count (`per_bucket`). The ZIP 318
+Poisson schedule draws every broadcast delay itself, so there is no cadence
+to choose and no chooser screen; the term survives only in history.
 
 **Wake**:
 An OS-scheduled re-entry into the app for a window. Two kinds per window: a
@@ -88,17 +88,114 @@ round's inputs nor its outputs, so planning over it is wrong.
 A part whose window became unwitnessable and which moved itself to a coming
 window. Rendered as a plain explanatory sentence, never an error.
 
-**Stranded**:
-Value left out of the plan because moving it would cost more than it carries.
-Disclosed at consent.
-
 **Residual**:
-What remains when the migration completes; disclosed on completion.
+Value left unmigrated because moving it would cost more than it carries —
+projected and disclosed at consent, reported again on completion. A plan
+never loses value silently: migrated + fees + residual equals the starting
+balance.
+_Avoid_: stranded (retired 2026-07-26 when zingolib unified the plan-time
+and completion-time vocabulary on "residual")
 
 **Consent**:
 The single user approval of an exact plan hash before anything is signed or
 sent. Covers the whole migration, both phases.
 
+## Mixnet Mode
+
+**Mixnet Mode**:
+Routing the send (transaction broadcast) and price-fetch surfaces over the
+Nym mixnet. Synchronization is never covered; the IP-correlation disclaimer
+(ZIP-0318) states that boundary. Modes: `off`, `bootstrapping`, `ready`,
+`died`.
+
+**Fail-closed**:
+The policy that when Mixnet Mode is anything but `off`, a covered surface
+that cannot reach the mixnet refuses rather than falling back to clearnet.
+A refusal is not a server error and is never retried.
+
+**Silent alpha APK**:
+An alpha build of the app that routes the covered surfaces over Nym with
+the stock (pre-Mixnet-Mode) UX/UI — no toggle, no banners, no disclaimer
+screen. Its purpose is isolating transport behavior from UI work.
+_Avoid_: silent mode (it is a build, not a runtime mode)
+
+**Always On** (build flavor):
+The build flavors that produce the silent alpha APKs: Mixnet Mode is enabled
+unconditionally at wallet initialization and cannot be disabled at runtime.
+Two network variants exist — `alwayson` first-runs on mainnet, and
+`alwaysontest` first-runs on testnet — installable side by side.
+
+## Indexers
+
+**Indexer**:
+A lightwalletd or zaino gRPC endpoint the wallet talks to. In UI copy:
+"server".
+
+**Operator**:
+The party running one or more indexer endpoints. Regional DNS variants of
+one operator (`eu.zec.rocks`, `zec.rocks`) are the same operator. Trust,
+diversity, and exclusion are all reckoned per operator, never per DNS name.
+
+**Sync Indexer**:
+The indexer the wallet synchronizes against. It necessarily learns the
+wallet's address set.
+
+**Broadcast Indexer**:
+An indexer drawn to receive one transaction broadcast. Also called a
+**witness**. A Broadcast Indexer is never the Sync Indexer: the operator
+that holds the address set must not also receive the broadcast. Exclusion
+is by operator.
+_Avoid_: relay, send server
+
+**Witness Rotation**:
+The policy of drawing each broadcast's witness uniformly from an
+operator-diverse pool, so accumulating knowledge of the wallet's sends
+spreads across parties instead of concentrating in one.
+
+**Census** (of indexers):
+The one authoritative list of indexer endpoints, held in zingolib and
+consumed everywhere an indexer is defaulted, selected, probed, or
+health-checked. Refreshes on release cadence, never over the network at
+runtime. Server selection consults only the census.
+_Avoid_: registry (that names the retired live fetch), server list (ambiguous)
+
+**Operator diversity**:
+The requirement that indexer selection — for sync and for broadcast —
+pursue distinct operators, not merely distinct hostnames. A selection whose
+candidates collapse to one operator fails this even if it lists many URIs.
+
+## Price surface
+
+**Price observation**:
+One fetched ZEC/USD price point, held in memory awaiting a piggyback
+write. A price fetch produces an observation and a payload for the
+caller; it never promises durability.
+
+**Observation window**:
+The bounded in-memory buffer of price observations, capacity 1000.
+When the 1001st observation arrives the oldest is dropped.
+
+**Piggyback write**:
+Persistence that rides along with another operation already holding the
+wallet write lock. The price surface's only persistence path: if no such
+operation runs while an observation is buffered, the observation is lost,
+by contract.
+_Avoid_: drain (already means the immediate migration path)
+
+**Route snapshot**:
+The price surface's view of the mixnet state, as last observed by a call
+that held the wallet for its own reasons. May lag the live state by one
+poll interval; the fail-closed policy applies to the snapshot.
+
+**Price source**:
+An operator the wallet asks for the ZEC/USD price: Gemini and Kraken
+(medians of recent trades) or CoinGecko (an aggregator's spot value).
+
+**Price race**:
+One fetch asking every price source concurrently and reporting the first
+success; the losing requests are cancelled. Only a race in which every
+source fails is a fetch failure, and that failure names each source.
+
 ## CI
 
 **Blocking check** — a PR CI job whose failure fails the pull request.
@@ -116,8 +213,15 @@ the verdict path.
 
 **Bucket** — a group of Android integration tests that share one CI job,
 so runner setup and emulator boot amortize across the group instead of
-being paid once per test. Unrelated to the migration API's `per_bucket`
-windowing sense, which UI copy avoids entirely.
+being paid once per test. Unrelated to the migration schedule's windowing
+sense of the word, which UI copy avoids entirely.
+
+**Mobileclient scenario contract** — the agreement that the
+`*_mobileclient` regtest scenarios zingo-mobile consumes from zingolib
+keep pre-ironwood semantics: the scenario chain never activates NU6.3,
+no funds can land in the Ironwood pool, and the on-device ledgers assert
+the pre-ironwood distribution. An ironwood-era ledger is valid only
+after a coordinated change on both sides of the contract.
 
 **Fail-all** — the policy that the first failure of any blocking check
 cancels the entire run at once, rather than letting the surviving checks

__tests__/CheckAddressVerdict.unit.test.ts

@@ -0,0 +1,56 @@
+/**
+ * @format
+ */
+
+import { interpretCheckAddressResult } from '../components/Receive/components/checkAddressVerdict';
+import { FfiResult } from '../app/walletBackend/ffi';
+
+const ok = (value: string): FfiResult<string> => ({ ok: true, value });
+const rejected = (): FfiResult<string> => ({
+  ok: false,
+  error: { code: 'InvalidInput', message: 'bad address' },
+});
+
+describe('interpretCheckAddressResult', () => {
+  test('is_wallet_address true is a positive verdict', () => {
+    const raw = JSON.stringify({ is_wallet_address: true, account_id: 0 });
+    expect(interpretCheckAddressResult(ok(raw))).toEqual({ kind: 'mine' });
+  });
+
+  test('is_wallet_address false is a negative verdict', () => {
+    const raw = JSON.stringify({ is_wallet_address: false, account_id: 0 });
+    expect(interpretCheckAddressResult(ok(raw))).toEqual({ kind: 'notMine' });
+  });
+
+  test('a typed FFI rejection is named, and carries its code', () => {
+    expect(interpretCheckAddressResult(rejected())).toEqual({
+      kind: 'ffiRejection',
+      code: 'InvalidInput',
+      message: 'bad address',
+    });
+  });
+
+  // EVIDENCE of the misinterpretation this replaces: the screen stored
+  // `is_wallet_address` straight off JSON.parse behind a `verifyOK !== null`
+  // render gate, so a well-formed payload lacking the field stored
+  // `undefined`, passed the gate, and rendered the definitive "this address
+  // does not belong to you" — a confident false negative produced by a
+  // check that never returned a verdict.
+  test('a payload without is_wallet_address is malformed, not "not your address"', () => {
+    const raw = JSON.stringify({ encoded_address: 'u1aaa' });
+    expect(interpretCheckAddressResult(ok(raw)).kind).toBe('malformed');
+  });
+
+  // EVIDENCE, same gate: a truthy non-boolean must not read as "yours".
+  test('a non-boolean is_wallet_address is malformed, not a verdict', () => {
+    const raw = JSON.stringify({ is_wallet_address: 'yes' });
+    expect(interpretCheckAddressResult(ok(raw)).kind).toBe('malformed');
+  });
+
+  // EVIDENCE: a parse failure used to be swallowed by a bare catch, so the
+  // user tapped Verify and nothing happened at all.
+  test('an unparseable or empty payload is malformed, never silent', () => {
+    expect(interpretCheckAddressResult(ok('not json')).kind).toBe('malformed');
+    expect(interpretCheckAddressResult(ok('')).kind).toBe('malformed');
+  });
+});