Skip to content

Commit a60a10b

Browse files
ovitrifovitrif
committed
ai: lsp rest api agent skill
1 parent 7c65722 commit a60a10b

7 files changed

Lines changed: 736 additions & 1 deletion

File tree

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"name": "blocktank-api",
3+
"description": "Interact with the Blocktank LSP API for Lightning testing during bitkit development."
4+
}

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Blocktank API Plugin
2+
3+
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.
4+
5+
## Usage
6+
7+
Once installed, the skill auto-triggers when you mention things like:
8+
- "mine blocks", "deposit sats", "pay invoice", "force close"
9+
- "channel order", "CJIT", "blocktank", "LSP"
10+
11+
Claude will use the `./lsp` wrapper at the repo root to make API calls directly.
12+
13+
## Configuration
14+
15+
The default API base URL is `https://api.stag0.blocktank.to/blocktank/api/v2` (staging).
16+
17+
To override (e.g., for a local instance):
18+
19+
```bash
20+
export BLOCKTANK_API_URL=http://localhost:9000/api
21+
```
22+
23+
## Cross-project reuse
24+
25+
To use this plugin from another repo (e.g. bitkit-ios), symlink it into that project's `.claude/plugins/`:
26+
27+
```bash
28+
ln -s /path/to/bitkit-android/.claude/plugins/blocktank-api /path/to/other-repo/.claude/plugins/blocktank-api
29+
```

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

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
name: lsp
3+
description: >
4+
This skill should be used when the user asks to interact with the Blocktank LSP API,
5+
"mine blocks", "deposit sats", "pay invoice", "force close a channel", "create a channel order",
6+
"open a channel", "estimate fees", "create a CJIT channel", or mentions "blocktank", "regtest",
7+
"LSP", or Lightning channel testing workflows during bitkit development.
8+
version: 0.1.0
9+
---
10+
11+
# Blocktank LSP API
12+
13+
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.
14+
15+
No authentication is required. All requests and responses use JSON.
16+
17+
## Configuration
18+
19+
**Default base URL:** `https://api.stag0.blocktank.to/blocktank/api/v2` (staging)
20+
21+
Override with the `BLOCKTANK_API_URL` environment variable:
22+
- Local instance: `http://localhost:9000/api`
23+
24+
## API Script
25+
26+
Call any endpoint using the `./lsp` wrapper at the repo root:
27+
28+
```bash
29+
./lsp <GET|POST> <path> [json_body]
30+
```
31+
32+
Examples:
33+
34+
```bash
35+
# Get service info
36+
./lsp GET /info
37+
38+
# Create a channel order
39+
./lsp POST /channels '{"lspBalanceSat":100000,"channelExpiryWeeks":12}'
40+
41+
# Mine 6 blocks
42+
./lsp POST /regtest/chain/mine '{"count":6}'
43+
44+
# Deposit to an address
45+
./lsp POST /regtest/chain/deposit '{"address":"bcrt1q...","amountSat":500000}'
46+
```
47+
48+
The script outputs raw JSON. Pipe to `jq` for formatting if needed.
49+
50+
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.
51+
52+
## Endpoint Quick Reference
53+
54+
### Service Info
55+
56+
| Method | Path | Description |
57+
|--------|------|-------------|
58+
| GET | `/info` | Service info, LSP nodes, channel size limits, fee rates |
59+
60+
### Channel Orders
61+
62+
| Method | Path | Description |
63+
|--------|------|-------------|
64+
| POST | `/channels` | Create a channel order |
65+
| GET | `/channels/:id` | Get order by ID |
66+
| GET | `/channels?ids[]=` | Get multiple orders (1-50 IDs) |
67+
| POST | `/channels/:id/open` | Open a paid channel |
68+
| GET | `/channels/:id/min-0conf-tx-fee` | Get 0-conf fee window |
69+
| POST | `/channels/estimate-fee` | Estimate order fee |
70+
| POST | `/channels/estimate-fee-full` | Estimate fee with breakdown |
71+
72+
### CJIT (Just-In-Time Channels)
73+
74+
| Method | Path | Description |
75+
|--------|------|-------------|
76+
| POST | `/cjit` | Create a JIT channel entry |
77+
| GET | `/cjit/:id` | Get CJIT entry status |
78+
79+
### Gift
80+
81+
| Method | Path | Description |
82+
|--------|------|-------------|
83+
| POST | `/gift/pay` | Pay a gift invoice |
84+
| POST | `/gift/order` | Create a gift order |
85+
| GET | `/gift/:id` | Get gift info |
86+
87+
### Regtest Tools (regtest only)
88+
89+
| Method | Path | Description |
90+
|--------|------|-------------|
91+
| POST | `/regtest/chain/mine` | Mine blocks (default: 1) |
92+
| POST | `/regtest/chain/deposit` | Deposit sats to address (default: 100,000) |
93+
| POST | `/regtest/channel/pay` | Pay a Lightning invoice |
94+
| GET | `/regtest/channel/pay/:id` | Get payment status |
95+
| POST | `/regtest/channel/close` | Force close a channel |
96+
97+
## Common Workflows
98+
99+
### Workflow A: Purchase a Channel
100+
101+
1. **Get service info** — `GET /info` to retrieve LSP node pubkeys and channel size limits
102+
2. **Create order** — `POST /channels` with `lspBalanceSat`, `channelExpiryWeeks`, and optional `clientBalanceSat`
103+
3. **Extract payment info** — from response: `payment.onchain.address` (bitcoin address) and `feeSat` (amount to pay)
104+
4. **Fund the order** — `POST /regtest/chain/deposit` with the payment address and fee amount
105+
5. **Confirm payment** — `POST /regtest/chain/mine` with `count: 1` to mine a block
106+
6. **Poll order status** — `GET /channels/:id` until `state2` becomes `paid`
107+
7. **Open channel** — `POST /channels/:id/open` with the client's `connectionStringOrPubkey`
108+
8. **Confirm channel** — `POST /regtest/chain/mine` with `count: 6` to fully confirm
109+
110+
### Workflow B: CJIT Channel (Just-In-Time)
111+
112+
1. **Get service info** — `GET /info` for node pubkeys and limits
113+
2. **Create CJIT entry** — `POST /cjit` with `channelSizeSat`, `invoiceSat`, `nodeId`, `channelExpiryWeeks`
114+
3. **Extract invoice** — from response: `invoice.request` (bolt11 invoice string)
115+
4. **Client pays invoice** — the mobile app pays the invoice, triggering automatic channel opening
116+
5. **Poll status** — `GET /cjit/:id` until `state` becomes `completed`
117+
118+
### Workflow C: Force Close a Channel
119+
120+
1. **Get order info** — `GET /channels/:id` to find `channel.fundingTx.id` and `channel.fundingTx.vout`
121+
2. **Close channel** — `POST /regtest/channel/close` with `fundingTxId`, `vout`, and `forceCloseAfterSec: 0` for immediate close
122+
3. **Mine blocks** — `POST /regtest/chain/mine` with `count: 6` to finalize the closure
123+
124+
## State Machines
125+
126+
### Order States (`state2`)
127+
128+
```
129+
created → paid → executed
130+
↘ expired
131+
```
132+
133+
- `created` — waiting for payment
134+
- `paid` — payment confirmed, ready to open channel
135+
- `executed` — channel opened successfully
136+
- `expired` — order timed out
137+
138+
### Payment States (`payment.state2`)
139+
140+
```
141+
created → paid → refundAvailable → refunded
142+
↘ canceled
143+
```
144+
145+
### Channel States (`channel.state`)
146+
147+
```
148+
opening → open → closed
149+
```
150+
151+
### CJIT States (`state`)
152+
153+
```
154+
created → completed
155+
↘ expired
156+
↘ failed
157+
```
158+
159+
## Detailed API Reference
160+
161+
For full request/response schemas, field constraints, and error codes for every endpoint, consult:
162+
163+
- **`references/api-reference.md`** — Complete API reference with all fields, types, defaults, and validation rules

0 commit comments

Comments
 (0)