Skip to main content

​
Overview

Staxiq smart contracts are deployed using Clarinet, the official Stacks smart contract development tool. This guide covers local development, testnet deployment, and mainnet deployment.
Clarity contracts are immutable after deployment. Thoroughly test on testnet before deploying to mainnet.

​
Prerequisites

1

Install Clarinet

Install Clarinet CLI:
# macOS/Linux
curl -L https://github.com/hirosystems/clarinet/releases/latest/download/clarinet-linux-x64.tar.gz | tar xz
sudo mv clarinet /usr/local/bin/

# Or via Homebrew (macOS)
brew install clarinet

# Windows
scoop install clarinet
Verify installation:
clarinet --version
2

Get Testnet STX

For testnet deployment, get free STX from the Stacks Faucet
3

Prepare Wallet

Export your wallet’s private key or mnemonic phrase for deployment

​
Project Structure

The Staxiq contracts repository has the following structure: 
staxiq-contracts/
├── Clarinet.toml          # Project configuration
├── contracts/
│   └── staxiq-user-profile.clar  # Main contract
├── tests/
│   └── staxiq-user-profile.test.ts  # Contract tests
├── settings/
│   ├── Devnet.toml        # Local devnet config
│   ├── Testnet.toml       # Testnet config
│   └── Mainnet.toml       # Mainnet config
├── deployments/           # Deployment plans
└── package.json

​
Clarinet Configuration

The main configuration file defines the contract:
Clarinet.toml
[project]
name = 'staxiq-contracts'
description = ''
authors = []
telemetry = false
cache_dir = '.\.cache'
requirements = []

[contracts.staxiq-user-profile]
path = 'contracts/staxiq-user-profile.clar'
clarity_version = 4
epoch = 'latest'

[repl.analysis]
passes = [
    'call_checker',
    'check_checker',
]
​
clarity_version
number
Staxiq uses Clarity 4 (latest version as of 2026)
​
epoch
string
Set to 'latest' to use the most recent Stacks epoch features

​
Local Development

​
Start Clarinet Console

Test contract functions interactively: 
clarinet console
In the console, you can call contract functions: 
;; Set risk profile
(contract-call? .staxiq-user-profile set-risk-profile u2)
;; Returns: (ok u2)

;; Get user profile
(contract-call? .staxiq-user-profile get-user-profile tx-sender)
;; Returns: (ok { risk-level: u2, created-at: u1, updated-at: u1, strategy-count: u0 })

;; Save strategy
(contract-call? .staxiq-user-profile save-strategy
  "a1b2c3d4e5f6789012345678901234567890123456789012345678901234"
  "ALEX")
;; Returns: (ok u1)

​
Run Tests

Run the test suite: 
npm test
With coverage and cost analysis: 
npm run test:report
Watch mode for development: 
npm run test:watch
Always run tests before deployment to catch bugs early.

​
Testnet Deployment

​
1. Configure Testnet Settings

Create or edit settings/Testnet.toml:
settings/Testnet.toml
[network]
name = "testnet"

[accounts.deployer]
mnemonic = "your twelve word seed phrase here..."
# Or use keychain:
# keychain = "~/.stacks-cli/testnet-deployer.json"
Never commit your mnemonic or private key to version control. Use environment variables or a secure keychain.

​
2. Check Contract Validity

Validate your contract before deploying: 
clarinet check
This runs static analysis and checks for common issues.

​
3. Deploy to Testnet

Deploy the contract: 
clarinet deployments generate --testnet
clarinet deployments apply -p deployments/default.testnet-plan.yaml
Or use the integrated deployment command: 
clarinet integrate --testnet

​
4. Verify Deployment

After deployment, you’ll see output like: 
✅ Contract deployed successfully!
Contract ID: ST9ZZEP9M6VZ9YJA0P69H313CRPV0HQ1ZNPVS8NZ.staxiq-user-profile
Transaction: 0xabc123...
Verify on Testnet Explorer: 
https://explorer.hiro.so/txid/0xabc123...?chain=testnet

​
Mainnet Deployment

Mainnet deployment is permanent and immutable. Triple-check everything before deploying.

​
Pre-Deployment Checklist

1

Test Thoroughly

  • All unit tests pass
  • Integration tests on testnet successful
  • Security audit completed (for high-value contracts)
  • Gas costs estimated and acceptable
2

Prepare Mainnet Wallet

  • Mainnet wallet has sufficient STX for deployment fees
  • Private key/mnemonic securely stored
  • Deployment address verified
3

Documentation Ready

  • Contract functions documented
  • Integration guide complete
  • User documentation prepared

​
1. Configure Mainnet Settings

settings/Mainnet.toml
[network]
name = "mainnet"

[accounts.deployer]
# Use keychain for mainnet (more secure)
keychain = "~/.stacks-cli/mainnet-deployer.json"

​
2. Generate Deployment Plan

clarinet deployments generate --mainnet
Review the generated plan in deployments/default.mainnet-plan.yaml: 
---
id: 0
name: Default
network: mainnet
stacks-node: https://api.hiro.so
contracts:
  staxiq-user-profile:
    path: contracts/staxiq-user-profile.clar
    cost:
      execute: 50000
      read_count: 0
      read_length: 0
      runtime: 10000
      write_count: 3
      write_length: 150
Review the estimated costs carefully. Deployment fees depend on contract size and complexity.

​
3. Deploy to Mainnet

clarinet deployments apply -p deployments/default.mainnet-plan.yaml
Confirm the deployment: 
⚠️  You are about to deploy to MAINNET
Contract: staxiq-user-profile
Deployer: SP...
Estimated cost: ~0.5 STX

Continue? (y/n): y

​
4. Save Deployment Info

After successful deployment, save the contract details:
deployments/mainnet-deployment.json
{
  "contract_id": "SP1234567890ABCDEF.staxiq-user-profile",
  "deployer": "SP1234567890ABCDEF",
  "transaction_id": "0xabc123...",
  "block_height": 150000,
  "deployed_at": "2026-03-09T10:30:00Z"
}

​
5. Update Frontend Configuration

Update your frontend to use the mainnet contract address:
src/services/contractService.js
// Update CONTRACT_ADDRESS to mainnet deployment
const CONTRACT_ADDRESS = 'SP1234567890ABCDEF';
const CONTRACT_NAME = 'staxiq-user-profile';

function getNetwork() {
    return window.location.hostname === 'staxiq.ai'
        ? STACKS_MAINNET
        : STACKS_TESTNET;
}

​
Deployment Costs

Estimated costs for deploying staxiq-user-profile.clar:
NetworkEstimated CostConfirmation Time
DevnetFreeInstant
TestnetFree (use faucet)~10 minutes
Mainnet~0.3-0.8 STX~10 minutes
Actual costs vary based on network congestion and contract complexity.

​
Post-Deployment

​
Verify Contract on Explorer

Check your deployed contract:

Testnet Explorer

View testnet deployments and transactions

Mainnet Explorer

View mainnet deployments and transactions

​
Update Documentation

After deployment:
  1. Update contract addresses in documentation
  2. Publish API reference with deployed contract ID
  3. Update integration guides with mainnet examples
  4. Announce deployment to users

​
Monitor Contract Usage

Track contract interactions: 
# Get contract info
curl https://api.mainnet.hiro.so/v2/contracts/interface/SP.../staxiq-user-profile

# Get recent transactions
curl https://api.mainnet.hiro.so/extended/v1/address/SP.../transactions

​
Troubleshooting

​
Common Issues

Solution: Ensure your deployer wallet has enough STX for deployment fees. Get testnet STX from the faucet.
Solution: Clarity contracts are immutable. You cannot redeploy with the same name. Use a different contract name or deployer address.
Solution: Run clarinet check to validate your contract syntax before deployment.
Solution: Network congestion can delay transactions. Wait 15-20 minutes and check the explorer. Increase the fee for faster confirmation.

​
Getting Help

Clarinet Docs

Official Clarinet documentation

Stacks Discord

Get help from the Stacks community

Hiro Support

Contact Hiro for technical support

GitHub Issues

Report bugs or request features

​
Next Steps

Testing

Learn how to test contracts before deployment

Integration

Integrate deployed contracts into your frontend

Build docs developers (and LLMs) love

Get started for freeTalk to us