Merge branch 'master' into chore/keychain-error-logs

Author: jvsena42

.claude/install-plugins.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -u -o pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+MARKETPLACE_DIR="$REPO_ROOT/.claude/plugins"
+MARKETPLACE_NAME="bitkit-android"
+
+if ! command -v claude >/dev/null 2>&1; then
+  echo "Error: 'claude' CLI not found on PATH. Install Claude Code first." >&2
+  exit 1
+fi
+
+if [ ! -f "$MARKETPLACE_DIR/.claude-plugin/marketplace.json" ]; then
+  echo "Error: $MARKETPLACE_DIR/.claude-plugin/marketplace.json not found." >&2
+  exit 1
+fi
+
+if claude plugin marketplace list 2>/dev/null | grep -q "\b${MARKETPLACE_NAME}\b"; then
+  echo "Updating marketplace '${MARKETPLACE_NAME}'..."
+  claude plugin marketplace update "${MARKETPLACE_NAME}" || \
+    echo "  (warning: marketplace update failed; continuing)"
+else
+  echo "Adding marketplace '${MARKETPLACE_NAME}'..."
+  claude plugin marketplace add "${MARKETPLACE_DIR}" --scope user
+fi
+
+failures=()
+for plugin_dir in "${MARKETPLACE_DIR}"/*/; do
+  [ -f "${plugin_dir}.claude-plugin/plugin.json" ] || continue
+  plugin_name="$(basename "${plugin_dir}")"
+  full="${plugin_name}@${MARKETPLACE_NAME}"
+
+  if claude plugin list 2>/dev/null | grep -q "${full}"; then
+    echo "Updating plugin '${full}'..."
+    claude plugin update "${full}" || failures+=("${full} (update)")
+  else
+    echo "Installing plugin '${full}'..."
+    claude plugin install "${full}" --scope user || failures+=("${full} (install)")
+  fi
+done
+
+echo ""
+if [ "${#failures[@]}" -gt 0 ]; then
+  echo "Completed with failures: ${failures[*]}" >&2
+  exit 1
+fi
+echo "Done. Restart Claude Code if it was running."

.claude/plugins/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "bitkit-android",
+  "owner": {
+    "name": "Synonym",
+    "email": "dev@synonym.to"
+  },
+  "plugins": [
+    {
+      "name": "blocktank-api",
+      "source": "./blocktank-api",
+      "description": "Interact with the Blocktank LSP API for Lightning testing during bitkit development."
+    }
+  ]
+}

.claude/plugins/blocktank-api/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "blocktank-api",
+  "description": "Interact with the Blocktank LSP API for Lightning testing during bitkit development."
+}

.claude/plugins/blocktank-api/README.md

@@ -0,0 +1,39 @@
+# Blocktank API Plugin
+
+A Claude Code plugin that gives Claude knowledge of the full Blocktank LSP API, enabling it to autonomously create channels, fund them, mine blocks, pay invoices, and close channels during Blocktank LSP testing.
+
+## Setup
+
+Run once from the repo root (re-run anytime to update):
+
+```sh
+./.claude/install-plugins.sh
+```
+
+Restart Claude Code once. The `blocktank-api:lsp` skill (invoked as `/lsp`) is then available.
+
+## Usage
+
+Once installed, the skill auto-triggers when you mention things like:
+- "mine blocks", "deposit sats", "pay invoice", "force close"
+- "channel order", "CJIT", "blocktank", "LSP"
+
+Claude will use the `./lsp` wrapper at the repo root to make API calls directly.
+
+## Configuration
+
+The default API base URL is `https://api.stag0.blocktank.to/blocktank/api/v2` (staging).
+
+To override (e.g., for a local instance):
+
+```bash
+export BLOCKTANK_API_URL=http://localhost:9000/api
+```
+
+## Cross-project reuse
+
+To use this plugin from another repo (e.g. bitkit-ios), symlink it into that project's `.claude/plugins/`:
+
+```bash
+ln -s /path/to/bitkit-android/.claude/plugins/blocktank-api /path/to/other-repo/.claude/plugins/blocktank-api
+```

.claude/plugins/blocktank-api/skills/lsp/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: lsp
+description: >
+  This skill should be used when the user asks to interact with the Blocktank LSP API,
+  "mine blocks", "deposit sats", "pay invoice", "force close a channel", "create a channel order",
+  "open a channel", "estimate fees", "create a CJIT channel", or mentions "blocktank", "regtest",
+  "LSP", or Lightning channel testing workflows during bitkit development.
+version: 0.1.0
+---
+
+# Blocktank LSP API
+
+Blocktank is the Lightning Service Provider (LSP) used by Bitkit. This skill provides full knowledge of its REST API and a utility script to call any endpoint from the command line.
+
+No authentication is required. All requests and responses use JSON.
+
+## Configuration
+
+**Default base URL:** `https://api.stag0.blocktank.to/blocktank/api/v2` (staging)
+
+Override with the `BLOCKTANK_API_URL` environment variable:
+- Local instance: `http://localhost:9000/api`
+
+## API Script
+
+Call any endpoint using the `./lsp` wrapper at the repo root:
+
+```bash
+./lsp <GET|POST> <path> [json_body]
+```
+
+Examples:
+
+```bash
+# Get service info
+./lsp GET /info
+
+# Create a channel order
+./lsp POST /channels '{"lspBalanceSat":100000,"channelExpiryWeeks":12}'
+
+# Mine 6 blocks
+./lsp POST /regtest/chain/mine '{"count":6}'
+
+# Deposit to an address
+./lsp POST /regtest/chain/deposit '{"address":"bcrt1q...","amountSat":500000}'
+```
+
+The script outputs raw JSON. Pipe to `jq` for formatting if needed.
+
+On HTTP errors (4xx/5xx), the script prints the status code to stderr and the error response body to stdout, then exits with code 1.
+
+## Endpoint Quick Reference
+
+### Service Info
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/info` | Service info, LSP nodes, channel size limits, fee rates |
+
+### Channel Orders
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/channels` | Create a channel order |
+| GET | `/channels/:id` | Get order by ID |
+| GET | `/channels?ids[]=` | Get multiple orders (1-50 IDs) |
+| POST | `/channels/:id/open` | Open a paid channel |
+| GET | `/channels/:id/min-0conf-tx-fee` | Get 0-conf fee window |
+| POST | `/channels/estimate-fee` | Estimate order fee |
+| POST | `/channels/estimate-fee-full` | Estimate fee with breakdown |
+
+### CJIT (Just-In-Time Channels)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/cjit` | Create a JIT channel entry |
+| GET | `/cjit/:id` | Get CJIT entry status |
+
+### Gift
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/gift/pay` | Pay a gift invoice |
+| POST | `/gift/order` | Create a gift order |
+| GET | `/gift/:id` | Get gift info |
+
+### Regtest Tools (regtest only)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/regtest/chain/mine` | Mine blocks (default: 1) |
+| POST | `/regtest/chain/deposit` | Deposit sats to address (default: 100,000) |
+| POST | `/regtest/channel/pay` | Pay a Lightning invoice |
+| GET | `/regtest/channel/pay/:id` | Get payment status |
+| POST | `/regtest/channel/close` | Force close a channel |
+
+## Common Workflows
+
+### Workflow A: Purchase a Channel
+
+1. **Get service info** — `GET /info` to retrieve LSP node pubkeys and channel size limits
+2. **Create order** — `POST /channels` with `lspBalanceSat`, `channelExpiryWeeks`, and optional `clientBalanceSat`
+3. **Extract payment info** — from response: `payment.onchain.address` (bitcoin address) and `feeSat` (amount to pay)
+4. **Fund the order** — `POST /regtest/chain/deposit` with the payment address and fee amount
+5. **Confirm payment** — `POST /regtest/chain/mine` with `count: 1` to mine a block
+6. **Poll order status** — `GET /channels/:id` until `state2` becomes `paid`
+7. **Open channel** — `POST /channels/:id/open` with the client's `connectionStringOrPubkey`
+8. **Confirm channel** — `POST /regtest/chain/mine` with `count: 6` to fully confirm
+
+### Workflow B: CJIT Channel (Just-In-Time)
+
+1. **Get service info** — `GET /info` for node pubkeys and limits
+2. **Create CJIT entry** — `POST /cjit` with `channelSizeSat`, `invoiceSat`, `nodeId`, `channelExpiryWeeks`
+3. **Extract invoice** — from response: `invoice.request` (bolt11 invoice string)
+4. **Client pays invoice** — the mobile app pays the invoice, triggering automatic channel opening
+5. **Poll status** — `GET /cjit/:id` until `state` becomes `completed`
+
+### Workflow C: Force Close a Channel
+
+1. **Get order info** — `GET /channels/:id` to find `channel.fundingTx.id` and `channel.fundingTx.vout`
+2. **Close channel** — `POST /regtest/channel/close` with `fundingTxId`, `vout`, and `forceCloseAfterSec: 0` for immediate close
+3. **Mine blocks** — `POST /regtest/chain/mine` with `count: 6` to finalize the closure
+
+### Workflow D: Automated Invoice Payments
+
+Bulk-create and pay invoices to populate the app with payment activity.
+
+**Prerequisites:** Dev debug build installed, wallet set up, LDK node running, open channel with inbound capacity, ADB connected.
+
+**Run with defaults** (21 invoices of 1..21 sats, mine 150 blocks in batches of 10):
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/skills/lsp/scripts/pay-invoices.sh"
+```
+
+**Custom parameters** via env vars:
+
+```bash
+INVOICE_COUNT=10 DESCRIPTION="test-ovi-{i}" MINE_TOTAL=60 MINE_BATCH=10 \
+  "${CLAUDE_PLUGIN_ROOT}/skills/lsp/scripts/pay-invoices.sh"
+```
+
+- `DESCRIPTION` — invoice description; `{i}` is replaced with the invoice index (default: `dev-payment-{i}`)
+
+The script uses the `DevToolsProvider` ContentProvider (dev builds only) to create invoices on the app's LDK node via `adb shell content call`, then pays each via the LSP's `POST /regtest/channel/pay` endpoint.
+
+**Create a single invoice manually:**
+
+```bash
+adb shell "content call --uri content://to.bitkit.dev.devtools \
+  --method createInvoice --arg '{\"amount\":1000,\"description\":\"test\"}'"
+```
+
+## State Machines
+
+### Order States (`state2`)
+
+```
+created → paid → executed
+    ↘ expired
+```
+
+- `created` — waiting for payment
+- `paid` — payment confirmed, ready to open channel
+- `executed` — channel opened successfully
+- `expired` — order timed out
+
+### Payment States (`payment.state2`)
+
+```
+created → paid → refundAvailable → refunded
+    ↘ canceled
+```
+
+### Channel States (`channel.state`)
+
+```
+opening → open → closed
+```
+
+### CJIT States (`state`)
+
+```
+created → completed
+    ↘ expired
+    ↘ failed
+```
+
+## Detailed API Reference
+
+For full request/response schemas, field constraints, and error codes for every endpoint, consult:
+
+- **`references/api-reference.md`** — Complete API reference with all fields, types, defaults, and validation rules