Skip to content
Skills Library
Programming · Learning & explanation

system-integration

/system-integration

Stacks system facts: boot contract and SIP trait addresses (pox-5, sip-010-trait) on mainnet and testnet, address versions, transactions, blocks and tenures. Use for standard Stacks addresses or chain mechanics.

Licence
MIT
Last repository change
02.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Stacks system facts: boot contract and SIP trait addresses (pox-5, sip-010-trait) on mainnet and testnet, address versions, transactions, blocks and tenures. Use for standard Stacks addresses or chain mechanics.

Original author description

Stacks system facts: boot contract and SIP trait addresses (pox-5, sip-010-trait) on mainnet and testnet, address versions, transactions, blocks and tenures. Use for standard Stacks addresses or chain mechanics.

How it works

  1. Key distinctions
  2. Principals and address versions
  3. Chain, clocks and tenures
  4. Transactions
  5. Execution model
  6. Reading state (no transaction)
  7. Resolve and integrate
  8. Tooling
  9. References
  10. Reference baseline
Original SKILL.md headings · 118 lines, 1,730 words
SKILL.md preview
---
name: system-integration
description: "Stacks system facts: boot contract and SIP trait addresses (pox-5, sip-010-trait) on mainnet and testnet, address versions, transactions, blocks and tenures. Use for standard Stacks addresses or chain mechanics."
license: MIT
metadata:
  version: "1.0.0"
  baseline_date: "2026-11-02"
  registry_verified_at: "2026-10-20"
---

# Clarity System Integration

Resolve system identity and boot-contract integration here; use [clarity:protocols](../protocols/SKILL.md) for application protocol addresses.

## Key distinctions

- A file in `stacks-core/.../boot` is not proof that its contract is active on a network.
- Boot contracts can rely on privileged VM behavior and network-specific source assembly. Redeploying the source under another principal is not equivalent.
- SIP token traits are ordinary deployed contracts, not boot contracts.
- Replacing a mainnet prefix with a testnet prefix does not establish a corresponding deployment.
- `costs_5.rs` is an active native schedule, not evidence of a deployed `.costs-5` contract.

## Principals and address versions

- A standard principal is a c32 address: a version byte plus a 20-byte hash. `SP` mainnet single-sig (`0x16`), `SM` mainnet multisig (`0x14`), `ST` testnet single-sig (`0x1a`), `SN` testnet multisig (`0x15`).
- `SM`/`SN` are P2SH version bytes, also used by P2SH-wrapped single keys: version `0x14`/`0x15` shows a script-hash address, not proof of a multisig.
- A contract principal is `deployer.name` (name 1–40 bytes, immutable code; a name can be deployed only once per deployer).
- Boot contracts are issued by `SP000000000000000000002Q6VF78` (mainnet) and `ST000000000000000000002AMW42H` (testnet), for example `SP000000000000000000002Q6VF78.pox-5`. Other boot and standard principals: [address records](references/addresses.md).
- `principal-construct?` with another network's version byte returns `(err {error_code: u0, value: (some principal)})`; a byte above `0x1f` or a hash shorter than 20 bytes gives `u1`, an invalid contract name `u2`. `principal-destruct?` returns `{version, hash-bytes, name}` as `ok` on the matching network and as `err` otherwise; `name` is `some` only for contract principals.
- `is-standard` is true when the principal's version matches the execution network, including **contract** principals. It is not an "is a wallet" check and proves neither key control nor trust.
- `is-in-mainnet` is easy to invert in a guard. Plain simnet, devnet and testnet run only the testnet branch; a [mainnet fork](../testing/SKILL.md#mainnet-forks) runs the mainnet branch, so test both.
- Clarity 1 `principal-of?` derives a **testnet** principal on every network and epoch; Clarity 2+ uses the execution network.
- STX is native with 6 decimals (1 STX = 1,000,000 µSTX). Tokens defined with `define-fungible-token` / `define-non-fungible-token` are also native: the node tracks them and postconditions can constrain them. Map-only "balances" are contract state.
- Token identity is the **contract principal plus asset name** (`SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token::sbtc-token`), never the symbol. Wrappers differ in principals, scales and custody; see [assets](../assets/SKILL.md#stx-through-a-token-interface-zest-wstx).
- `stx-get-balance` returns only the **spendable** STX (unlocked, plus expired locks); `stx-account` returns `{locked, unlock-height, unlocked}`. Staked STX is locked in place, not transferred.

## Chain, clocks and tenures

- Stacks settles to Bitcoin. Since Nakamoto (epoch 3.0), a miner election starts a **tenure**: its miner can produce multiple Stacks blocks, approved by eligible signers. A Bitcoin block does not guarantee a new tenure; tenure extensions and empty sortitions separate the clocks.

| Clock | Clarity | Advances | Use for |
|---|---|---|---|
| Stacks block | `stacks-block-height` (C3+) | every Stacks block (seconds) | ordering, same-block guards |
| Tenure | `tenure-height` (C3+) | each new tenure | legacy `block-height` meaning in C1/C2 after Nakamoto |
| Bitcoin | `burn-block-height` | each Bitcoin block (~10 min) | PoX cycles, Bitcoin-anchored delays |
| Wall time | `stacks-block-time` (C4+) | timestamp of the current block | interest, expiry, oracle staleness |

- Heights and wall-clock timestamps answer different questions. Never convert heights to seconds with a constant.
- `(get-stacks-block-info? time h)` works only for past blocks.
- **Epochs** are consensus upgrades. They select the cost schedule, the newest deployable Clarity version and block limits, and can change how old contracts execute (for example `at-block` aborts from epoch 3.4). Mainnet runs epoch 4.0 (Clarity up to 6); `/v2/pox.epochs` is the authoritative schedule and can list a future epoch with an unreachable start height, so do not hardcode "Epoch 4.0" as the latest.
- Since Nakamoto, blocks of a tenure share its execution budget; see [versions](../epochs/SKILL.md) for resource bounds.

## Transactions

- Types you meet: STX transfer, contract deploy (versioned or epoch-default language), contract call (a public function), plus system coinbase/tenure-change transactions.
- Sequential nonce per account. Fees are paid in µSTX by the origin or by a **sponsor** (`tx-sponsor?`). Fees do not buy extra execution budget.
- **Postconditions** are attached by the client and enforced by the node after execution: "this principal sends at most / exactly N of asset X", "this NFT leaves/stays".
  - *Deny* mode aborts the transaction on any asset movement not covered and, from epoch 4.0, on any uncovered stake or PoX action ([staking conditions](../staking/SKILL.md#transaction-post-conditions)). *Allow* mode permits unlisted movements. *Originator* mode (epoch 3.4+, SIP-040) applies *Deny* to the origin account only.
  - Conditions can name contract principals too, NFTs can be marked "may send" (3.4+), and epoch 4.0 adds Staking/PoX conditions.
  - Contracts cannot read or set them.
  - User-facing calls need postconditions for every asset the user (or a user-owned contract) sends, including native STX moved through a wSTX wrapper.
- Outcome: a top-level `(ok ...)` commits state and events. A top-level `(err ...)`, a runtime abort (`unwrap-panic`, overflow, division by zero) or a postcondition failure rolls back contract state/assets/events; the fee is still paid and the nonce consumed.
- Inside one transaction, a callee's `err` rolls back only that callee's changes; the caller may handle it and continue.

## Execution model

- Clarity is interpreted, not compiled: the source you deploy is the code that runs.
- It is decidable: no recursion, no unbounded loops (iterate with `map`/`fold`/`filter` over bounded lists).
- It is statically typed: `uint`/`int` are 128-bit, and lists, buffers and strings carry a maximum length. Overflow, underflow and division by zero abort the transaction.
- Calling into an already-active function is rejected, but callbacks to a different function of an active contract are possible. Review intermediate state and A → B → C chains with inherited `tx-sender`.
- Dynamic dispatch uses traits passed as arguments; a contract cannot call a principal it loaded from storage unless the caller passes it in as a trait, so validate `contract-of`.
- Trait arguments are checked by shape, not by trait identity, and `impl-trait` is not required. A node's mempool checks each contract argument of a contract call against the whole trait, as deployment analysis does for contract literals in source and for `impl-trait`. Unlike deployment analysis, the mempool checks only the first element of any list ([admission type check](https://github.com/stacks-network/stacks-core/blob/ccf31dc69cddb9a7125e286e733b24484b073133/clarity/src/vm/analysis/type_checker/v2_1/mod.rs)). When the VM dispatches, it checks only the called function (calling a missing one aborts with `BadTraitImplementation`). Simnet calls skip the mempool, so partial mocks pass there. A trait argument never proves the full standard; bind the expected principal. Exception: a trait-typed parameter inside a trait you define is compared by trait identity, so a local copy there breaks calls to the real contract at runtime.
- A contract that `impl-trait`s a mainnet trait principal fails to deploy on a network where that principal does not exist. Keep the mainnet principal and declare it under `[[project.requirements]]`, or self-deploy the trait; details in [standard traits](references/addresses.md#standard-traits).
- Every transaction is metered in five dimensions against the active execution budget.

## Reading state (no transaction)

| Need | Endpoint (node RPC, e.g. `https://api.hiro.so`) |
|---|---|
| Call a read-only function | `POST /v2/contracts/call-read/{addr}/{name}/{fn}` body `{"sender": "...", "arguments": ["0x<clarity-serialized hex>"]}` |
| Map entry / data var | `POST /v2/map_entry/{addr}/{name}/{map}` (body: the serialized key as a JSON string), `GET /v2/data_var/{addr}/{name}/{var}` |
| Contract source / ABI | `GET /v2/contracts/source/{addr}/{name}`, `GET /v2/contracts/interface/{addr}/{name}` |
| Chain tip, epoch, PoX | `GET /v2/info`, `GET /v2/pox` |
| Transactions, events, balances | Stacks Blockchain API `/extended/v3/transactions/{id}` and its `/events`, `/extended/v3/principals/{principal}/balances/stx` (`/ft`, `/nft`), `/extended/v3/blocks/{height_or_hash}`; `/extended/v1` routes are deprecated ([routes](../apis/references/endpoints.md#verify-the-chain-and-deployment)) |

- Serialize arguments with `@stacks/transactions` (`Cl.*` + `serializeCV`) or `cvToHex`.
- Read-only results come back as serialized hex; decode them, and check `okay`.
- Copyable curl calls, evidence capture and pagination: [APIs and deployment evidence](../apis/SKILL.md#common-calls).

## Resolve and integrate

- Establish network, executing epoch and target contract language version.
- Use [address records](references/addresses.md) for full boot principals, active PoX observations and verified mainnet standard traits.
- From this skill's directory, check the registry's age offline with `python3 ../protocols/scripts/check_registry.py --registry references/addresses.md`. At 30 days or older the installed package may be outdated: tell the user to update the plugin, and verify each address you use against the live node (`python3 ../protocols/scripts/verify_registry.py --observations references/address-observations.json --contract <id>`, plus `/v2/pox` for active selection). Never fetch registry files from a repository.
- Resolve the active PoX contract and cycle from the live node (`/v2/pox.contract_id`; PoX-4 still having source does not make it active), then capture its source and ABI with the helper in `../apis/scripts/` (use `--api https://api.testnet.hiro.so` for testnet):

```sh
curl -s https://api.hiro.so/v2/pox | python3 -c "import sys,json;d=json.load(sys.stdin);print(d['contract_id'],d['current_cycle']['id'])"
python3 ../apis/scripts/inspect_contract.py SP000000000000000000002Q6VF78.pox-5 --out <project>/evidence/pox-5
```

- Inspect the [boot directory](https://github.com/stacks-network/stacks-core/tree/ccf31dc69cddb9a7125e286e733b24484b073133/stackslib/src/chainstate/stacks/boot) and registration/epoch code; retain the source hash, revision, network and state tip ([API evidence](../apis/SKILL.md#read-state-and-transactions)).
- For boot contracts, corroborate source/activation with consensus initialization rather than demanding a normal user deployment transaction.
- For ordinary traits/protocols, verify successful canonical deployment. Source existence does not prove current registry selection or permissions.
- Test required system state and permissions; empty simnet mocks do not reproduce consensus boot transitions.
- Staking locks STX across reward cycles; PoX-5 uses signer managers and sBTC reward claims; use [staking](../staking/SKILL.md). sBTC transfers on Stacks are synchronous while Bitcoin settlement is asynchronous; use [sBTC balances](../assets/SKILL.md#sbtc) and [Bitcoin settlement](../bitcoin-proofs/SKILL.md).

## Tooling

- Default to Clarigen for typed project clients and tests.
- Clarinet (CLI + `@stacks/clarinet-sdk`) gives simnet (fast, deterministic, in-process VM), devnet (local node + Bitcoin regtest) and deployment plans.
- `[[project.requirements]]` pulls mainnet contracts (traits, protocols) into simnet. sBTC is built in from epoch 3.0, so do not add it as a requirement.

## References

- [Address records](references/addresses.md): open for full boot principals and contract names, standard trait principals per network (mainnet and testnet status), and the Clarinet requirement remap.
- For on-chain Stacks inclusion proofs, read [clarity-stacks](../apis/references/positions-and-proofs.md#stacks-transaction-inclusion-with-clarity-stacks). Use [clarity:bitcoin-proofs](../bitcoin-proofs/SKILL.md) for Bitcoin proofs and sBTC settlement.
- [clarity:epochs](../epochs/SKILL.md): language and epoch compatibility and activation; its [recall corrections](../epochs/SKILL.md#recall-corrections) cover limits, native costs and chain identifiers.
- [clarity:staking](../staking/SKILL.md) for delegation and rewards, [clarity:optimizer](../optimizer/SKILL.md) for cost formulas and measurement, and [clarity:sip-compliance](../sip-compliance/SKILL.md) for normative token and signature behavior.

## Reference baseline

Examples use Clarity 4+ syntax unless marked, checked on epoch 4.0. Source links in this skill and its references use these pins; links into sibling skills use their owner's `SKILL.md`. Review dates do not renew live evidence.

- `stacks-core`: [ccf31dc69c](https://github.com/stacks-network/stacks-core/tree/ccf31dc69cddb9a7125e286e733b24484b073133).
- `sips`: [642af6804d](https://github.com/stacksgov/sips/tree/642af6804dacc80455c3d49ef66b62bc4fb209aa).
Files in this package (6)
  • SKILL.md 14 KB
  • agents/openai.yaml 1 KB
  • assets/icon-large.png 9 KB
  • assets/icon-small.svg 2 KB
  • references/address-observations.json 12 KB
  • references/addresses.md 7 KB

Versions

The database has no other skills named system-integration.

Database snapshot: 13.11.2026 · package version 1e0fb9af940e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100clarity-system-integration
    Stacks system facts: boot contract and SIP trait addresses (pox-5, sip-010-trait) on mainnet and testnet, address versions, transactions, blocks and tenures. Use for standard Stacks addresses or chain mechanics.
  • 100sip-compliance
    Token standards in Clarity: SIP-010, SIP-009 and SIP-013 traits and conformance, metadata, SIP-018 signed data. Use when writing a token or NFT contract or checking trait conformance.
  • 100deploy-to-mainnet
    Deploy a Sui Move package to mainnet after testnet has been exercised. Use when the user wants to ship to mainnet, go to prod, or publish to Sui mainnet.
  • 95bitcoin-l2-stacks
    Stacks: Bitcoin smart contract layer with Clarity language, sBTC for native peg, Nakamoto upgrade for fast finality, PoX (Proof of Transfer) consensus. USE WHEN: building Bitcoin smart contracts, integrating sBTC, evaluating Stacks vs RSK / EVM alternatives.
  • 100sip-protocol-fundamentals
    Use when working with SIP messages, methods, call flows, and protocol fundamentals for VoIP applications.
  • 95telnyx-sip-curl
    Configure SIP trunking connections and outbound voice profiles. Use when connecting PBX systems or managing SIP infrastructure. This skill provides REST API (curl) examples.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.