Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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`
95 changes: 0 additions & 95 deletions CLAUDE.md

This file was deleted.

1 change: 1 addition & 0 deletions CLAUDE.md
Loading