Customizing deployment plans
Learn how to customize your deployment plans.
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.
In this guide, you will learn how to:
- Generate and configure a deployment plan.
- Set deployment plan specifications.
- Add project contract requirements.
- Customize your deployment plan.
Generate a deployment plan
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)
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:
Deployment plan specifications
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
- Stacking orders
Adding project contract requirements
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).
Edit your deployment plan
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.
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:
emulated-contract-publish: Deploy a contract in an in-memory simulated chain.
emulated-contract-call: Call a contract that has been deployed in an in-memory simulated chain.
requirement-publish: Deploy an external contract on another testnet/devnet using another wallet.
contract-publish: Deploy a contract.
contract-call: Call a contract.
stx-transfer: Transfer STX between specified accounts.
btc-transfer: Simple bitcoin transfer from a p2pkh address to a p2pkh address (experimental, regtest/testnet/mainnet).
emulated-contract-publish
This default transaction is included in every generated deployment for a simnet deployment.
emulated-contract-call
This is a transaction type for a simnet deployment where the developer wants to emulate a contract call.
Read-only functions and functions that take no arguments are passed an empty list like so: parameters: []
requirement-publish
This cBTC smart contract application has a devnet deployment plan that publishes the contract required by its core smart contract.
contract-publish
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.
contract-call
The developer can call a function and pass arguments of any valid Clarity type.
Read-only functions and functions that take no arguments are passed an empty list like so: parameters: []
stx-transfer
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)
btc-transfer
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.