Stacks Development: Where the Connection with Bitcoin Breaks
Stacks is chosen when an application needs Bitcoin's settlement base, but the logic must live in contracts. State and computation remain on the second layer, while settlement and ordering are inherited from the base network.
It is this junction — the link between settlement layers — that most often becomes the place where Stacks development breaks.
The first bottleneck is confirmation. An operation on the second layer goes through quickly, but it is finalized by a record in the base layer, and the base layer assembles a block not on our schedule.
Until the record is made, the transaction looks successful, although the settlement is not yet secured — the application shows the user an asset they cannot yet dispose of.
The second is the order in which data exits to the base layer. Data from the second layer enters it as a batch, and the order within the batch does not match the order in which operations occurred for the user.
sBTC deposits and withdrawals add their own waiting windows, so "successful" and "settled" are two different states that need to be distinguished in code.
The third is state divergence. Clarity contracts and what the application reads are not updated synchronously: the read service lags several blocks behind.
The consequence is manual reconciliations: an operator on duty checks balances, investigates stuck withdrawals, and manually recalculates operations that the network has already confirmed.
Below we examine how this is addressed engineering-wise: by designing for finality waiting, idempotent operations, and automated reconciliations that detect divergence before the user sees it.
What Changes After Implementation: Timelines, Failures, Verifiability
Verifiability of operations here is not a declaration but a property of the platform: logic on Stacks is described by readable source code, and the registry state is derived from the Bitcoin chain itself, not from an export of an internal database.
An operation can be verified against the published code and current state — without access to our infrastructure. Manual registry reconciliation ceases to be a monthly procedure: divergence is visible at the level of rules, not at the end of the quarter.
The release time for a new version of logic is reduced because the rule is described declaratively and run through a set of tests on a network clone before publication.
Release no longer depends on manual exports and correspondence between systems: a change goes through a single procedure, and the previous version remains available for rollback. A typical rule-change cycle takes days instead of weeks of approvals.
The class of failures closed first is desynchronization between accounting and the actual state on the chain. Double entries, lost events, and "stuck" sBTC transfers disappear because the source of truth becomes verifiable state rather than an intermediary database.
The cost of downtime falls through localization: an incident is reduced to a specific rule, not the entire integration, and is reproduced on a test clone. As a result, the client has its own verification loop — access to contracts, tests, and the operations log.
Stacks Development: Comparing Integration Options
An integration scheme is chosen based on two questions: where state lives and who is responsible for settlement finality.
Clarity contracts on the base layer, a separate layer with a bridge, a hybrid scheme, and a closed loop cover different classes of tasks — and differ not in convenience but in the trust model.
| Option | When It Fits | Limitations |
|---|---|---|
| Clarity contracts on the base layer | Settlements must inherit Bitcoin security; logic is public and verifiable | Fee and delay for every operation, limited state volume, frequent calls are expensive |
| Separate settlement layer with a bridge | Many operations, fast response and low transaction cost are needed | The bridge between layers is an additional trust point and a withdrawal period |
| Hybrid scheme | Critical rules remain on the base layer; high-load ones are moved outside | Split logic: more expensive audit, state synchronization between parts is required |
| Closed loop | Internal settlements, confidential data, isolation requirements | Public network security is not inherited; custody rests entirely with the operator |
sBTC blurs the boundaries between options: the asset moves between layers without losing its link to the base.
But this does not remove the rules — the more logic leaves Clarity contracts, the more trust assumptions must be fixed before start; otherwise, a hybrid scheme turns into a closed loop with unnecessary entities.
Stages: Logic Audit, Contract Scheme, Verification, Handover
The order of work here is not decorative: a Clarity contract is immutable after publication — you cannot fix a typo in it, you can only release a new one and migrate state into it. That is why the audit and scheme come first, and code is written against the fixed scheme.
- Logic and current loop audit — we read existing contracts and storage calls, map published functions, address rights, and related balances. The output is a risk map: what cannot be rewritten and what will have to be migrated.
- Contract scheme — we decompose the logic into the minimum number of modules: a core with state, a rights module, and auxiliary calls. We fix public functions, events, storage structure, and publication order — the possible rollback point depends on it.
- Implementation and edge-case verification — we write contracts and cover every failure branch with a separate check: repeated call, insufficient rights, zero input, attempt to withdraw more than the balance.
- Test loop — a run in an isolated network on real scenarios: sBTC deposit and withdrawal, exchange between contracts. We separately examine behavior under Bitcoin network congestion, when confirmations are slow.
- Deployment — staged publication: first contracts, then rights, then state migration, each step with verification. We issue keys and access according to the minimum necessary set.
- Acceptance and handover — we run control scenarios together with your team, compare the result with the expected one, and provide documentation: contract scheme, function list, update and emergency behavior procedure, plus team training.
What the Handover Package Includes: Code, Schemes, Procedures
Project handover is not an archive with code or a list of deployed contract addresses. We provide a package by which your team can conduct an independent verification, make a change, and restore operation after a failure without our involvement. Below is what exactly the package includes.
- Contract source code. Clarity contract texts with comments, tests, deployment and reproducible build scripts. The repository comes up on a clean machine with a single command — no "it works locally for me."
- Layer interaction schemes. How contracts are connected to the wallet and external services, where trust boundaries run, which failure points lead to which outage, and how this is diagnosed.
- Access and key policies. Roles, signature thresholds, key rotation and rights issuance procedures. Administrator rights are transferred to you — we do not remain the only ones who can change the contract.
- Documentation. Description of interfaces, call formats, events, and storage structure. A separate section covers why certain decisions were made and what was considered as an alternative.
- Update procedure. Step-by-step rollout of a new version: preparation, state migration, window and conditions for rollback to the previous version without data loss.
- Incident review procedure. What counts as an incident, who responds, how contract operation is paused, how the cause is recorded, and what changes after the review.
Acceptance is engineering-style: your team deploys the project according to our documentation and makes a trial change in the test network. Anything that is not reproducible or requires our explanations is considered a handover defect and is closed before signing.
Case Study: Settlements on the Bitcoin Network Without Downtime and Manual Reconciliations
The client is a settlement service where payout and accounting logic lived in a combination of an internal database and manual operator reconciliations.
Rules were released through a procedural process: edit, review, manual run, migration — the cycle took about three weeks, and each change involved four people and a night-work window.
What We Changed
The settlement and limit logic was moved into contracts on Stacks — the second layer of the Bitcoin network with its own execution and finality tied to Bitcoin.
State and rules became a single source of truth: the operator stopped reconciling balances manually and confirms only exceptions. Release of an update was reduced from three weeks to two days — contract checks run before rollout, not after.
What It Became
The share of failures in payout operations fell from 4.1% to 0.3%: disputed cases are filtered out by checks before recording, rather than investigated after the fact.
Recovery time after a failure decreased from eight hours to forty minutes — state is restored from the network, and rollback is performed by switching to the previous contract.
The volume of manual reconciliations dropped from nine hundred operations per month to sixty: only discrepancies on the side of external counterparties remain, which are not closed within the loop.
What to Do If the Logic Is Already Deployed on Another Network?
What is ported one-to-one is what does not depend on the language: the data model, roles and rights, invariants — the sum of balances, token unlock schedule, multisignature thresholds — and the settlement math.
These are rules, not code, so when developing on Stacks they are described anew but verified with the same tests on the same datasets.
Then logic migration begins, and here the execution model is decisive. Clarity is not a Turing-complete language: it has no loops with a previously unknown number of iterations and no calling a contract by address during execution.
But it also has no reentrancy — the usual locks are removed as unnecessary, and array traversal is decomposed into an index and separate calls.
Assets are structured differently: the balance is tied to settlements in the Bitcoin network, so deposits and withdrawals are a separate loop with its own confirmation rules.
Where an account-based model gave instant balance recording, here there is waiting and its own handling of canceled operations.
Migrating the entire loop is a snapshot, not a transfer of the whole history: we fix a block, export aggregates and the balance map, and compute a root from the operations log. It serves as proof of funds origin when details are rolled into an archive.
Parallel loops are maintained during the transition: the old one is put into read-only mode, the new one accepts writes, and asset issuance is closed for this window — otherwise double spending.
Switching proceeds by reconciling checksums at each step, and rollback means returning traffic to the previous loop.
Common Technical Doubts Before Work Starts
Before the start, the client and its engineers ask the same questions. They concern not the technology itself but risks: load on the base layer, data privacy, correctness guarantees, and what happens after code handover. Below are short answers.
Will the application become more expensive to operate as the number of operations grows?
User actions do not create a separate transaction in the base layer: logic executes in the Stacks layer, and an aggregated record goes to Bitcoin.
Load grows from the number of such records, not from the number of contract calls, so peak traffic does not cause linear growth in base-layer consumption.
What if some data cannot be disclosed?
The contract stores an identifier or hash of the record, not the content itself. Data resides in external storage with access control, while verifiability is preserved: the hash shows that the record was not substituted.
How will you prove that the contract is correct?
Clarity executes deterministically and without loops, so the logic can be statically analyzed. We set up property checks on random input sets, run failure scenarios on a local network copy, and send the code for independent audit before publication.
What happens after project handover?
A published contract is immutable, so an update is a new version plus state migration. We hand over source code, deployment scheme, migration procedure, and a set of checks that catch state divergence after release.
We have our own team. How do we divide the work?
From day one we work in your repository: shared code checks, a unified branch procedure, access to staging environments. We fix areas of responsibility explicitly — your engineers handle product logic and the interface, we cover contracts and integration with the base layer.
Let's Discuss the Task: Where to Start and What to Send
To come back with an estimate and stage plan, rather than clarifying questions a week later, one email with the inputs is enough for us. Below is what really affects the effort of Stacks development: from the sBTC access model to who makes decisions on the client side.
- Process description — how the logic works now: who initiates an operation, where the result is recorded, and which checks are mandatory before writing to the network.
- Loop scheme — which services the system consists of, where signing keys are stored, which external systems are called, and in which direction data flows.
- Boundaries of the first iteration — which scenarios go into Clarity contracts and which deliberately remain outside the perimeter.
- Timeline constraints — whether there are external dates on which the order of stages depends, and what is more important: an early working prototype or an industrial loop right away.
- Roles in the client team — who owns the product, who accepts the result, who is responsible for infrastructure and access.
- Access and environments — repository, test loop, test assets for verifying transfers and rollbacks.
- Current work — if contracts or the server side already exist, send them: reviewing existing code changes both the plan and the order of stages.
A draft scheme is also fine: from it we fix the boundaries of work, risks, and acceptance points. To discuss the task substantively, a short description is enough — we will come back with an estimate and stage plan.