readme

docs/local-dev.md

@@ -0,0 +1,133 @@
+# Descro — Local Development & Testing
+
+## Prerequisites
+
+- [Rust](https://rustup.rs/) with the `solana` toolchain (`rust-toolchain.toml` pins the version)
+- [Solana CLI](https://docs.solana.com/cli/install-solana-cli-tools) ≥ 1.18
+- [Anchor CLI](https://www.anchor-lang.com/docs/installation) (used for `build-sbf`)
+- Node.js + [Yarn](https://yarnpkg.com/)
+- A browser wallet extension (Phantom, Backpack, etc.)
+
+---
+
+## 1 — Start a local validator
+
+```bash
+solana-test-validator --reset
+```
+
+Leave this running in a dedicated terminal. The validator listens on:
+
+| Endpoint | Address |
+|---|---|
+| RPC | `http://localhost:8899` |
+| WebSocket | `ws://localhost:8900` |
+
+---
+
+## 2 — Configure the Solana CLI to use localhost
+
+```bash
+solana config set --url localhost
+```
+
+Verify:
+
+```bash
+solana config get
+# RPC URL: http://localhost:8899
+```
+
+If you do not yet have a local keypair:
+
+```bash
+solana-keygen new --outfile ~/.config/solana/id.json
+solana airdrop 10
+```
+
+---
+
+## 3 — Build and deploy the programs
+
+Build order matters — `descro` depends on `descro_ext_resolvers`.
+
+```bash
+# Build the resolver registry first
+cargo build-sbf --manifest-path programs/descro_ext_resolvers/Cargo.toml
+
+# Then build the escrow program
+cargo build-sbf --manifest-path programs/descro/Cargo.toml
+```
+
+Deploy both to the local validator:
+
+```bash
+solana program deploy \
+  --program-id programs/descro_ext_resolvers/keypair.json \
+  target/deploy/descro_ext_resolvers.so
+
+solana program deploy \
+  --program-id programs/descro/keypair.json \
+  target/deploy/descro.so
+```
+
+> **Note:** if you don't have per-program keypair files, omit `--program-id` and note
+> the deployed address; then update the IDs in `sdk/src/pda.ts` and the IDL `address`
+> fields accordingly.
+
+Expected program IDs (as declared in `Anchor.toml`):
+
+| Program | ID |
+|---|---|
+| `descro` | `DjVR4EuYV6USMJFfsGZwhZ3y8rtWsmG8EvDY96GTqqi3` |
+| `descro_ext_resolvers` | `GwUPAKs3HHzCpj8uhet4NAnxk9GWNwfrYbpihu5DyFp` |
+
+---
+
+## 4 — Configure your browser wallet for localhost
+
+**Phantom:**
+1. Settings → Developer Settings → Testnet Mode (or add a custom RPC)
+2. Network → Custom → `http://localhost:8899`
+
+**Backpack:**
+1. Settings → Solana → RPC Connection → Custom → `http://localhost:8899`
+
+Airdrop yourself some SOL from the CLI or from the Solana faucet panel inside the wallet.
+
+---
+
+## 5 — Start the app
+
+```bash
+yarn install          # from repo root, only needed once
+yarn workspace descro-app run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+In the top-right **Network** dropdown, select **Localnet**. The app will connect to
+`http://localhost:8899`. Connect your wallet and you can create escrows, deposit funds,
+and test the full instruction flow against the locally-deployed programs.
+
+---
+
+## Running tests
+
+Tests load the compiled `.so` files via `include_bytes!`, so always build before testing.
+
+```bash
+# All tests for the escrow program (includes CPI flow test)
+cargo test --manifest-path programs/descro/Cargo.toml
+
+# All tests for the resolver registry
+cargo test --manifest-path programs/descro_ext_resolvers/Cargo.toml
+
+# Single test by name
+cargo test --manifest-path programs/descro/Cargo.toml -- test_create_escrow
+
+# Specific test file
+cargo test --manifest-path programs/descro/Cargo.toml --test test_resolve
+```
+
+Tests use **LiteSVM** (in-process) and do not require a running validator.