stacking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stacking Skill

Stacking 技能

Provides Proof of Transfer (PoX) stacking operations on the Stacks blockchain. Stacking locks STX tokens for a specified number of reward cycles to earn Bitcoin rewards.

get-pox-info and get-stacking-status — Read-only, no wallet required.
stack-stx and extend-stacking — Write operations, require an unlocked wallet.

在 Stacks 区块链上提供 Proof of Transfer（PoX）质押操作。质押是指将 STX 代币锁定指定数量的奖励周期，以赚取 BTC 奖励。

get-pox-info 和 get-stacking-status — 只读操作，无需钱包。
stack-stx 和 extend-stacking — 写入操作，需要解锁的钱包。

Usage

使用方法

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

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

Subcommands

子命令

get-pox-info

Get current Proof of Transfer (PoX) cycle information, including current and next cycle details, minimum stacking amount, and cycle lengths.

bun run stacking/stacking.ts get-pox-info

Output:

json

{
  "network": "testnet",
  "currentCycle": {
    "id": 88,
    "min_threshold_ustx": 50000000000,
    "stacked_ustx": 1200000000000,
    "is_pox_active": true
  },
  "nextCycle": {
    "id": 89,
    "min_threshold_ustx": 50000000000,
    "min_increment_ustx": 5000000000,
    "stacked_ustx": 0,
    "prepare_phase_start_block_height": 3450,
    "blocks_until_prepare_phase": 25,
    "reward_phase_start_block_height": 3500,
    "blocks_until_reward_phase": 75,
    "ustx_until_pox_rejection": 0
  },
  "minAmountUstx": 50000000000,
  "rewardCycleLength": 2100,
  "prepareCycleLength": 100,
  "currentBurnchainBlockHeight": 3425,
  "totalLiquidSupplyUstx": 1400000000000000
}

获取当前 Proof of Transfer（PoX）周期信息，包括当前和下一周期的详情、最低质押金额以及周期时长。

bun run stacking/stacking.ts get-pox-info

输出：

json

{
  "network": "testnet",
  "currentCycle": {
    "id": 88,
    "min_threshold_ustx": 50000000000,
    "stacked_ustx": 1200000000000,
    "is_pox_active": true
  },
  "nextCycle": {
    "id": 89,
    "min_threshold_ustx": 50000000000,
    "min_increment_ustx": 5000000000,
    "stacked_ustx": 0,
    "prepare_phase_start_block_height": 3450,
    "blocks_until_prepare_phase": 25,
    "reward_phase_start_block_height": 3500,
    "blocks_until_reward_phase": 75,
    "ustx_until_pox_rejection": 0
  },
  "minAmountUstx": 50000000000,
  "rewardCycleLength": 2100,
  "prepareCycleLength": 100,
  "currentBurnchainBlockHeight": 3425,
  "totalLiquidSupplyUstx": 1400000000000000
}

get-stacking-status

Check if an address is currently stacking STX.

bun run stacking/stacking.ts get-stacking-status [--address <addr>]

Options:

```
--address
```
(optional) — Stacks address to check (uses active wallet if omitted)

Output:

json

{
  "address": "SP2...",
  "network": "testnet",
  "stacked": true,
  "amountMicroStx": "100000000000",
  "amountStx": "100000",
  "firstRewardCycle": 85,
  "lockPeriod": 3,
  "unlockHeight": 6300
}

检查某个地址当前是否正在质押 STX。

bun run stacking/stacking.ts get-stacking-status [--address <addr>]

选项：

```
--address
```
（可选）—— 要检查的 Stacks 地址（若省略则使用当前活跃钱包）

输出：

json

{
  "address": "SP2...",
  "network": "testnet",
  "stacked": true,
  "amountMicroStx": "100000000000",
  "amountStx": "100000",
  "firstRewardCycle": 85,
  "lockPeriod": 3,
  "unlockHeight": 6300
}

stack-stx

Lock STX tokens to earn Bitcoin rewards via Proof of Transfer. Requires an unlocked wallet with sufficient STX.

The Bitcoin reward address must be provided as a version byte and hash. For P2PKH (legacy Bitcoin address), version is

. For P2SH, version is

. For P2WPKH (native SegWit), version is

bun run stacking/stacking.ts stack-stx \
  --amount <microStx> \
  --pox-address-version <version> \
  --pox-address-hashbytes <hex> \
  --start-burn-height <btcBlockHeight> \
  --lock-period <cycles>

Options:

```
--amount
```
(required) — Amount of STX to stack in micro-STX (1 STX = 1,000,000 micro-STX). Must meet the minimum stacking threshold.
```
--pox-address-version
```
(required) — Bitcoin address version byte:
```
0
```
(P2PKH),
```
1
```
(P2SH),
```
4
```
(P2WPKH),
```
5
```
(P2WSH),
```
6
```
(P2TR)
```
--pox-address-hashbytes
```
(required) — Bitcoin address hash bytes as a hex string (20 bytes for P2PKH/P2SH/P2WPKH, 32 bytes for P2WSH/P2TR)
```
--start-burn-height
```
(required) — Bitcoin block height at which stacking begins (must be in a prepare phase or the first block of a reward phase)
```
--lock-period
```
(required) — Number of reward cycles to lock STX (1–12)

Output:

json

{
  "success": true,
  "txid": "abc123...",
  "stacker": "SP2...",
  "amount": "100000000000",
  "lockPeriod": 3,
  "startBurnHeight": 850000,
  "network": "testnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=testnet"
}

通过 Proof of Transfer 锁定 STX 代币以赚取 BTC 奖励。需要有足够 STX 的解锁钱包。

BTC 奖励地址必须以版本字节和哈希的形式提供。对于 P2PKH（传统 BTC 地址），版本为

；对于 P2SH，版本为

；对于 P2WPKH（原生隔离见证），版本为

。

bun run stacking/stacking.ts stack-stx \
  --amount <microStx> \
  --pox-address-version <version> \
  --pox-address-hashbytes <hex> \
  --start-burn-height <btcBlockHeight> \
  --lock-period <cycles>

选项：

```
--amount
```
（必填）—— 要质押的 STX 数量，单位为 micro-STX（1 STX = 1,000,000 micro-STX）。必须满足最低质押门槛。
```
--pox-address-version
```
（必填）—— BTC 地址版本字节：
```
0
```
（P2PKH）、
```
1
```
（P2SH）、
```
4
```
（P2WPKH）、
```
5
```
（P2WSH）、
```
6
```
（P2TR）
```
--pox-address-hashbytes
```
（必填）—— BTC 地址哈希字节，以十六进制字符串形式提供（P2PKH/P2SH/P2WPKH 为20字节，P2WSH/P2TR为32字节）
```
--start-burn-height
```
（必填）—— 质押开始的 BTC 区块高度（必须处于当前 PoX 周期的准备阶段或奖励阶段的第一个区块）
```
--lock-period
```
（必填）—— STX 锁定的奖励周期数（1–12）

输出：

json

{
  "success": true,
  "txid": "abc123...",
  "stacker": "SP2...",
  "amount": "100000000000",
  "lockPeriod": 3,
  "startBurnHeight": 850000,
  "network": "testnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=testnet"
}

extend-stacking

Extend an existing stacking lock period by additional reward cycles. Must already be stacking. Requires an unlocked wallet.

bun run stacking/stacking.ts extend-stacking \
  --extend-count <cycles> \
  --pox-address-version <version> \
  --pox-address-hashbytes <hex>

Options:

```
--extend-count
```
(required) — Number of additional reward cycles to lock (1–12)
```
--pox-address-version
```
(required) — Bitcoin address version byte (same as used when initially stacking)
```
--pox-address-hashbytes
```
(required) — Bitcoin address hash bytes as a hex string (same as used when initially stacking)

Output:

json

{
  "success": true,
  "txid": "abc123...",
  "stacker": "SP2...",
  "extendCount": 2,
  "network": "testnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=testnet"
}

通过额外的奖励周期延长现有质押锁定期。必须处于已质押状态，且需要解锁的钱包。

bun run stacking/stacking.ts extend-stacking \
  --extend-count <cycles> \
  --pox-address-version <version> \
  --pox-address-hashbytes <hex>

选项：

```
--extend-count
```
（必填）—— 额外锁定的奖励周期数（1–12）
```
--pox-address-version
```
（必填）—— BTC 地址版本字节（与初始质押时使用的版本相同）
```
--pox-address-hashbytes
```
（必填）—— BTC 地址哈希字节，以十六进制字符串形式提供（与初始质押时使用的哈希相同）

输出：

json

{
  "success": true,
  "txid": "abc123...",
  "stacker": "SP2...",
  "extendCount": 2,
  "network": "testnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=testnet"
}

Notes

注意事项

The minimum stacking amount varies by cycle. Use
```
get-pox-info
```
to check
```
minAmountUstx
```
before calling
```
stack-stx
```
.
Bitcoin reward addresses are specified as version + hashbytes (raw hash, not base58check encoded). To derive these from a Bitcoin address, use a library or the
```
wallet
```
skill's
```
get-taproot-address
```
for Taproot addresses.
```
lock-period
```
of 1–12 cycles is valid. Each cycle is typically ~2 weeks on mainnet.

start-burn-height

must fall within the prepare phase of the current PoX cycle. Check

nextCycle.prepare_phase_start_block_height

from

get-pox-info

Wallet operations require an unlocked wallet (use
```
bun run wallet/wallet.ts unlock
```
first).

最低质押金额会随周期变化。在调用
```
stack-stx
```
前，请使用
```
get-pox-info
```
检查
```
minAmountUstx
```
。
BTC 奖励地址以版本+哈希字节的形式指定（原始哈希，非 base58check 编码）。要从 BTC 地址推导这些信息，可以使用相关库，或针对 Taproot 地址使用
```
wallet
```
技能的
```
get-taproot-address
```
功能。
```
lock-period
```
支持1–12个周期。主网上每个周期通常约为2周。
```
start-burn-height
```
必须落在当前 PoX 周期的准备阶段内。请从
```
get-pox-info
```
的
```
nextCycle.prepare_phase_start_block_height
```
信息中确认。
钱包操作需要解锁钱包（先使用
```
bun run wallet/wallet.ts unlock
```
）。