Contract Deployment

Deploy Staxiq smart contracts to Stacks testnet and mainnet

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:

Network	Estimated Cost	Confirmation Time
Devnet	Free	Instant
Testnet	Free (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

Error: Insufficient funds

Solution: Ensure your deployer wallet has enough STX for deployment fees. Get testnet STX from the faucet.

Error: Contract already exists

Solution: Clarity contracts are immutable. You cannot redeploy with the same name. Use a different contract name or deployer address.

Error: Invalid Clarity syntax

Solution: Run clarinet check to validate your contract syntax before deployment.

Error: Transaction timeout

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