Contract Deployment

Clarinet provides deployment tooling that helps you move from local development to production networks. Whether you're testing on devnet, staging on testnet, or launching on mainnet, Clarinet streamlines the process.

Generating deployment plans

Deployment plans are YAML files that describe how contracts are published or called. Generate a plan for any network:

$ clarinet deployments generate --testnet
Analyzing contracts...
Calculating deployment costs...
Generating deployment plan
Created file deployments/default.testnet-plan.yaml

Example output structure:

deployments/default.devnet-plan.yaml

---
id: 0
name: Devnet deployment
network: devnet
stacks-node: "http://localhost:20443"
bitcoin-node: "http://devnet:devnet@localhost:18443"
plan:
  batches:
    - id: 0
      transactions:
        - contract-publish:
            contract-name: counter
            expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
            cost: 6940
            path: contracts/counter.clar
            anchor-block-only: true
            clarity-version: 2
      epoch: "2.5"

Deployment plan structure

Field

Description

id

Unique identifier for the deployment

name

Human-readable deployment name

network

Target network (devnet, testnet, or mainnet)

stacks-node

RPC endpoint for the Stacks node

bitcoin-node

RPC endpoint for the Bitcoin node

plan.batches

Array of deployment batches

Deployment specifications

Deployment behavior is configured in two places:

Project configuration (Clarinet.toml) – Clarity versions, dependencies, epoch requirements
Network configuration (settings/<network>.toml) – Account details, balances, endpoints

Example network configuration:

settings/Testnet.toml

[network]
name = "testnet"
deployment_fee_rate = 10

[accounts.deployer]
mnemonic = "<YOUR TESTNET MNEMONIC>"
balance = 100_000_000_000_000
derivation = "m/44'/5757'/0'/0/0"

Working with contract requirements

Reference contracts that already exist on-chain—useful for standardized traits.

Adding requirements

clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait

Clarinet updates your configuration automatically:

[project]
name = "my-nft-project"
requirements = [
  { contract_id = "SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait" }
]

During deployment Clarinet downloads the contract, remaps the principal for devnet, and ensures the requirement is available before your contracts deploy.

Deploying to different networks

Devnet

Devnet deploys contracts automatically when it starts:

clarinet devnet start

To deploy manually against a running devnet:

clarinet deployments apply --devnet

See local development for more devnet configuration tips.

Testnet

Prerequisites:

Request testnet STX from the faucet
Configure your account in settings/Testnet.toml
Validate contracts with clarinet check

Generate a deployment plan with cost estimation:

clarinet deployments generate --testnet --medium-cost

Deploy to testnet:

clarinet deployments apply --testnet

Mainnet

Mainnet checklist

Finish thorough testing on testnet

Audit contracts for security

Ensure sufficient STX for fees

Back up deployment keys securely

Prefer a hardware wallet for deployment

Create a mainnet plan:

clarinet deployments generate --mainnet --high-cost

Deploy with confirmation:

clarinet deployments apply --mainnet

Cost estimation and optimization

Choose the right fee level for your deployment:

clarinet deployments generate --testnet --manual-cost

Fee options:

--low-cost – minimize fees, slower confirmation
--medium-cost – balanced approach
--high-cost – priority inclusion
--manual-cost – interactive selection

Analyze costs before deploying:

clarinet deployments generate --testnet --medium-cost

Advanced deployment configurations

Multi-batch deployments

Deploy complex systems with batches:

plan:
  batches:
    - id: 0
      transactions:
        - contract-publish:
            contract-name: trait-definitions
            path: contracts/traits.clar
            clarity-version: 2
    - id: 1
      transactions:
        - contract-publish:
            contract-name: token
            path: contracts/token.clar
        - contract-publish:
            contract-name: oracle
            path: contracts/oracle.clar
    - id: 2
      transactions:
        - contract-publish:
            contract-name: defi-pool
            path: contracts/defi-pool.clar

Batches guarantee that dependencies deploy first, allow parallel transactions within a batch, and run batches sequentially.

Transaction types

Deployment plans support different transaction types:

Transaction type

Description

Contract operations

Publish or call contracts, specifying sender, cost, and source path

Asset transfers

Transfer STX or BTC by setting sender, recipient, and amounts

Contract operations

- contract-publish:
    contract-name: my-contract
    expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
    cost: 5960
    path: contracts/my-contract.clar
    clarity-version: 2

- contract-call:
    contract-id: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract
    expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
    method: initialize
    parameters:
      - u1000000
      - "Token Name"
    cost: 5960

Asset transfers

- stx-transfer:
    expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
    recipient: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG
    mstx-amount: 1000000
    memo: '0x48656c6c6f'

- btc-transfer:
    expected-sender: mjSrB3wS4xab3kYqFktwBzfTdPg367ZJ2d
    recipient: bcrt1qnxknq3wqtphv7sfwy07m7e4sr6ut9yt6ed99jg
    sats-amount: 100000000
    sats-per-byte: 10

Manual customization

You can edit deployment plans for complex scenarios.

Manual edits

When Clarinet prompts to overwrite your plan, answer no to keep custom changes.

Example contract initialization batch:

- id: 3
  transactions:
    - contract-call:
        contract-id: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token
        method: initialize
        parameters:
          - u1000000
          - { name: "My Token", symbol: "MTK", decimals: u6 }
        expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

Common issues

Insufficient STX balance

Error: “Insufficient STX balance for deployment”

Solutions:

Request testnet STX from the faucet

Reduce the fee rate with --low-cost

Check your balance:

clarinet console --testnet
stx-account 'ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG

Contract already exists

Error: “Contract token already deployed at this address”

Solutions:

Use a different contract name

Deploy from another address

On testnet, switch to a fresh account

Network connection failures

Error: “Failed to connect to testnet node”

Check your network settings:

[network]
name = "testnet"
node_rpc_address = "https://stacks-node-api.testnet.stacks.co"

Alternative endpoints:

Hiro: https://api.testnet.hiro.so
Your own node

Debug the connection:

curl -I https://api.testnet.hiro.so/v2/info

Invalid deployment plan

Common YAML errors

Incorrect indentation
Missing required fields
Invalid contract paths

Validate and regenerate as needed:

clarinet deployments check
clarinet deployments generate --testnet
ls contracts/

PreviousLocal Blockchain Development NextCLI Reference

Last updated 11 days ago

Was this helpful?