Skip to content

docs: add aliasing design (architecture/aliasing.md) - #7

Merged
TaprootFreak merged 2 commits into
developfrom
feat/aliasing-design-doc
Jun 1, 2026
Merged

docs: add aliasing design (architecture/aliasing.md)#7
TaprootFreak merged 2 commits into
developfrom
feat/aliasing-design-doc

Conversation

@TaprootFreak

Copy link
Copy Markdown
Contributor

Summary

Adds docs/architecture/aliasing.md — a forward-looking design that separates the user-facing identifier, the on-chain coin recipient field, and the server-side state lookup key into five independent layers.

Today these three concepts collapse onto a single 64-hex string, which is the root cause of:

  • raw hex visible in the UI,
  • username-resolve → address → balance / history working as an unauthenticated lookup chain,
  • cross-sender linkability of payments to the same recipient (worsened once counterparty_address lands per zk-coins/node#160),
  • the impossibility of view-only key sharing.

The design proposes:

  • Layer 1 — Alias: name@host, permanent, stable for the wallet's lifetime, the only form ever shown to the user.
  • Layer 2 — Directory: an unauthenticated .well-known endpoint that returns routing material only (no balance, no activity).
  • Layer 3 — Payment derivation: per-send ECDH-derived payment_tag + scan_hint in the coin (direct extension of SPEC §15 D2/D10).
  • Layer 4 — State: all read endpoints (/api/balance, /api/history, /api/scan) become Schnorr-signed, with a three-tier capability split (receive / view via scan_priv / spend via spend_priv).
  • Layer 5 — On-chain: unchanged — 64-byte half-aggregate nullifier.

Why a separate doc

addressing.md describes the current three-phase implementation. This document is explicitly marked Design and supersedes it once implemented. Keeping them side by side preserves the audit trail of how the address model evolved.

Cross-references

  • SPEC §15 D2/D10 — cryptographic prerequisites (commitment-based recipient)
  • zk-coins/node#170 — aliasing closes P10 (unauthenticated reads) but does not address P3/P9 (operator plaintext visibility)
  • Companion to architecture/addressing.md, architecture/privacy-model.md, architecture/nullifier-design.md

What this PR does not do

  • No protocol or wallet implementation work.
  • No changes to the current addressing.md document (kept for current-state reference).
  • No commitment on timing or sequencing relative to D2/D10 in SPEC.md.

Local verification

  • npm ci && npm run build — green, no broken links or markdown errors.

Test plan

  • Reviewer reads architecture/aliasing.md end-to-end and confirms the five-layer model holds together.
  • Reviewer confirms cross-references to addressing.md, SPEC §15, and #170 land correctly.
  • Reviewer flags any of the four open items (circuit slot, scan-hint index, squatting policy, view-only export format) that should be split into separate tracking issues.

Forward-looking design that separates the user-facing identifier,
the on-chain coin recipient, and the server-side state lookup key
into five independent layers. Aliases (`name@host`) become the only
user-visible form; raw hex is removed from the UI entirely.

Cross-references the current addressing scheme, SPEC §15 D2/D10,
and zk-coins/node#170 (network-layer decentralization).
@TaprootFreak
TaprootFreak marked this pull request as ready for review June 1, 2026 22:42
Per project constraint: the wallet SDK must mirror familiar wallet
SDKs (Cake, LayerZ, BlueWallet, …) so integrators work only with
seed and address. All zk-specific concepts move into the node.

Changes:
- New Layer 2 (SDK surface) section with concrete TypeScript shape
  and explicit "does / does not" lists.
- ECDH / payment derivation moved into the node (Layer 3 rewritten
  as node-internal; previous wallet-side derivation removed).
- Capability split (scan_priv / spend_priv) removed; single wallet
  signing key. View-only / watch-only flows declared out of scope.
- "Default choices" updated: scan location no longer a question;
  default-alias derivation rule added.
- Trust trade-off (operator visibility) made explicit, with
  self-hosting as the documented escape hatch.
- Integration mapping table for Cake / LayerZ / BlueWallet.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant