Advancing blocks

Some contract logic depends on time: PoX cycles, unlock heights, time-locked redemptions, bridge finalization, oracle freshness. The AdvanceBlocks step adds bitcoin (burn) blocks and Stacks blocks on top of a simulation's fork, so you can step past those boundaries inside one session.

The step

{ "AdvanceBlocks": { "bitcoin_blocks": 2, "stacks_blocks_per_bitcoin": 1 } }

Field	Required	Meaning
bitcoin_blocks	yes	Burn blocks to add. May be 0 only with stacks_blocks_per_bitcoin > 0, which adds Stacks blocks to the current tenure.
stacks_blocks_per_bitcoin	yes	Stacks blocks per burn block; at least 1 when bitcoin_blocks > 0.
bitcoin_interval_secs	no	Burn block time step, default 600.
burn_header_hashes	no	Override the header hash of burn block i (0-based within this step), 32-byte hex.
pox_addrs	no	Override PoX payout addresses and amount per burn block.
vrf_seeds	no	Override the VRF seed per burn block, 32-byte hex.

The result lists each new block. From a real session forked at Stacks block 1044660:

{
  "AdvanceBlocks": {
    "Ok": [
      { "stacks_height": 1044661, "burn_height": 894279, "coinbase_height": 194338,
        "block_time": 1745816675, "burn_block_time": 1745816675, "tenure_change": true,
        "index_block_hash": "92dc00f6…", "burn_header_hash": "d46c59da…", "vrf_seed": "1dd053c2…" },
      { "stacks_height": 1044662, "burn_height": 894280, "coinbase_height": 194339,
        "block_time": 1745817275, "burn_block_time": 1745817275, "tenure_change": true, "…": "…" }
    ]
  }
}

Later steps run at the new tip, so height- and time-dependent Clarity (burn-block-height, get-burn-block-info? and so on) sees the advanced chain.

The session tip

GET /devtools/v2/simulations/{id}/tip returns where the session is now. After an AdvanceBlocks step it is the last synthetic block ("synthetic": true, with vrf_seed and tenure_change); before, it is the fork point ("synthetic": false).

{ "synthetic": true, "stacks_height": 1044662, "burn_height": 894280, "coinbase_height": 194339,
  "block_time": 1745817275, "burn_block_time": 1745817275, "epoch": "3.1", "tenure_change": true, "…": "…" }

With the SDK

import { SimulationBuilder, getSimulationTip } from 'stxer'

const id = await SimulationBuilder.new()
  .withSender('SP…')
  .addContractCall({ /* request a redemption */ })
  .addAdvanceBlocks({ bitcoin_blocks: 144, stacks_blocks_per_bitcoin: 1 }) // about one day
  .addContractCall({ /* claim after the lock */ })
  .run()

const tip = await getSimulationTip(id)
console.log(tip.synthetic, tip.burn_height)

A tip: to learn the parent burn height before computing how many blocks you need, advance with bitcoin_blocks: 0, stacks_blocks_per_bitcoin: 1 first and read the tip.

Worked scenarios (locked STX unlock, sBTC deposit, BTC peg-in, vault cooldowns) are in the SDK's samples on GitHub.