\r \r

BTCD PGP Collateralization Flow\r

\r This skill contains a complete, self-contained Node.js project to run the full BTCD collateralization lifecycle on the PGP (Elastos) chain.\r \r

Bundled Code Location\r

\r All runnable code is inside the scripts/ directory relative to this SKILL.md:\r \r

scripts/\r
├── package.json\r
├── .env.template.txt\r
├── setup.js\r
├── 00-create-order.js\r
├── 01-take-order.js\r
├── 02-lock-btc-collateral.js\r
├── 03-submit-btc-proof.js\r
├── 05-claim-btcd-tokens.js\r
├── 06-repay-loan.js\r
├── abi/                    # Contract ABIs (LoanContract, Order, Issuer, ERC20, ArbitratorManager)\r
├── utils/                  # Shared utilities (config, wallet, EVM/BTC clients, logger, state, proof, arbiter)\r
└── state/                  # Flow state persists here\r
```\r
\r
## Setup Instructions\r
\r
1. **Copy the entire `scripts/` directory** to a working directory:\r
   ```bash\r
   cp -r \x3Cpath-to-this-skill>/scripts/ /tmp/btcd-flow/\r
   cd /tmp/btcd-flow/\r
   ```\r
\r
2. **Create `.env`** from the template. Only two values need changing:\r
   ```bash\r
   cp .env.template.txt .env\r
   ```\r
   Edit `.env` and set:\r
   - `EVM_PRIVATE_KEY` — your EVM private key (with `0x` prefix)\r
   - `BTC_PRIVATE_KEY` — your BTC private key (hex, **no** `0x` prefix)\r
\r
   Optionally adjust `LENDING_AMOUNT` (minimum 10) and `LENDING_DAYS` (only 90 or 180).\r
\r
   All other values (contract addresses, RPC URLs, subgraph URLs) are **fixed for PGP chain** and must not be changed.\r
\r
3. **Install dependencies:**\r
   ```bash\r
   npm install\r
   ```\r
\r
4. **Ensure wallets are funded:**\r
   - **BTC wallet**: Must have enough mainnet BTC for collateral + miner fees.\r
   - **EVM wallet**: Must have PGA tokens for gas fees on PGP chain. To get PGA tokens, go to **https://swap.pgpgas.org** — you need USDT on BSC chain, bridge it to PGP, then swap for PGA tokens and/or BTCD.\r
\r
## CRITICAL: Check State Before Running\r
\r
**Before running any step**, always read `state/flow-state.json` to understand what has already been completed. This prevents catastrophic errors like double-locking BTC collateral.\r
\r
- If the `steps` object already has a completed entry for the step you're about to run, **do not re-run it**.\r
- If step `02-lock-btc-collateral` has a `btcTxId` but no `confirmations` (or `confirmations \x3C 3`), the BTC was already broadcast — re-running will **resume confirmation waiting**, not send a new transaction.\r
- If `02-lock-btc-collateral` shows `confirmations >= 3`, it is fully done — proceed to step 03.\r
\r
Example of a partially completed state (safe to resume step 02, do NOT re-run steps 00 or 01):\r
```json\r
{\r
  "steps": {\r
    "00-create-order": { "orderId": "0x...", "completedAt": "..." },\r
    "01-take-order": { "orderId": "0x...", "preImage": "...", "completedAt": "..." },\r
    "02-lock-btc-collateral": { "btcTxId": "abc...", "confirmations": 0 }\r
  }\r
}\r
```\r
\r
## Execution Steps\r
\r
Run each step **sequentially** from the scripts directory. Each step has interactive confirmation prompts (press `y` + Enter).\r
\r
```\r
Flow Progress:\r
- [ ] Step 0: Setup\r
- [ ] Step 1: Create Order\r
- [ ] Step 2: Take Order\r
- [ ] Step 3: Lock BTC Collateral\r
- [ ] Step 4: Submit BTC Proof\r
- [ ] Step 5: Claim BTCD Tokens  ← flow complete here\r
- [ ] Step 6: Repay Loan  ← ONLY when user explicitly requests\r
```\r
\r
### Step 0: Setup\r
```bash\r
npm run setup\r
```\r
Validates config, initializes wallets, checks EVM balance, creates `state/flow-state.json`.\r
\r
### Step 1: Create Order\r
```bash\r
npm run 00-create-order\r
```\r
Creates a lending order via the Issuer contract. Uses `LENDING_AMOUNT` and `LENDING_DAYS` from `.env`. Saves the **Order ID** to state.\r
\r
### Step 2: Take Order\r
```bash\r
npm run 01-take-order\r
```\r
Takes the order from Step 1. Generates a preImage, selects the best arbiter from the subgraph, and calls `takeOrder()`. Pays the arbiter's fee in native PGA tokens.\r
\r
### Step 3: Lock BTC Collateral\r
```bash\r
npm run 02-lock-btc\r
```\r
Sends BTC to the lock script address. **No interactive prompts** — the script is fully automated:\r
- Checks `state/flow-state.json` first. If a `btcTxId` already exists, it resumes confirmation waiting instead of sending new BTC.\r
- If already completed (`confirmations >= 3`), it skips entirely.\r
- Defaults to standard collateral amount (no staking discount).\r
- Broadcasts BTC tx and waits for **3 confirmations** (~30 min).\r
\r
Safe to re-run if interrupted — it will never double-send BTC.\r
\r
### Step 4: Submit BTC Proof\r
```bash\r
npm run 03-submit-proof\r
```\r
Generates ZKP proof from the BTC transaction and submits to the EVM order contract.\r
\r
**Skip `04-arbiter-fee`** — not needed.\r
\r
### Step 5: Claim BTCD Tokens\r
```bash\r
npm run 05-claim-btcd\r
```\r
Calls `borrow()` with the preImage from Step 2. BTCD tokens are minted to your EVM wallet.\r
\r
### Step 6: Repay Loan (ONLY when explicitly requested by user)\r
```bash\r
npm run 06-repay\r
```\r
Calculates repayment (principal + interest), approves BTCD, signs the BTC repayment transaction, and calls `repay()`.\r
\r
**DO NOT run this step automatically.** The flow is considered complete after Step 5 (Claim BTCD). Repaying the loan unlocks the BTC collateral and closes the position — only do this when the user explicitly asks to repay. Running it prematurely defeats the purpose of the collateralization.\r
\r
**Skip `07-unlock`** — not needed.\r
\r
## State Management\r
\r
State persists in `state/flow-state.json`. Each step reads from prior steps and writes its results.\r
\r
When Step 6 (Repay) completes, the state file is **automatically archived** to `state/flow-state-\x3Ctimestamp>.json` and removed, so the next run starts fresh. Archived files serve as a historical record of completed flows.\r
\r
| Step | Writes | Read By |\r
|------|--------|---------|\r
| 00-create-order | `orderId` | 01-take-order |\r
| 01-take-order | `orderId`, `preImage`, `btcAddress`, `btcPublicKey`, `arbiterAddress` | 02-lock-btc, 05-claim-btcd, 06-repay |\r
| 02-lock-btc | `btcTxId`, `scriptAddress`, `confirmations` | 03-submit-proof, 06-repay |\r
| 05-claim-btcd | `btcdReceived` | 06-repay |\r
\r
## Troubleshooting\r
\r
- **"Order status is X, expected Y"**: Steps must run in order. Check `state/flow-state.json`.\r
- **BTC confirmation timeout**: Re-run Step 3 — it detects the existing `btcTxId` and resumes waiting.\r
- **Insufficient PGA for gas**: Get PGA tokens from https://swap.pgpgas.org (USDT on BSC → bridge to PGP → swap for PGA).\r
- **Insufficient BTC**: Ensure BTC wallet has enough for collateral amount + miner fees.\r
- **Contract error on takeOrder**: Order may already be taken. Check order status on-chain.\r
- **Explorer**: PGP chain transactions can be viewed at `https://pgp.elastos.io/tx/\x3Chash>`.\r
\r
## PGP Chain Contract Addresses\r
\r
| Contract | Address |\r
|----------|---------|\r
| Loan Contract | `0x5cD194C9d34e5B9b7A0E5cBC64C93c1c9277891e` |\r
| Issuer | `0x91cf47c5d2b44Da124d4B54E9207aE6FB63D5Fa7` |\r
| BTCD Token | `0xF9BF836FEd97a9c9Bfe4D4c28316b9400C59Cc6B` |\r
\r
## Alternative RPC Endpoints\r
\r
| URL | Notes |\r
|-----|-------|\r
| `https://api.elastos.io/pg` | Primary (default) |\r
| `https://api2.elastos.io/pg` | Backup |\r
| `https://pgp-node.elastos.io` | Alternative |\r