Deploying your contracts

Clarinet provides comprehensive deployment tools to help you move your contracts from local development to production networks. Whether you're testing on devnet, staging on testnet, or launching on mainnet, Clarinet streamlines the entire deployment process.

Generating deployment plans

Deployment plans are YAML files that define exactly how your contracts will be deployed. They specify the order, configuration, and network details for each contract, ensuring reproducible deployments across all environments. To create a deployment plan for any network, run the following command:

Terminal

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

This creates a deployment plan based on your project's configuration:

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

Key components of a deployment plan:

Field	Description
`id`	Unique identifier for the deployment
`name`	Human-readable deployment name
`network`	Target network (devnet/testnet/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 version for contracts
Contract dependencies
Epoch requirements

Network configuration (settings/<Network>.toml):

Account details and balances
Network endpoints
Custom deployment accounts

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

Your project can reference contracts that already exist on the blockchain. This is especially useful for implementing standardized traits.

Adding requirements

Add external contract dependencies:

Terminal

$ clarinet requirements add SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait
Added requirement SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait
Updated Clarinet.toml

This updates your project configuration:

Clarinet.toml

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

When deploying, Clarinet automatically:

Downloads the contract via the Stacks API
Remaps the principal to a local account for devnet
Ensures the requirement is available before deploying your contracts

Deploying to different networks

Quick deployment for local development

Devnet automatically deploys contracts when started:

Terminal

$ clarinet devnet start
[32mStarting devnet...[0m
[32mDeploying contracts...[0m
[90mDeploying[0m counter.clar        [32m✓[0m  ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.counter
[90mDeploying[0m token.clar          [32m✓[0m  ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.token

For manual deployment to a running devnet:

Terminal

$ clarinet deployments apply --devnet

See local development for detailed devnet configuration.

Cost estimation and optimization

Fee levels

Choose the right fee level for your deployment:

Terminal

$ clarinet deployments generate --testnet --manual-cost

Fee level options:

--low-cost: Minimize fees, slower confirmation
--medium-cost: Balanced fees and speed
--high-cost: Priority inclusion
--manual-cost: Choose interactively

Analyzing deployment costs

Get detailed cost breakdown before deploying:

Terminal

$ clarinet deployments generate --testnet --medium-cost

Advanced deployment configurations

Multi-batch deployments

Deploy complex systems with dependencies using batches:

deployments/defi-protocol.yaml

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
            depends_on: ["trait-definitions"]
        - contract-publish:
            contract-name: oracle
            path: contracts/oracle.clar
    - id: 2
      transactions:
        - contract-publish:
            contract-name: defi-pool
            path: contracts/defi-pool.clar
            depends_on: ["token", "oracle"]

Batches ensure:

Dependencies are deployed first
Parallel deployment within batches
Sequential execution between batches

Transaction types

Deployment plans support various transaction types:

Transaction Type	Description
Contract Operations	Involves publishing and calling contracts, specifying sender, cost, and path
Asset Transfers	Transfers assets like STX or BTC, specifying sender, recipient, and amounts

With 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

With asset transfers:

- stx-transfer:
    expected-sender: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
    recipient: ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG
    mstx-amount: 1000000
    memo: '0x48656c6c6f'  # "Hello" in hex

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

Manual plan customization

You can manually edit deployment plans for complex scenarios:

Manual edits

When deploying, Clarinet prompts to overwrite manual changes. Type no to keep your customizations.

Contract initialization example:

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

Common issues

Next steps

After successful deployment:

Monitor your contracts using the Stacks Explorer
Set up event notifications with Chainhook
Learn about contract upgrades
Configure monitoring and alerts for your contracts

Deploying your contracts

Insufficient STX balance

Contract already exists

Network connection failures

Invalid deployment plan