Deployment plans minimize the inherent complexity of deployments, such as smart contract dependencies and interactions, transaction chaining limits, deployment costs, and more. Deployment plans ensure reproducible deployments, a critical workflow for testing purposes.
Clarinet uses a deployment plan for every deployment—whether for a basic simnet, devnet (for use with the clarinet devnet start command), or the public testnet and mainnet.
You can view the current deployment plan saved to disk at any time with the following command (specifying the network simnet, devnet, testnet, mainnet)
Terminal
$
clarinet deployments generate --<network>
Upon this command, your project's default deployment plan, a .yaml file (for example, default.devnet-plan.yaml), is generated from your project specifications and contracts. Here, for example, is the deployment plan for the counter smart contract used in our quickstart guide:
A project's deployment plan specifications are set on two files within a Clarinet project—the Clarinet.toml file as well as the network’s corresponding .toml file (for example, Devnet.toml) in the settings/ folder.
Specifications in the Clarinet.toml file you can change include:
The Clarity version or blockchain epoch that Clarinet emulates for your smart contracts
Project requirements in the form of contract dependencies (see next section)
Specifications in the Devnet.toml file you can change include:
Accounts, balances, and names
Blockchain environment features of your devnet, such as block time or API ports
Your project can reference a smart contract that already exists on the blockchain.
For example, Stacks Improvement Proposal 009 specifies a trait reference for all non-fungible tokens. Instead of redeploying this trait as a separate contract each time a new NFT collection is published, you can reference the contract directly within deployment plans with the following Clarinet command, including the contract principal reference:
This command updates a Clarinet project's deployment plan for use in development.
For instance, clarinet devnet start would now download a copy of the contract principal via the Stacks API node that is booted alongside each devnet deployment, and it would remap the principal that publishes this contract to one of the accounts specified in your Devnet.toml file.
This permits a developer to maintain the minimum set of contracts their Clarinet project will deploy to mainnet (with a single use of an impl-trait statement in their Clarity contract).
Recall that a default deployment plan is used for every deployment, comprising your projects specifications as set in your Clarinet.toml and <network>.toml files.
The default plan is generated upon each clarinet deployments generate --<network> shell command to your deployments/ folder.
However, you can also manually edit this default deployment .yaml file directly—programmatically orchestrating your contract publication and user interaction beyond your plan's defaults.
Note
When deploying, Clarinet prompts you to overwrite any manually added or edited changes that differ from the specifications laid out in your project's .toml files. Type no to proceed with your manually configured deployment plan instead of the default.
Here are some of the relevant transactions and configurations available to developers manually configuring their deployment plans:
This default transaction is included in every generated deployment plan for every contract your Clarinet project has. This counter application has a devnet deployment plan that publishes its core smart contract.
The developer can specify the originating account of an STX transfer, the quantity denominated in microstacks, and the recipient, as well as an optional memo field (Note: the memo field can only contain a Clarity buffer type up to 34 bytes in size, pre-fixed with 0x (for example, 0x68656c6c6f21), not ASCII text or strings)
This cBTC smart contract application has a devnet deployment plan that includes broadcasting a BTC transfer transaction to the emulated bitcoin chain with these parameters.