child-inscription

# Child Inscription Skill Creates parent-child Ordinals inscriptions per the [Ordinals provenance spec](https://docs.ordinals.com/inscriptions/provenance.html). The inscription owner spends the parent UTXO in the reveal transaction, embedding a pointer that establishes on-chain provenance for the child. - **estimate** — Read-only fee calculation, no wallet required. - **inscribe** — Step 1 commit transaction, requires an unlocked wallet with BTC. - **reveal** — Step 2 reveal transaction, requires the commit tx to be confirmed. ## Usage ``` bun run child-inscription/child-inscription.ts <subcommand> [options] ``` ## Subcommands ### estimate Calculate the total cost (commit fee + reveal amount) for a child inscription without broadcasting anything. ``` bun run child-inscription/child-inscription.ts estimate \ --parent-id <inscription-id> \ --content-type <mime> \ --content <string> ``` Options: - `--parent-id` (required) — Parent inscription ID, e.g. `abc123...i0` - `--content-type` (required) — MIME type, e.g. `text/plain` or `image/png` - `--content` (required) — Content as a UTF-8 string (base64-encoded internally) - `--fee-rate` (optional) — Fee rate in sat/vB; defaults to current mempool medium fee Output: ```json { "parentId": "abc123...i0", "contentType": "text/plain", "contentSize": 42, "feeRate": 12, "fees": { "commitFee": 1440, "revealFee": 2100, "revealAmount": 3394, "totalCost": 4834 }, "breakdown": "Commit tx: 1440 sats | Reveal amount: 3394 sats (includes 2100 reveal fee) | Total: 4834 sats" } ``` ### inscribe Broadcast the commit transaction (Step 1). The commit locks funds into a pay-to-taproot address encoding the inscription script. After this confirms, run `reveal`. ``` bun run child-inscription/child-inscription.ts inscribe \ --parent-id <inscription-id> \ --content-type <mime> \ --content <string> \ [--fee-rate <sats-per-vbyte>] ``` Options: - `--parent-id` (required) — Parent inscription ID. Your wallet must own this inscription (verified on-chain). - `--content-type` (required) — MIME type of the child content. - `--content` (required) — Child content as a UTF-8 string. - `--fee-rate` (optional) — Fee rate: `fast`, `medium`, `slow`, or an integer in sat/vB (default: `medium`). Output: ```json { "status": "commit_broadcast", "commitTxid": "deadbeef...", "commitExplorerUrl": "https://mempool.space/tx/deadbeef...", "revealAddress": "bc1p...", "revealAmount": 3394, "commitFee": 1440, "feeRate": 12, "parentInscriptionId": "abc123...i0", "contentType": "text/plain", "contentSize": 42, "nextStep": "After commit confirms, call reveal with commitTxid and revealAmount from this response." } ``` ### reveal Broadcast the reveal transaction (Step 2). This spends the commit output and the parent UTXO simultaneously, creating the child inscription and returning the parent to your address. **Wait for the commit tx to confirm before calling this.** ``` bun run child-inscription/child-inscription.ts reveal \ --commit-txid <txid> \ --vout <num> ``` Options: - `--commit-txid` (required) — Txid of the confirmed commit transaction (from the `inscribe` step). - `--vout` (required) — Output index of the commit transaction (almost always `0`). Note: Content, content-type, parent-id, and reveal-amount are read from the `.child-inscription-state.json` file written by the `inscribe` subcommand. Output: ```json { "status": "success", "inscriptionId": "revealthash...i0", "parentInscriptionId": "abc123...i0", "contentType": "text/plain", "contentSize": 42, "commit": { "txid": "deadbeef...", "explorerUrl": "https://mempool.space/tx/deadbeef..." }, "reveal": { "txid": "revealthash...", "fee": 2100, "explorerUrl": "https://mempool.space/tx/revealthash..." }, "recipientAddress": "bc1p..." } ``` ## Notes - Always run `estimate` first to understand total cost before committing funds. - The `inscribe` subcommand writes a `.child-inscription-state.json` file in the current working directory. Do not delete it before running `reveal`. - The parent inscription must remain at your Taproot address between the `inscribe` and `reveal` steps. Do not transfer the parent during this window. - Content is encoded as UTF-8 and base64-encoded before being passed to the MCP tool. Binary content (images etc.) should be supplied pre-encoded. - Wallet operations require an unlocked wallet (`bun run wallet/wallet.ts unlock` first). - All operations target Bitcoin mainnet by default (controlled by the `NETWORK` environment variable).