New Default: Latest Epoch for Contract Development

[tippenein]

To encourage staying up-to-date with contract development and ensure consistency between local testing and production deployments, we've introduced a new default for contract epoch settings.

What's Changed

When creating a new contract with clarinet contracts new <name>, you'll now get a contract configured with the 'latest' epoch by default:

Config.toml Example

[contracts.counter]
path = 'contracts/counter.clar'
clarity_version = 3
epoch = 'latest'

Why This Matters

Consistency with Mainnet: When you deploy a contract on Mainnet, it automatically uses the latest epoch. Now your local testing environment will match this behavior by default, reducing surprises during deployment.

Stay Current: Using the latest epoch ensures you're developing with the newest Clarity features and improvements.

Customization Options

You can still specify a particular epoch version if needed (e.g. epoch = 3.0)

Migration

Existing contracts: This change only affects newly created contracts. Your existing contracts will continue to use their current epoch settings.

Upgrading existing contracts: If you want to update existing contracts to use the latest epoch, simply change the epoch value in your Clarinet.toml file.

[Rapha-btc]

Suggestion: Improve error message for epoch-related contract resolution

When using clarinet requirement add followed by adding a contract, if there's an epoch mismatch, Clarinet throws:

error: use of unresolved contract

This is misleading because the contract is added correctly—the issue is that the referenced contract was deployed in a later epoch than the one configured for my contract.

Current behavior: Error message suggests the contract doesn't exist.

Expected behavior: The error should detect this scenario and suggest:

"Contract X was deployed in epoch 3.3, but your contract is configured for epoch 3.2. Consider setting epoch = "latest" in your Clarinet.toml."

Why this matters:

• Devs get stuck debugging a "missing contract" that isn't actually missing
• The fix is simple (epoch = "latest") but non-obvious from the error
• This is especially common when referencing recently-deployed mainnet contracts

Workaround: Set epoch = "latest" in Clarinet.toml so local contracts always use the current mainnet epoch. See: #1963

Nota: Thank you @hugoclrd for kind help and support.

[Rapha-btc]

Bonus Feature idea: Have clarinet requirement add recursively resolve and add all transitive contract dependencies automatically.

[hugo-stacks]

Hey @Rapha-btc, this is already the case