souldinals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Souldinals Skill

Souldinals 工具

Manages Souldinals — soul.md files inscribed as child ordinals under a genesis parent inscription. A soul inscription records an agent's identity, values, and traits as Markdown on Bitcoin L1.

All write operations (

inscribe-soul

reveal-soul

) require an unlocked wallet with BTC balance on the SegWit address.

管理Souldinals——即作为创世父铭文下的子Ordinals铭刻的soul.md文件。灵魂铭文以Markdown格式在Bitcoin L1上记录Agent的身份、价值观和特征。

所有写入操作（

inscribe-soul

、

reveal-soul

）需要一个解锁的钱包，且SegWit地址上有BTC余额。

Usage

使用方法

bun run souldinals/souldinals.ts <subcommand> [options]

bun run souldinals/souldinals.ts <子命令> [选项]

Subcommands

子命令

inscribe-soul

Inscribe a soul.md file as a child inscription under a parent inscription — STEP 1: Broadcast commit transaction.

Reads the soul.md file, base64-encodes it, and broadcasts the commit transaction. After the commit confirms, call

reveal-soul

with the saved parameters to finalize the inscription.

bun run souldinals/souldinals.ts inscribe-soul \
  --parent-inscription-id <id> \
  [--soul-file ./SOUL.md] \
  [--fee-rate fast|medium|slow|<number>]

Options:

```
--parent-inscription-id
```
(required) — The genesis parent inscription ID (format:
```
{txid}i{index}
```
)
```
--soul-file
```
(optional) — Path to the soul.md file (default:
```
./SOUL.md
```
)
```
--fee-rate
```
(optional) —
```
fast
```
,
```
medium
```
,
```
slow
```
, or number in sat/vB (default:
```
medium
```
)

Requires: unlocked wallet with BTC balance.

Output:

json

{
  "status": "commit_broadcast",
  "message": "Soul commit transaction broadcast. Wait for confirmation, then call reveal-soul.",
  "commitTxid": "abc123...",
  "commitExplorerUrl": "https://mempool.space/tx/abc123...",
  "revealAddress": "bc1p...",
  "revealAmount": 3200,
  "commitFee": 1640,
  "feeRate": 8,
  "parentInscriptionId": "def456...i0",
  "soulFile": "./SOUL.md",
  "contentType": "text/markdown",
  "contentSize": 1024,
  "contentBase64": "...",
  "nextStep": "After commit confirms, call: bun run souldinals/souldinals.ts reveal-soul ..."
}

将soul.md文件作为父铭文下的子铭文铭刻——步骤1：广播提交交易。

读取soul.md文件，进行base64编码，然后广播提交交易。提交交易确认后，使用保存的参数调用

reveal-soul

以完成铭刻。

bun run souldinals/souldinals.ts inscribe-soul \
  --parent-inscription-id <id> \
  [--soul-file ./SOUL.md] \
  [--fee-rate fast|medium|slow|<数字>]

选项：

```
--parent-inscription-id
```
（必填）——创世父铭文ID（格式：
```
{txid}i{index}
```
）
```
--soul-file
```
（可选）——soul.md文件路径（默认：
```
./SOUL.md
```
）
```
--fee-rate
```
（可选）——
```
fast
```
、
```
medium
```
、
```
slow
```
，或以sat/vB为单位的数字（默认：
```
medium
```
）

要求：解锁且有BTC余额的钱包。

输出：

json

{
  "status": "commit_broadcast",
  "message": "Soul提交交易已广播。等待确认后，调用reveal-soul。",
  "commitTxid": "abc123...",
  "commitExplorerUrl": "https://mempool.space/tx/abc123...",
  "revealAddress": "bc1p...",
  "revealAmount": 3200,
  "commitFee": 1640,
  "feeRate": 8,
  "parentInscriptionId": "def456...i0",
  "soulFile": "./SOUL.md",
  "contentType": "text/markdown",
  "contentSize": 1024,
  "contentBase64": "...",
  "nextStep": "提交确认后，调用：bun run souldinals/souldinals.ts reveal-soul ..."
}

reveal-soul

Complete a soul inscription — STEP 2: Broadcast reveal transaction.

Call this AFTER the commit transaction from

inscribe-soul

has confirmed.

bun run souldinals/souldinals.ts reveal-soul \
  --commit-txid <txid> \
  --reveal-amount <satoshis> \
  --content-base64 <base64> \
  [--fee-rate fast|medium|slow|<number>]

Options:

```
--commit-txid
```
(required) — Transaction ID of the confirmed commit (64 hex chars)
```
--reveal-amount
```
(required) — Amount in the commit output in satoshis (from
```
inscribe-soul
```
response)
```
--content-base64
```
(required) — Base64-encoded soul.md content (from
```
inscribe-soul
```
response)
```
--fee-rate
```
(optional) — Fee rate for reveal tx (default:
```
medium
```
)

Requires: unlocked wallet.

Output:

json

{
  "status": "success",
  "message": "Soul inscription created successfully!",
  "inscriptionId": "def456...i0",
  "contentType": "text/markdown",
  "contentSize": 1024,
  "commit": {
    "txid": "abc123...",
    "explorerUrl": "https://mempool.space/tx/abc123..."
  },
  "reveal": {
    "txid": "def456...",
    "fee": 960,
    "explorerUrl": "https://mempool.space/tx/def456..."
  },
  "recipientAddress": "bc1p...",
  "note": "Soul inscription will appear at the recipient address once the reveal transaction confirms."
}

完成灵魂铭刻——步骤2：广播揭示交易。

需在

inscribe-soul

的提交交易确认后调用此命令。

bun run souldinals/souldinals.ts reveal-soul \
  --commit-txid <txid> \
  --reveal-amount <聪> \
  --content-base64 <base64> \
  [--fee-rate fast|medium|slow|<数字>]

选项：

```
--commit-txid
```
（必填）——已确认的提交交易ID（64位十六进制字符）
```
--reveal-amount
```
（必填）——提交输出中的金额，单位为聪（来自
```
inscribe-soul
```
的响应）
```
--content-base64
```
（必填）——base64编码的soul.md内容（来自
```
inscribe-soul
```
的响应）
```
--fee-rate
```
（可选）——揭示交易的费率（默认：
```
medium
```
）

要求：解锁的钱包。

输出：

json

{
  "status": "success",
  "message": "灵魂铭刻创建成功！",
  "inscriptionId": "def456...i0",
  "contentType": "text/markdown",
  "contentSize": 1024,
  "commit": {
    "txid": "abc123...",
    "explorerUrl": "https://mempool.space/tx/abc123..."
  },
  "reveal": {
    "txid": "def456...",
    "fee": 960,
    "explorerUrl": "https://mempool.space/tx/def456..."
  },
  "recipientAddress": "bc1p...",
  "note": "揭示交易确认后，灵魂铭文将出现在接收地址中。"
}

list-souls

List all soul inscriptions (text/markdown) owned by the wallet's Taproot address.

Queries the Unisat Ordinals API and filters for

text/markdown

content type.

bun run souldinals/souldinals.ts list-souls

Requires: unlocked wallet (for Taproot address).

Output:

json

{
  "address": "bc1p...",
  "count": 2,
  "souls": [
    {
      "id": "abc123...i0",
      "number": 78345,
      "contentType": "text/markdown",
      "contentLength": 1024,
      "timestamp": "2024-01-15T12:00:00.000Z",
      "genesisBlockHeight": 835000
    }
  ]
}

列出钱包Taproot地址下所有的灵魂铭文（text/markdown类型）。

查询Unisat Ordinals API并筛选

text/markdown

类型的内容。

bun run souldinals/souldinals.ts list-souls

要求：解锁的钱包（用于获取Taproot地址）。

输出：

json

{
  "address": "bc1p...",
  "count": 2,
  "souls": [
    {
      "id": "abc123...i0",
      "number": 78345,
      "contentType": "text/markdown",
      "contentLength": 1024,
      "timestamp": "2024-01-15T12:00:00.000Z",
      "genesisBlockHeight": 835000
    }
  ]
}

load-soul

Load and display the full content of the oldest soul inscription from the wallet.

Finds the oldest text/markdown inscription and fetches its content via the Unisat Ordinals API.

bun run souldinals/souldinals.ts load-soul

Requires: unlocked wallet (for Taproot address).

Output:

json

{
  "inscriptionId": "abc123...i0",
  "contentType": "text/markdown",
  "contentSize": 1024,
  "timestamp": "2024-01-15T12:00:00.000Z",
  "content": "# My Soul\n\n..."
}

加载并展示钱包中最早的灵魂铭文的完整内容。

查找最早的text/markdown类型铭文，并通过Unisat Ordinals API获取其内容。

bun run souldinals/souldinals.ts load-soul

要求：解锁的钱包（用于获取Taproot地址）。

输出：

json

{
  "inscriptionId": "abc123...i0",
  "contentType": "text/markdown",
  "contentSize": 1024,
  "timestamp": "2024-01-15T12:00:00.000Z",
  "content": "# My Soul\n\n..."
}

display-soul

Parse and display soul traits from a specific inscription by ID.

Fetches inscription content and parses Markdown sections to extract identity traits: name, description, values, focus areas, and custom sections.

bun run souldinals/souldinals.ts display-soul --inscription-id <id>

Options:

```
--inscription-id
```
(required) — Inscription ID (format:
```
{txid}i{index}
```
)

Output:

json

{
  "inscriptionId": "abc123...i0",
  "contentType": "text/markdown",
  "traits": {
    "name": "...",
    "description": "...",
    "values": ["..."],
    "focusAreas": ["..."],
    "sections": {
      "Identity": "...",
      "Values": "..."
    }
  },
  "rawContent": "# Soul\n\n..."
}

通过铭文ID解析并展示特定铭文的灵魂特征。

获取铭文内容并解析Markdown章节，提取身份特征：名称、描述、价值观、关注领域和自定义章节。

bun run souldinals/souldinals.ts display-soul --inscription-id <id>

选项：

```
--inscription-id
```
（必填）——铭文ID（格式：
```
{txid}i{index}
```
）

输出：

json

{
  "inscriptionId": "abc123...i0",
  "contentType": "text/markdown",
  "traits": {
    "name": "...",
    "description": "...",
    "values": ["..."],
    "focusAreas": ["..."],
    "sections": {
      "Identity": "...",
      "Values": "..."
    }
  },
  "rawContent": "# Soul\n\n..."
}

Two-Step Soul Inscription Workflow

两步式灵魂铭刻流程

bash

undefined

bash

undefined

Step 1: Broadcast commit (soul.md defaults to ./SOUL.md)

步骤1：广播提交（soul.md默认使用./SOUL.md）

bun run souldinals/souldinals.ts inscribe-soul
--parent-inscription-id <genesisInscriptionId>

Save: commitTxid, revealAmount, contentBase64

保存：commitTxid、revealAmount、contentBase64

Wait for commit to confirm (check mempool.space)

等待提交交易确认（可在mempool.space查看）

Step 2: Reveal (finalizes inscription)

步骤2：揭示（完成铭刻）

bun run souldinals/souldinals.ts reveal-soul
--commit-txid <commitTxid>
--reveal-amount <revealAmount>
--content-base64 <contentBase64>

undefined

bun run souldinals/souldinals.ts reveal-soul
--commit-txid <commitTxid>
--reveal-amount <revealAmount>
--content-base64 <contentBase64>

undefined

Notes

注意事项

inscribe-soul

and

reveal-soul

require a wallet unlocked via

bun run wallet/wallet.ts unlock

The wallet must have BTC balance on the SegWit (bc1q/tb1q) address for funding
Soul inscriptions are received at the Taproot (bc1p/tb1p) address
The
```
--parent-inscription-id
```
binds the soul as a child in the Souldinals collection
```
list-souls
```
,
```
load-soul
```
, and
```
display-soul
```
use the Unisat Ordinals API (set
```
UNISAT_API_KEY
```
env var for higher rate limits; free tier: 5 req/s)

inscribe-soul

和

reveal-soul

需要通过

bun run wallet/wallet.ts unlock

解锁钱包

钱包的SegWit（bc1q/tb1q）地址必须有BTC余额用于交易资金
灵魂铭文将被接收至Taproot（bc1p/tb1p）地址
```
--parent-inscription-id
```
将灵魂绑定为Souldinals集合中的子铭文
```
list-souls
```
、
```
load-soul
```
和
```
display-soul
```
使用Unisat Ordinals API（设置
```
UNISAT_API_KEY
```
环境变量可获得更高请求速率限制；免费层：5次请求/秒）