Stacks

Skill is based on Stacks blockchain (stacks-node v3.3.0.0.5), generated 2026-02-24. Docs: sources/stacks/docs/, docs.stacks.co

Stacks is a layer-2 blockchain anchored to Bitcoin security, using Proof of Transfer (PoX) for mining and Clarity for smart contracts. This skill covers the reference node (stacks-node): RPC endpoints, testnet tx flow, mining config, event observer, SIPs, property testing, release/branching, profiling, init/service, and CI.

Core References

Features

Best Practices

Advanced

External Links

• Stacks docs
• Stacks blockchain (GitHub)
• SIPs (stacksgov/sips)

Generation Info

• Source: sources/stacks (https://github.com/stacks-network/stacks-blockchain)
• Git SHA: 1208ed33008c77c53d45e08ab914449d807bb713
• Generated: 2026-02-24
• Docs used: docs/testnet.md, docs/rpc-endpoints.md, docs/mining.md, docs/event-dispatcher.md, docs/SIPS.md, docs/init.md, docs/release-process.md, docs/property-testing.md, docs/profiling.md, docs/ci-workflow.md, docs/branching.md, README.md

CI Workflow

Releases are built via the CI GitHub Actions workflow (.github/workflows/ci.yml): format check, integration and unit tests, binary archives with checksums, and Docker image publish.

Triggers and artifacts

• Push to branch (no tag): No workflow by default; PR open/reopen/sync produces amd64 Docker image stacks-core:<branch-name> and stacks-core:<pr-number>.
• Run on release branch release/X.Y.Z.A.n: GitHub Release with binary archives (multi-arch), checksum file, tag X.Y.Z.A.n, Docker tags stacks-core:latest, stacks-core:X.Y.Z.A.n, -debian/-alpine variants.

Caching uses commit SHA; Nextest runs tests from cached build archives with partitioning for speed.

Test organization

Tests are split into workflows (e.g. Stacks Core Tests, Bitcoin Tests, Atlas, Epoch, P2P, Slow Tests). Matrix is used for a fixed set of jobs; nextest partitioning for large sets (e.g. unit tests). Slow tests (>10 min or flaky) go in Slow Tests workflow.

Adding a test: Add the test name to the appropriate workflow matrix (e.g. in atlas-tests.yml: matrix.test-name). New workflows can be added per test type.

Standalone and check-jobs-status

Standalone Tests is manually triggered; you select which test set runs (e.g. Epoch Tests, Release Tests). To require multiple jobs (e.g. all unit-test partitions + other jobs) in a ruleset, use the check-jobs-status action in a separate job that depends on those jobs and add that job as required.

<!-- Source references:

• sources/stacks/docs/ci-workflow.md
• https://github.com/stacks-network/stacks-blockchain
• https://github.com/stacks-network/actions

-->

Profiling Stacks-Node and Mining

Techniques to find performance bottlenecks in the mining loop and node: config validation, debug logging, mock miner, event recording, historical mining, and CPU/SQLite profiling.

Config and logging

Validate config:

cargo run -r -p stacks-node --bin stacks-node check-config --config ./sample/conf/mainnet-follower-conf.toml

Debug logging: STACKS_LOG_DEBUG=1. JSON logging: STACKS_LOG_JSON=1 with feature slog_json.

Mock miner and events

• Set STACKS_DIR, STACKS_WORKING_DIR, STACKS_SNAPSHOT_DIR.
• Download Hiro mainnet archive; extract to working dir. Run node with mainnet-mockminer-conf.toml; $STACKS_WORKING_DIR overrides config working dir.
• Run stacks-events to receive events, then start node with event observer (e.g. STACKS_EVENT_OBSERVER=localhost:3700). Archive events to a log file for replay.

Historical mining (tip-mine)

Snapshot working dir, then run tip-mine benchmark:

export STACKS_TIP_MINE_BLOCK_HEIGHT=71294
export STACKS_TIP_MINE_NUM_TXS=100
cargo run -F disable-costs -r --bin stacks-inspect tip-mine $STACKS_SNAPSHOT_DIR $STACKS_DIR/events.log $STACKS_TIP_MINE_BLOCK_HEIGHT $STACKS_TIP_MINE_NUM_TXS

Use disable-costs to ignore block cost limits. Build once then run the binary directly for faster iteration.

Flame graphs

• Mac: Install flamegraph; use DTrace:

flamegraph --root -o perf.svg -e cpu-clock --min-width 1 --deterministic -- ./target/release/stacks-inspect tip-mine ...

• Linux: Use perf (flamegraph-rs). If system perf is slow, build perf from kernel tree; set PERF=~/linux/tools/perf/perf when invoking flamegraph. May need linker = "clang" and lld flags in .cargo/config.toml (see flamegraph-rs docs).

SQLite profiling

Enable SQLite trace with feature profile-sqlite and debug logging:

STACKS_LOG_DEBUG=1 cargo run -F profile-sqlite,disable-costs -r --bin stacks-inspect try-mine $STACKS_WORKING_DIR

Log lines include query text and millis.

<!-- Source references:

• sources/stacks/docs/profiling.md
• https://github.com/stacks-network/stacks-blockchain

-->

Stacks RPC Endpoints

The stacks-node exposes HTTP RPC for posting transactions, querying accounts/contracts, and fetching blocks. Base path is typically the node's RPC bind (e.g. http://localhost:20443).

Posting transactions

POST /v2/transactions — Submit raw transaction bytes to the mempool (body: application/octet-stream). Rejections return 400 with JSON:

{
  "error": "transaction rejected",
  "reason": "BadNonce",
  "reason_data": { "actual": 3, "expected": 0, "is_origin": true, "principal": "ST2MVN..." },
  "txid": "0x..."
}

Common reason values: Serialization, Deserialization, SignatureValidation, BadNonce, FeeTooLow, NotEnoughFunds, NoSuchContract, NoSuchPublicFunction, BadFunctionArgument, ContractAlreadyExists, ServerFailureDatabase, ServerFailureOther. Use reason_data when present for details.

Accounts and contract data

• GET /v2/accounts/[Principal] — Balance (hex), nonce, optional balance_proof/nonce_proof. Use ?proof=0 to omit proofs. Principal is Stacks address or contract id (e.g. SP...contract-name).
• GET /v2/data_var/[Address]/[Contract]/[VarName] — Data variable value (hex) and optional proof.
• GET /v2/map_entry/[Address]/[Contract]/[MapName] — POST with body = hex-serialized Clarity key (JSON string). Returns serialized option (none or some).
• GET /v2/constant_val/[Address]/[Contract]/[ConstantName] — Constant value (hex).
• GET /v2/clarity/marf/[MARF Key] — Raw MARF key value.
• GET /v2/clarity/metadata/[Address]/[Contract]/[MetadataKey] — Contract metadata (JSON string in data).
• GET /v2/fees/transfer — Estimated fee rate (integer) for STX transfer.

Contract interface and read-only calls

• GET /v2/contracts/interface/[Address]/[Contract] — Contract ABI: functions, variables, maps, fungible_tokens, non_fungible_tokens.
• GET /v2/contracts/source/[Address]/[Contract] — Source code, publish_height, optional proof. ?proof=0 to skip proof.
• POST /v2/contracts/call-read/[Address]/[Contract]/[FunctionName] — Simulate read-only function. Body:

  { "sender": "SP...contract.get-info", "arguments": ["0x0011...", "0x00231..."] }

Returns { "okay": true, "result": "0x..." } or { "okay": false, "cause": "..." }.

• GET /v2/traits/[Address]/[Contract]/[TraitAddress]/[TraitContract]/[TraitName] — Trait implementation check.

Blocks and headers (v2)

• GET /v2/pox — Current PoX-related info (see OpenAPI spec).
• GET /v2/headers/[Count] — Ancestral Stacks block headers (newest first). Optional ?tip=<block_id>. Up to 2100 per request; use parent_block_id from last header to page. Returns consensus_hash, header (hex), parent_block_id.

Nakamoto (v3) and miner

• POST /v3/block_proposal — Miner-only (loopback). Submit NakamotoBlockProposal (block + chain_id). Response is async via event observer /proposal_response (Ok with block hex and cost, or Reject with reason/reason_code).
• GET /v3/blocks/[Block ID] — Raw Nakamoto block by ID. 404 if missing.
• GET /v3/blocks/height/[Height] — Block by height. Optional ?tip= for non-canonical tip.
• GET /v3/tenures/[Block ID] — Block and ancestors in same tenure (concatenated raw blocks, up to 2 MB).
• GET /v3/tenures/info — Highest-known tenure: consensus_hash, reward_cycle, tip_block_id, tip_height.
• GET /v3/signer/[Signer Pubkey]/[Reward Cycle] — Number of blocks signed by signer in that cycle.
• GET /v3/transaction/[Txid] — Index block hash, tx body (hex), result. Requires txindex. 404 if not found, 501 if txindex disabled.
• GET /v3/health — Sync health: current tip height vs max peer tip; use difference_from_max_peer to decide if out of sync.

Usage tips

• Principals: Stacks address (e.g. ST2..., SP2...) or contract id {address}.{contract-name}.
• Proofs: omit with ?proof=0 when not needed for verification.
• Map keys: POST body must be hex serialization of the Clarity key (JSON string atom).

<!-- Source references:

• sources/stacks/docs/rpc-endpoints.md
• https://github.com/stacks-network/stacks-blockchain

-->

Testnet and Transaction Flow

Use testnet config (e.g. testnet-follower-conf.toml) and grant genesis balances via [[ustx_balance]] (address + amount in microSTX). Encode and sign transactions with blockstack-cli, then submit via POST /v2/transactions.

Generate keypair and sign

cargo run --bin blockstack-cli generate-sk --testnet
# Output: secretKey, publicKey, stacksAddress

Register the address in testnet config if using genesis balance. Signing uses the secret key (hex).

Publish a contract

cargo run --bin blockstack-cli publish <secret_key> <fee_microstx> <nonce> <contract_name> <path/to/contract.clar> --testnet

Fee must cover at least 1 microSTX per byte; nonce must increase per sender. Pipe binary output to file then POST:

cargo run --bin blockstack-cli publish <sk> 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin
curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions

Contract call (read/write)

cargo run --bin blockstack-cli contract-call <secret_key> <fee> <nonce> <sender_address> <contract_name> <function_name> -e \"arg1\" -e \"arg2\" --testnet

Example: call get-value with key foo, then set-value key foo value bar, then get-value again (nonces 1, 2, 3):

# get-value "foo"
cargo run --bin blockstack-cli contract-call <sk> 500 1 <sender> kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin
# set-value "foo" "bar"
cargo run --bin blockstack-cli contract-call <sk> 500 2 <sender> kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin
# get-value "foo" again
cargo run --bin blockstack-cli contract-call <sk> 500 3 <sender> kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin

Submit each with the same curl pattern to the node's /v2/transactions.

Key points

• Nonce must be monotonic per principal; get current nonce from GET /v2/accounts/[principal].
• Testnet node must be running and config must include the sender in [[ustx_balance]] if using genesis funding.
• Contract identifier on chain is {deployer_address}.{contract_name}; use that for call-read and map_entry.

<!-- Source references:

• sources/stacks/docs/testnet.md
• https://github.com/stacks-network/stacks-blockchain

-->

Event Observer (Dispatcher)

Configure one or more [[events_observer]] entries in the node config. The node POSTs JSON payloads to the given endpoint for subscribed events.

Config

[[events_observer]]
endpoint = "listener:3700"
events_keys = ["*"]      # or specific keys (see below)
timeout_ms = 5000        # optional, default 1000
disable_retries = false # optional

Invalid events_keys cause startup panic. All observers implicitly receive /attachments/new for new AtlasDB attachments.

Event keys and endpoints

Payload summary

• POST /new_block — Block hash/height, parent hashes, transactions array, events (filtered), matured_miner_rewards, cost aggregates. Tx with raw_tx: "0x00" is a burnchain op; see burnchain_op (e.g. transfer_stx, stack_stx, delegate_stx, pre_stx, vote_for_aggregate_key).
• POST /new_burn_block — burn_block_hash, consensus_hash, burn_block_height, reward_recipients, reward_slot_holders, burn_amount.
• POST /new_mempool_tx — JSON array of hex-encoded raw transactions.
• POST /drop_mempool_tx — dropped_txids, reason (e.g. ReplaceByFee, ReplaceAcrossFork, TooExpensive, StaleGarbageCollect), optional replacement txid.
• POST /stackerdb_chunks — contract_id, modified_slots (slot_id, slot_version, signature, data).
• POST /attachments/new — Array of attachment objects (attachment_index, index_block_hash, block_height, content_hash, contract_id, metadata, tx_id, content).
• POST /proposal_response — result: Ok (block hex, cost, size) or Reject (reason, reason_code).

Key points

• Microblock events are only supported until epoch 2.5.
• Subscribe to specific contract/asset keys to reduce payload size.
• Block proposal responses are async: submit via POST /v3/block_proposal and receive result on observer /proposal_response.

<!-- Source references:

• sources/stacks/docs/event-dispatcher.md
• https://github.com/stacks-network/stacks-blockchain

-->

Stacks Mining (PoX)

STX are mined via Proof of Transfer (PoX): miners commit BTC on the burnchain to participate in leader election. Configure [node] and [miner] / [burnchain] in the node config (e.g. mainnet-miner-conf.toml).

Node and miner config

[node]
miner = true
seed = "YOUR_BITCOIN_PRIVATE_KEY"
# mock_mining = true   # Test without spending BTC (requires miner = true)

[miner]
nakamoto_attempt_time_ms = 20000

[burnchain]
burn_fee_cap = 20000           # Max sats for burn commitment
satoshis_per_byte = 50         # Fee rate for Bitcoin tx
rbf_fee_increment = 5         # Sats per byte when RBF'ing
max_rbf = 150                 # Max % of satoshis_per_byte for RBF

RBF (Replace-by-Fee) is important: if the miner cannot replace an outdated commit with a higher-fee tx, it may build on the wrong tenure and have blocks rejected. Allow at least a few fee increments within max_rbf.

Verify miner is running

Check logs for UTXO discovery:

grep -i utxo /path/to/node/logs
# Expect: "Miner node: checking UTXOs at address: ..." then "UTXOs found - will run as a Miner node"

Fee and cost estimation

Optional [fee_estimation] section (non–consensus-critical):

[fee_estimation]
cost_estimator = naive_pessimistic
fee_estimator = fuzzed_weighted_median_fee_rate
fee_rate_fuzzer_fraction = 0.1
fee_rate_window_size = 5
cost_metric = proportion_dot_product
log_error = true
enabled = true

Estimators use observed tx costs/fees to suggest fee rates and execution costs for clients and miners. Set enabled = false to disable.

Key points

• Miner needs a Bitcoin key with UTXOs for burn commitments.
• Use mock_mining only for testing (no real BTC spent).
• RBF settings should allow multiple bumps to stay on canonical chain.

<!-- Source references:

• sources/stacks/docs/mining.md
• https://github.com/stacks-network/stacks-blockchain

-->

Stacks Improvement Proposals (SIPs)

SIPs describe Stacks blockchain implementation and propose improvements. They are the primary medium for new features, community input on system-wide issues, and design decisions.

• Process: Defined in SIP 000.
• Repository: stacksgov/sips under the Stacks Community Governance org.

When implementing or reviewing consensus, PoX, or contract behavior, check the relevant SIP in that repo for the canonical spec (e.g. SIP-007 for stacking consensus and STX operations on Bitcoin).

<!-- Source references:

• sources/stacks/docs/SIPS.md
• https://github.com/stacksgov/sips

-->