From 46725bef8161a794f914adbacf12a1905905044f Mon Sep 17 00:00:00 2001 From: pasta Date: Mon, 9 Nov 2026 22:56:44 -0600 Subject: [PATCH 1/2] docs: move the agent rules to AGENTS.md so every agent reads them Codex and other agents read AGENTS.md and ignore CLAUDE.md, so they worked here without the repo's rules. CLAUDE.md now imports AGENTS.md, so Claude Code loads the same file. Co-Authored-By: Claude Fable 5.2 --- AGENTS.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 96 +------------------------------------------------------ 2 files changed, 96 insertions(+), 95 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..65ebbdf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,95 @@ +# AGENTS.md + +This file provides guidance to coding agents (Claude Code, Codex and others) working in this repository. `CLAUDE.md` imports it. + +## Project Overview + +Non-custodial browser-based bridge for converting Dash Core funds to Dash Platform credits. All cryptographic operations happen client-side; keys never leave the browser. + +## Commands + +```bash +npm install # Install dependencies +npm run dev # Start Vite dev server +npm run build # TypeScript check + Vite production build +npm run test # Run Vitest tests +``` + +## Architecture + +The main codebase is TypeScript in `src/` (Vite + TypeScript). There's also a `v2/` directory with a JavaScript-based alternative implementation using `@dashevo/dashcore-lib` and `dash` SDK directly. + +### Source Structure (src/) + +``` +src/ +├── main.ts # Entry point, UI orchestration, state management +├── config.ts # Network configuration (testnet/mainnet) +├── types.ts # TypeScript interfaces (KeyPair, UTXO, BridgeState, etc.) +├── crypto/ # Cryptographic operations +│ ├── keys.ts # Key generation (secp256k1) +│ ├── hd.ts # HD wallet derivation (BIP32/BIP39) +│ ├── address.ts # Address derivation from public keys +│ ├── hash.ts # Hash functions (SHA256, RIPEMD160) +│ └── signing.ts # Transaction signing +├── transaction/ # Dash transaction handling +│ ├── builder.ts # Asset lock transaction construction (Type 8) +│ ├── serialize.ts # Transaction serialization +│ ├── sighash.ts # Signature hash computation +│ └── structures.ts # Transaction data structures +├── proof/ # Asset lock proof construction +│ └── builder.ts # InstantSend lock proof building +├── api/ # Network communication +│ ├── insight.ts # Insight API client (UTXO fetching, broadcast) +│ ├── dapi.ts # JSON-RPC client (only for a custom devnet with its own rpcUrl) +│ ├── dapi-subscription.ts # DAPI bloom-filter streams (InstantSend locks on every network) +│ ├── islock.ts # IslockService: picks the InstantSend lock source per network +│ ├── evonode-discovery.ts # Testnet/mainnet evonodes from the masternode list the seeds serve +│ └── evonodes.ts # Quorum-service evonode list (discovery fallback) +├── platform/ # Dash Platform operations +│ ├── identity.ts # Identity registration and top-up +│ └── login.ts # Sign in with Dash: key checks and signing +├── embed/ # Embed mode for third-party apps (docs/widget.md) +│ ├── protocol.ts # Shared postMessage protocol + URL param validation +│ ├── bridge.ts # Bridge side: framing guard, EmbedSession messaging +│ └── login.ts # Sign in with Dash: message format, redirect fragments +├── widget/ # widget.js SDK (separate lib build: vite.widget.config.ts) +│ └── verify.ts # verifyLogin -> dist/widget-verify.mjs (vite.verify.config.ts) +└── ui/ # UI layer + ├── state.ts # State machine and state transitions + ├── components.ts # UI rendering + └── qrcode.ts # QR code generation +``` + +### Key Flows + +**Identity Creation (create mode):** +1. Generate HD wallet from mnemonic → derive asset lock keypair +2. Display deposit address with QR code +3. Poll Insight API for UTXO → build Type 8 asset lock transaction +4. Sign transaction locally → broadcast via Insight +5. Wait for InstantSend lock via DAPI → build asset lock proof +6. Register identity on Platform with configured identity keys + +**Top-up Mode:** +Uses random one-time keypair (not HD-derived) to add credits to an existing identity. + +### Key Types + +- `KeyType`: ECDSA_SECP256K1 | ECDSA_HASH160 +- `KeyPurpose`: AUTHENTICATION | TRANSFER | VOTING | OWNER +- `SecurityLevel`: MASTER | CRITICAL | HIGH | MEDIUM +- `BridgeMode`: create | topup + +### Network Selection + +Network is determined by URL parameter: `?network=mainnet` (defaults to testnet). + +InstantSend lock source and Platform status per network: + +- **testnet and mainnet**: no JSON-RPC service, and no digitalcash.dev anywhere (the build check fails if it reappears). The lock comes from the DAPI bloom-filter stream on 3 evonodes at once. They are discovered when a funding flow starts, from the masternode list served by `@dashevo/dapi-client`'s seeds for that network, preferring nodes the quorum service health-checks and falling back to its list; the subscription rejects before broadcast if both fail. There is no built-in node list. Platform status is read through the EvoSDK (`platform/status.ts`) (it tolerates sections nodes leave out). +- **devnets**: their configured `rpcUrl` if any, otherwise the DAPI stream over their `dapiAddresses`; Platform status through dapi-client. + +## Dependencies + +Core dependencies: `@dashevo/evo-sdk`, `@noble/hashes`, `@noble/secp256k1`, `@scure/bip32`, `@scure/bip39`, `bs58check`, `qrcode` diff --git a/CLAUDE.md b/CLAUDE.md index 1205804..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,95 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -Non-custodial browser-based bridge for converting Dash Core funds to Dash Platform credits. All cryptographic operations happen client-side; keys never leave the browser. - -## Commands - -```bash -npm install # Install dependencies -npm run dev # Start Vite dev server -npm run build # TypeScript check + Vite production build -npm run test # Run Vitest tests -``` - -## Architecture - -The main codebase is TypeScript in `src/` (Vite + TypeScript). There's also a `v2/` directory with a JavaScript-based alternative implementation using `@dashevo/dashcore-lib` and `dash` SDK directly. - -### Source Structure (src/) - -``` -src/ -├── main.ts # Entry point, UI orchestration, state management -├── config.ts # Network configuration (testnet/mainnet) -├── types.ts # TypeScript interfaces (KeyPair, UTXO, BridgeState, etc.) -├── crypto/ # Cryptographic operations -│ ├── keys.ts # Key generation (secp256k1) -│ ├── hd.ts # HD wallet derivation (BIP32/BIP39) -│ ├── address.ts # Address derivation from public keys -│ ├── hash.ts # Hash functions (SHA256, RIPEMD160) -│ └── signing.ts # Transaction signing -├── transaction/ # Dash transaction handling -│ ├── builder.ts # Asset lock transaction construction (Type 8) -│ ├── serialize.ts # Transaction serialization -│ ├── sighash.ts # Signature hash computation -│ └── structures.ts # Transaction data structures -├── proof/ # Asset lock proof construction -│ └── builder.ts # InstantSend lock proof building -├── api/ # Network communication -│ ├── insight.ts # Insight API client (UTXO fetching, broadcast) -│ ├── dapi.ts # JSON-RPC client (only for a custom devnet with its own rpcUrl) -│ ├── dapi-subscription.ts # DAPI bloom-filter streams (InstantSend locks on every network) -│ ├── islock.ts # IslockService: picks the InstantSend lock source per network -│ ├── evonode-discovery.ts # Testnet/mainnet evonodes from the masternode list the seeds serve -│ └── evonodes.ts # Quorum-service evonode list (discovery fallback) -├── platform/ # Dash Platform operations -│ ├── identity.ts # Identity registration and top-up -│ └── login.ts # Sign in with Dash: key checks and signing -├── embed/ # Embed mode for third-party apps (docs/widget.md) -│ ├── protocol.ts # Shared postMessage protocol + URL param validation -│ ├── bridge.ts # Bridge side: framing guard, EmbedSession messaging -│ └── login.ts # Sign in with Dash: message format, redirect fragments -├── widget/ # widget.js SDK (separate lib build: vite.widget.config.ts) -│ └── verify.ts # verifyLogin -> dist/widget-verify.mjs (vite.verify.config.ts) -└── ui/ # UI layer - ├── state.ts # State machine and state transitions - ├── components.ts # UI rendering - └── qrcode.ts # QR code generation -``` - -### Key Flows - -**Identity Creation (create mode):** -1. Generate HD wallet from mnemonic → derive asset lock keypair -2. Display deposit address with QR code -3. Poll Insight API for UTXO → build Type 8 asset lock transaction -4. Sign transaction locally → broadcast via Insight -5. Wait for InstantSend lock via DAPI → build asset lock proof -6. Register identity on Platform with configured identity keys - -**Top-up Mode:** -Uses random one-time keypair (not HD-derived) to add credits to an existing identity. - -### Key Types - -- `KeyType`: ECDSA_SECP256K1 | ECDSA_HASH160 -- `KeyPurpose`: AUTHENTICATION | TRANSFER | VOTING | OWNER -- `SecurityLevel`: MASTER | CRITICAL | HIGH | MEDIUM -- `BridgeMode`: create | topup - -### Network Selection - -Network is determined by URL parameter: `?network=mainnet` (defaults to testnet). - -InstantSend lock source and Platform status per network: - -- **testnet and mainnet**: no JSON-RPC service, and no digitalcash.dev anywhere (the build check fails if it reappears). The lock comes from the DAPI bloom-filter stream on 3 evonodes at once. They are discovered when a funding flow starts, from the masternode list served by `@dashevo/dapi-client`'s seeds for that network, preferring nodes the quorum service health-checks and falling back to its list; the subscription rejects before broadcast if both fail. There is no built-in node list. Platform status is read through the EvoSDK (`platform/status.ts`) (it tolerates sections nodes leave out). -- **devnets**: their configured `rpcUrl` if any, otherwise the DAPI stream over their `dapiAddresses`; Platform status through dapi-client. - -## Dependencies - -Core dependencies: `@dashevo/evo-sdk`, `@noble/hashes`, `@noble/secp256k1`, `@scure/bip32`, `@scure/bip39`, `bs58check`, `qrcode` +@AGENTS.md From 71cb8123e4c756263542484b22954dbcc5f815c4 Mon Sep 17 00:00:00 2001 From: pasta Date: Mon, 9 Nov 2026 23:14:17 -0600 Subject: [PATCH 2/2] docs: make CLAUDE.md a symlink to AGENTS.md Claude Code skips an @AGENTS.md import when it starts in a subdirectory, because the imported file is then outside the working directory. A symlink is read as the file itself, from any directory. Co-Authored-By: Claude Fable 5.2 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) mode change 100644 => 120000 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 43c994c..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -@AGENTS.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file