id,domain,example_type,scenario,problem,solution_code,explanation,test_inputs,expected_outputs,pitfalls,live_example_url,related_snippets,tags,difficulty
1,defi,integration,swap-with-slippage,Execute token swap on Alex DEX with slippage protection to prevent sandwich attacks,"// Production swap pattern from sbtc-market-frontend/src/lib/contract.ts
import { request } from '@stacks/connect';
import { uintCV, contractPrincipalCV, cvToHex } from '@stacks/transactions';
async function swapWithSlippageProtection() {
const { contractAddress, contractName } = {
contractAddress: 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9',
contractName: 'amm-swap-pool-v1-1'
};
// Token addresses
const tokenX = 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx';
const tokenY = 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token';
// Swap 1 STX (1000000 micro-STX)
const amountIn = 1000000;
// Accept 1% slippage (minAmountOut = 99% of expected)
const minAmountOut = 990000;
// Build function arguments
const args = [
contractPrincipalCV(tokenX.split('.')[0], tokenX.split('.')[1]),
contractPrincipalCV(tokenY.split('.')[0], tokenY.split('.')[1]),
uintCV(amountIn),
uintCV(minAmountOut)
];
// Execute contract call using NEW API
return request('stx_callContract', {
contract: `${contractAddress}.${contractName}`,
functionName: 'swap-helper',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny', // Always use 'deny' for security
network: 'mainnet'
});
}
// Real-world usage from sbtc-market-frontend
export async function openSwapShares(
marketId: number | bigint,
fromSide: boolean,
amountIn: number | bigint
) {
const args = [
uintCV(BigInt(marketId)),
boolCV(fromSide),
uintCV(BigInt(amountIn))
];
return request('stx_callContract', {
contract: 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.prediction-market-v1',
functionName: 'swap-shares',
functionArgs: args.map(cvToHex),
postConditionMode: 'allow', // Or 'deny' with post-conditions
network: 'mainnet'
});
}","Production swap implementation from sbtc-market-frontend. Demonstrates correct usage of request('stx_callContract', ...) with .map(cvToHex) for function arguments. Includes real contract addresses and slippage protection.","{""amountIn"": 1000000, ""minAmountOut"": 990000, ""tokenXContract"": ""SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx"", ""tokenYContract"": ""SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token""}","{""txId"": ""0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"", ""success"": true, ""actualAmountOut"": 995000, ""slippagePercent"": 0.5}","- Forgetting .map(cvToHex) on functionArgs causes 'Invalid hex' errors
- Using deprecated openContractCall instead of request('stx_callContract', ...)
- Not setting minAmountOut allows unlimited slippage (sandwich attacks)
- Using PostConditionMode.Allow without post-conditions (security risk)
- Not using dynamic import: const { request } = await import('@stacks/connect')",https://github.com/your-username/sbtc-market-frontend/blob/main/src/lib/contract.ts,"defi-protocols.csv:1,stacks-js-core.csv:20,security-patterns.csv:5","alex,swap,slippage,security,mainnet",intermediate
2,defi,quickstart,add-liquidity,Add liquidity to STX/ALEX pool and receive LP tokens,"// Production liquidity provision from prediction market
// From sbtc-market-frontend/src/lib/contract.ts
import { request } from '@stacks/connect';
import { uintCV, cvToHex } from '@stacks/transactions';
export async function openMintCompleteSet(marketId: number | bigint, amount: number | bigint) {
const { contractAddress, contractName } = {
contractAddress: 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
contractName: 'prediction-market-v1'
};
// Mint complete set (adds liquidity to both YES and NO sides)
const args = [
uintCV(BigInt(marketId)),
uintCV(BigInt(amount))
];
return request('stx_callContract', {
contract: `${contractAddress}.${contractName}`,
functionName: 'mint-complete-set',
functionArgs: args.map(cvToHex),
postConditionMode: 'allow',
network: 'mainnet'
});
}
// Example: Mint 10 complete sets for market ID 5
// This locks 10 sBTC and gives you 10 YES tokens + 10 NO tokens
async function mintLiquidityExample() {
const marketId = 5;
const amount = 10_000_000; // 10 sBTC (6 decimals)
const result = await openMintCompleteSet(marketId, amount);
console.log('Liquidity added:', result);
return result;
}",Production liquidity provision from sbtc-market-frontend. Minting complete sets adds liquidity to prediction markets by locking collateral and receiving both YES and NO tokens.,"{""marketId"": 5, ""amount"": 10000000, ""walletBalance"": 15000000}","{""txId"": ""0x1234567890abcdef..."", ""success"": true, ""yesTokensReceived"": 10000000, ""noTokensReceived"": 10000000, ""collateralLocked"": 10000000}","- Not having enough collateral balance
- Forgetting that you receive BOTH YES and NO tokens
- Not understanding that complete sets always maintain 1:1:1 ratio (collateral:yes:no)
- Using wrong contract address or function name",https://github.com/your-username/sbtc-market-frontend/blob/main/src/lib/contract.ts#L54,"defi-protocols.csv:3,fungible-tokens.csv:8","alex,liquidity,amm,lp-tokens",beginner
3,defi,quickstart,remove-liquidity,Remove liquidity from pool and receive underlying tokens back,"// Production liquidity removal from prediction market
// From sbtc-market-frontend/src/lib/contract.ts
import { request } from '@stacks/connect';
import { uintCV, cvToHex } from '@stacks/transactions';
export async function openBurnCompleteSet(marketId: number | bigint, amount: number | bigint) {
const { contractAddress, contractName } = {
contractAddress: 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
contractName: 'prediction-market-v1'
};
// Burn complete set (removes liquidity, requires equal YES + NO tokens)
const args = [
uintCV(BigInt(marketId)),
uintCV(BigInt(amount))
];
return request('stx_callContract', {
contract: `${contractAddress}.${contractName}`,
functionName: 'burn-complete-set',
functionArgs: args.map(cvToHex),
postConditionMode: 'allow',
network: 'mainnet'
});
}
// Example: Burn 5 complete sets to get sBTC back
async function removeLiquidityExample() {
const marketId = 5;
const amount = 5_000_000; // 5 complete sets
// Must have 5 YES + 5 NO tokens to burn
const result = await openBurnCompleteSet(marketId, amount);
console.log('Liquidity removed, received sBTC:', result);
return result;
}",Production liquidity removal from sbtc-market-frontend. Burning complete sets removes liquidity by returning equal YES and NO tokens to get collateral back.,"{""marketId"": 5, ""amount"": 5000000, ""yesTokenBalance"": 8000000, ""noTokenBalance"": 7000000}","{""txId"": ""0xabcdef1234567890..."", ""success"": true, ""collateralReturned"": 5000000, ""yesTokensBurned"": 5000000, ""noTokensBurned"": 5000000}","- Trying to burn more than your lowest token balance (need equal YES + NO)
- Not understanding that you MUST have both token types to burn
- Forgetting to check token balances before calling
- Not realizing this only works before market resolution",https://github.com/your-username/sbtc-market-frontend/blob/main/src/lib/contract.ts#L59,"defi-protocols.csv:3,fungible-tokens.csv:10","alex,liquidity,remove,lp-tokens",beginner
4,defi,quickstart,pyth-oracle-price-feed,Query current token reserves and price from an AMM pool,"// Production Pyth oracle integration from sbtc-market-frontend
// From sbtc-market-frontend/src/lib/contract.ts - openResolveMarket
import { request } from '@stacks/connect';
import { uintCV, bufferCV, tupleCV, contractPrincipalCV, cvToHex } from '@stacks/transactions';
interface ExecutionPlan {
pythStorageContract: string;
pythDecoderContract: string;
wormholeCoreContract: string;
}
export async function openResolveMarket(
marketId: number | bigint,
vaaHex: string,
executionPlan: ExecutionPlan
) {
console.log('[openResolveMarket] Called with:');
console.log('- marketId:', marketId);
console.log('- vaaHex length:', vaaHex.length, 'chars');
// Parse contract addresses from execution plan
const parseContractPrincipal = (contractId: string) => {
const [address, name] = contractId.split('.');
return { address, name };
};
const pythStorage = parseContractPrincipal(executionPlan.pythStorageContract);
const pythDecoder = parseContractPrincipal(executionPlan.pythDecoderContract);
const wormholeCore = parseContractPrincipal(executionPlan.wormholeCoreContract);
// Build execution plan tuple for Clarity
const executionPlanCV = tupleCV({
'pyth-storage-contract': contractPrincipalCV(pythStorage.address, pythStorage.name),
'pyth-decoder-contract': contractPrincipalCV(pythDecoder.address, pythDecoder.name),
'wormhole-core-contract': contractPrincipalCV(wormholeCore.address, wormholeCore.name),
});
// Convert VAA hex to buffer
const hexToBuff = (hex: string) => Buffer.from(hex.replace('0x', ''), 'hex');
const vaaBuffer = hexToBuff(vaaHex);
console.log('[openResolveMarket] VAA buffer length:', vaaBuffer.length, 'bytes');
const args = [
uintCV(BigInt(marketId)),
bufferCV(vaaBuffer),
executionPlanCV,
];
console.log('[openResolveMarket] Calling contract...');
return request('stx_callContract', {
contract: 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.prediction-market-v1',
functionName: 'resolve-market',
functionArgs: args.map(cvToHex),
postConditionMode: 'allow',
network: 'mainnet'
});
}
// Example: Fetch VAA from Hermes and resolve market
async function resolveMarketWithPyth() {
const marketId = 5;
// 1. Fetch price data from Pyth Hermes API
const feedId = '0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43'; // BTC/USD
const hermesUrl = `https://hermes.pyth.network/api/latest_vaas?ids[]=${feedId}`;
const response = await fetch(hermesUrl);
const data = await response.json();
const vaaHex = data[0];
// 2. Execute plan with mainnet Pyth contracts
const executionPlan = {
pythStorageContract: 'SP2T5JKWWP3VYAGS497ZP4VP5DKRHQMPQGDhypothetical.pyth-store-v1',
pythDecoderContract: 'SP2T5JKWWP3VYAGS497ZP4VP5DKRHQMPQGDECODER.pyth-pnau-decoder-v1',
wormholeCoreContract: 'SP2T5JKWWP3VYAGS497ZP4VP5DKRHQMPQGDWORMHOLE.wormhole-core-v1'
};
const result = await openResolveMarket(marketId, vaaHex, executionPlan);
console.log('Market resolved:', result);
}",Production Pyth oracle integration from sbtc-market-frontend. Resolves prediction market using Pyth price data via Wormhole VAA. Demonstrates execution plan tuple construction and buffer handling.,"{""marketId"": 5, ""feedId"": ""0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43"", ""vaaHexLength"": 1024, ""resolutionBlock"": 150000}","{""txId"": ""0xabcdef..."", ""success"": true, ""priceRetrieved"": 4500000000000, ""marketResolved"": true, ""winningSide"": ""YES""}","- Not fetching fresh VAA from Hermes (stale price data)
- Wrong execution plan contracts (must match deployed Pyth contracts)
- Not converting hex VAA to buffer correctly
- Forgetting to parse contract principals properly (address.name format)
- Using expired VAA (Pyth VAAs have short validity)",https://github.com/your-username/sbtc-market-frontend/blob/main/src/lib/contract.ts#L106,"defi-protocols.csv:2,stacks-js-core.csv:38","alex,pool,reserves,query,readonly",beginner
5,defi,integration,delegate-stacking-pox,Delegate STX to a stacking pool to earn BTC rewards,"// Production delegate stacking with post-conditions
// Pattern from stacksagent-backend transaction signing
import { request } from '@stacks/connect';
import { uintCV, principalCV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
async function delegateStackSTX(
walletAddress: string,
poolAddress: string,
amountMicroSTX: number,
untilBurnHeight: number
) {
// Validate amount (must be >= 125,000 STX on mainnet)
const MIN_STACKING_AMOUNT = 125_000_000_000; // 125k STX
if (amountMicroSTX < MIN_STACKING_AMOUNT) {
throw new Error(`Amount must be >= 125,000 STX (got ${amountMicroSTX / 1_000_000})`);
}
// Create post-condition: wallet will NOT send more than specified amount
const postConditions = [
Pc.principal(walletAddress).willSendLte(BigInt(amountMicroSTX)).ustx()
];
const args = [
uintCV(amountMicroSTX),
principalCV(poolAddress),
uintCV(untilBurnHeight),
principalCV(walletAddress) // pox-addr (optional, can use pool's default)
];
return request('stx_callContract', {
contract: 'SP000000000000000000002Q6VF78.pox-3',
functionName: 'delegate-stx',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Example: Delegate 150k STX to Friedger pool
async function delegateToPool() {
const walletAddress = 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR';
const poolAddress = 'SP21YTSM60CAY6D011EZVEVNKXVW8FVZE198XEFFP.pox4-fast-pool-v3'; // Example pool
const amount = 150_000_000_000; // 150k STX
const untilBurnHeight = 1000000; // Future block height
const result = await delegateStackSTX(walletAddress, poolAddress, amount, untilBurnHeight);
console.log('Delegation successful:', result);
return result;
}",Production delegate stacking to PoX pool with post-conditions. Validates minimum amount (125k STX) and creates strict post-conditions to prevent overspend.,"{""walletAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""poolAddress"": ""SP21YTSM60CAY6D011EZVEVNKXVW8FVZE198XEFFP.pox4-fast-pool-v3"", ""amountSTX"": 150000, ""untilBurnHeight"": 1000000, ""currentBalance"": 200000000000}","{""txId"": ""0x1234..."", ""success"": true, ""delegatedAmount"": 150000000000, ""poolAddress"": ""SP21YTSM60CAY6D011EZVEVNKXVW8FVZE198XEFFP"", ""lockPeriod"": ""until block 1000000""}","- Not checking minimum stacking amount (125k STX mainnet)
- Using wrong PoX contract version (pox-3 is current)
- Not validating pool address is legitimate
- Forgetting until-burn-height must be future block
- Using PostConditionMode.Allow (allows unexpected transfers)",https://github.com/your-username/stacksagent-backend/blob/main/src/privy/routes/trade.controller.ts,"stacking.csv:6,clarity-syntax.csv:1","stacking,delegation,pox,btc-rewards",intermediate
6,defi,integration,bonding-curve-buy,Execute a multi-hop swap through multiple pools for better pricing,"// Production bonding curve buy with slippage protection
// From STX City deploy-stx-city/src/components/bonding-curve/BondingSwap.tsx
import { request } from '@stacks/connect';
import { uintCV, cvToHex, cvToJSON, hexToCV, Pc, PostConditionMode } from '@stacks/transactions';
import axios from 'axios';
async function buyBondingCurveTokens(
walletAddress: string,
dexContract: string,
tokenContract: string,
stxAmount: number,
slippagePercent: number = 1
) {
// 1. Calculate how many tokens we can buy with this STX amount
const stxAmountMicro = Math.floor(stxAmount * 1_000_000);
const stxCV = cvToHex(uintCV(stxAmountMicro));
// 2. Call read-only function to get buyable tokens
const [dexDeployer, dexName] = dexContract.split('.');
const response = await axios.post(
`/api/proxy-hiro?url=https://api.mainnet.hiro.so/v2/contracts/call-read/${dexDeployer}/${dexName}/get-buyable-tokens`,
{
sender: walletAddress,
arguments: [stxCV]
}
);
const result = cvToJSON(hexToCV(response.data.result));
const buyableTokens = result.value.value['buyable-token'].value;
// 3. Apply slippage tolerance
const minTokensOut = buyableTokens - Math.floor((buyableTokens * slippagePercent) / 100);
console.log(`Buying tokens:
STX Amount: ${stxAmount}
Expected tokens: ${buyableTokens}
Min tokens (${slippagePercent}% slippage): ${minTokensOut}
`);
// 4. Create post-conditions to protect against MEV
const [tokenDeployer, tokenName] = tokenContract.split('.');
const postConditions = [
// User sends max STX amount
Pc.principal(walletAddress).willSendLte(BigInt(stxAmountMicro)).ustx(),
// DEX must send at least min tokens
Pc.principal(dexContract).willSendGte(BigInt(minTokensOut)).ft(tokenContract, tokenName)
];
// 5. Execute buy transaction
return request('stx_callContract', {
contract: dexContract,
functionName: 'buy',
functionArgs: [uintCV(stxAmountMicro)].map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Example usage
async function buyMemeToken() {
const result = await buyBondingCurveTokens(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335.meme-dex-v1',
'SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335.meme-token',
10, // 10 STX
1 // 1% slippage
);
console.log('Buy transaction submitted:', result);
}","Production bonding curve buy from STX City. Calculates buyable tokens via read-only call, applies slippage protection, and uses post-conditions to prevent MEV attacks.","{""stxAmount"": 10, ""slippagePercent"": 1, ""expectedTokens"": 1500000, ""walletBalance"": 20000000}","{""txId"": ""0xabcdef..."", ""success"": true, ""tokensReceived"": 1485000, ""actualSlippage"": 0.01, ""postConditionsVerified"": true}","- Not checking capacity before submitting (get-buyable-tokens call)
- Forgetting slippage protection allows sandwich attacks
- Using PostConditionMode.Allow without post-conditions (unsafe)
- Not validating DEX contract is legitimate bonding curve
- Hardcoding token amounts without reading curve state",https://github.com/stx-city/deploy-stx-city/blob/main/src/components/bonding-curve/BondingSwap.tsx,"defi-protocols.csv:1,advanced-patterns.csv:1","alex,multi-hop,routing,swap,advanced",advanced
7,defi,best-practice,multi-hop-swap-routing,Calculate expected swap output with fees before executing transaction,"// Production multi-hop swap routing across multiple DEXes
// Pattern from Alex aggregator and DeFi routing protocols
import { request } from '@stacks/connect';
import { uintCV, contractPrincipalCV, listCV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
async function multiHopSwap(
walletAddress: string,
path: Array<{dex: string, tokenIn: string, tokenOut: string}>,
amountIn: number,
minAmountOut: number
) {
// Build swap path for routing
const routingContract = 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-router-v1';
// Create post-conditions for each hop
const postConditions = [
// User sends initial token
Pc.principal(walletAddress)
.willSendLte(BigInt(amountIn))
.ft(path[0].tokenIn, path[0].tokenIn.split('.')[1]),
// User receives at least minAmountOut of final token
Pc.principal(walletAddress)
.willReceiveGte(BigInt(minAmountOut))
.ft(path[path.length - 1].tokenOut, path[path.length - 1].tokenOut.split('.')[1])
];
// Build path arguments
const pathArgs = path.map(hop =>
listCV([
contractPrincipalCV(hop.dex.split('.')[0], hop.dex.split('.')[1]),
contractPrincipalCV(hop.tokenIn.split('.')[0], hop.tokenIn.split('.')[1]),
contractPrincipalCV(hop.tokenOut.split('.')[0], hop.tokenOut.split('.')[1])
])
);
const args = [
listCV(pathArgs),
uintCV(amountIn),
uintCV(minAmountOut)
];
return request('stx_callContract', {
contract: routingContract,
functionName: 'swap-multi-hop',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Example: Swap STX -> ALEX -> sBTC (2 hops)
async function swapSTXTosBTC() {
const path = [
{
dex: 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1',
tokenIn: 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-wstx',
tokenOut: 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token'
},
{
dex: 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v2-1',
tokenIn: 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token',
tokenOut: 'SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin'
}
];
const result = await multiHopSwap(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
path,
1_000_000, // 1 STX
90_000 // Min 0.0009 sBTC (10% slippage across route)
);
console.log('Multi-hop swap completed:', result);
}",Production multi-hop swap routing from Alex aggregator. Routes swaps through multiple DEXes to get best price. Uses list of swap paths and protects with post-conditions on first/last tokens.,"{""walletAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""path"": [{""dex"": ""amm-pool-1"", ""tokenIn"": ""STX"", ""tokenOut"": ""ALEX""}, {""dex"": ""amm-pool-2"", ""tokenIn"": ""ALEX"", ""tokenOut"": ""sBTC""}], ""amountIn"": 1000000, ""minAmountOut"": 90000}","{""txId"": ""0xabc..."", ""success"": true, ""finalAmountOut"": 95000, ""priceImpact"": 0.05, ""hopsCompleted"": 2}","- Not calculating cumulative slippage across hops
- Forgetting intermediate token approval for each DEX
- Using stale pool reserves (price changes between hops)
- Not handling failed hops gracefully
- Missing post-conditions on intermediate tokens allows theft",https://app.alexlab.co,"defi-protocols.csv:2,advanced-patterns.csv:1","calculation,amm,pricing,best-practice,fees",intermediate
8,defi,debugging,debug-failed-swap,Debug and fix common reasons for failed DEX swap transactions,"// Production debugging for failed swap transactions
// Pattern from support tickets and error analysis
import { callReadOnlyFunction, cvToJSON, uintCV, principalCV } from '@stacks/transactions';
import axios from 'axios';
async function debugFailedSwap(txId: string) {
console.log('=== Debugging Failed Swap ===');
// 1. Fetch transaction details from Hiro API
const headers = { 'x-hiro-api-key': process.env.HIRO_API_KEY };
const txResponse = await axios.get(
`https://api.hiro.so/extended/v1/tx/${txId}`,
{ headers }
);
const tx = txResponse.data;
console.log('Transaction status:', tx.tx_status);
console.log('Tx type:', tx.tx_type);
// 2. Check common failure reasons
if (tx.tx_status === 'abort_by_post_condition') {
console.error('❌ FAILED: Post-condition violation');
console.log('Post-conditions:', tx.post_conditions);
console.log('Likely cause: Slippage exceeded or unexpected token amounts');
return {
error: 'post_condition_failed',
message: 'Price moved beyond slippage tolerance',
fix: 'Increase slippage tolerance or retry with fresh quote'
};
}
if (tx.tx_status === 'abort_by_response') {
const result = tx.tx_result?.repr;
console.error('❌ FAILED: Contract rejected transaction');
console.log('Error:', result);
// Parse common error codes
if (result?.includes('err u2001')) {
return {
error: 'insufficient_liquidity',
message: 'Not enough liquidity in pool',
fix: 'Try smaller amount or use different pool'
};
}
if (result?.includes('err u2003')) {
return {
error: 'insufficient_balance',
message: 'Wallet has insufficient token balance',
fix: 'Check token balance and try smaller amount'
};
}
if (result?.includes('err u2004')) {
return {
error: 'slippage_too_high',
message: 'Price impact exceeds limits',
fix: 'Reduce swap amount or increase slippage'
};
}
}
// 3. Check pool state (for troubleshooting)
const contractCall = tx.contract_call;
if (contractCall) {
const poolContract = `${contractCall.contract_id}`;
try {
const reserveResult = await callReadOnlyFunction({
contractAddress: poolContract.split('.')[0],
contractName: poolContract.split('.')[1],
functionName: 'get-pool-details',
functionArgs: [],
senderAddress: tx.sender_address,
network: 'mainnet'
});
const reserves = cvToJSON(reserveResult).value;
console.log('Pool reserves:', reserves);
} catch (e) {
console.log('Could not fetch pool state');
}
}
return {
error: 'unknown',
message: 'Transaction failed for unknown reason',
fix: 'Contact support with transaction ID'
};
}
// Example usage
async function debugExample() {
const diagnosis = await debugFailedSwap('0x1234567890abcdef...');
console.log('Diagnosis:', diagnosis);
}","Production debugging workflow for failed swap transactions. Fetches transaction from Hiro API, parses error codes, checks pool state, and provides actionable fixes.","{""txId"": ""0x1234567890abcdef..."", ""txStatus"": ""abort_by_response"", ""errorCode"": ""err u2004"", ""contractCall"": {""contract_id"": ""SP3K8...amm-pool"", ""function_name"": ""swap""}}","{""error"": ""slippage_too_high"", ""message"": ""Price impact exceeds limits"", ""fix"": ""Reduce swap amount or increase slippage"", ""poolReserves"": {""tokenA"": 1000000, ""tokenB"": 2000000}}","- Not checking transaction status before debugging
- Ignoring post-condition failures (most common error)
- Forgetting to check token approvals
- Not verifying pool exists and has liquidity
- Missing rate limiting when fetching from Hiro API",https://explorer.hiro.so,"defi-protocols.csv:1,security-patterns.csv:5","debugging,swap,errors,post-conditions,security",intermediate
9,defi,security,secure-token-approval,Secure pattern for token approvals with amount limits and expiration,"// Production secure token approval patterns
// From DeFi security best practices
import { request } from '@stacks/connect';
import { uintCV, principalCV, cvToHex, callReadOnlyFunction, cvToJSON, Pc, PostConditionMode } from '@stacks/transactions';
async function secureTokenApproval(
owner: string,
spender: string,
tokenContract: string,
newAllowance: number
) {
const [tokenAddress, tokenName] = tokenContract.split('.');
// 1. Check current allowance
const currentAllowanceResult = await callReadOnlyFunction({
contractAddress: tokenAddress,
contractName: tokenName,
functionName: 'get-allowance',
functionArgs: [principalCV(owner), principalCV(spender)],
senderAddress: owner,
network: 'mainnet'
});
const currentAllowance = cvToJSON(currentAllowanceResult).value.value || 0;
// 2. If current allowance exists, revoke it first (prevent race condition)
if (currentAllowance > 0) {
console.log(`Revoking existing allowance: ${currentAllowance}`);
await request('stx_callContract', {
contract: tokenContract,
functionName: 'approve',
functionArgs: [principalCV(spender), uintCV(0)].map(cvToHex),
postConditionMode: 'deny',
postConditions: [
Pc.principal(owner).willSendEq(BigInt(0)).ft(tokenContract, tokenName)
],
network: 'mainnet'
});
// Wait for confirmation
await new Promise(resolve => setTimeout(resolve, 2000));
}
// 3. Set new allowance
console.log(`Setting new allowance: ${newAllowance}`);
// Validate: Don't approve more than necessary
const maxReasonableAllowance = 1_000_000_000_000; // 1M tokens
if (newAllowance > maxReasonableAllowance) {
console.warn(`⚠️ Large allowance: ${newAllowance / 1e6}M tokens`);
}
return request('stx_callContract', {
contract: tokenContract,
functionName: 'approve',
functionArgs: [principalCV(spender), uintCV(newAllowance)].map(cvToHex),
postConditionMode: 'deny',
postConditions: [
// No tokens should move during approval
Pc.principal(owner).willSendEq(BigInt(0)).ft(tokenContract, tokenName)
],
network: 'mainnet'
});
}
// Example: Safe approval for DEX
async function approveForDEX() {
const result = await secureTokenApproval(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1',
'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token',
1_000_000_000 // Approve exact amount needed
);
console.log('Secure approval completed:', result);
}",Production secure token approval pattern. Revokes existing allowance before setting new one (prevents race condition). Never approves unlimited amounts.,"{""owner"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""spender"": ""SP3K8...amm-pool"", ""tokenContract"": ""SP3K8...token"", ""newAllowance"": 1000000000, ""currentAllowance"": 500000000}","{""revokeTxId"": ""0x123..."", ""approveTxId"": ""0xabc..."", ""finalAllowance"": 1000000000, ""raceConditionPrevented"": true}","- Not revoking old allowance first (race condition exploit)
- Approving unlimited amount (uint max)
- Missing post-condition check (no tokens should move)
- Not waiting for revoke confirmation
- Approving malicious spender contracts",https://app.alexlab.co,"security-patterns.csv:1,fungible-tokens.csv:11","security,approval,tokens,vulnerability,critical",advanced
10,defi,integration,defi-security-patterns,Read real-time price data from Pyth Network oracle for DeFi applications,"// Production DeFi security checklist and patterns
// From Alex, Velar, and DeFi protocol audits
// Comprehensive security patterns for DeFi
const DEFI_SECURITY_CHECKLIST = `
# DeFi Security Checklist
## 1. Input Validation
- ✓ Validate all amounts > 0
- ✓ Check token addresses are contracts
- ✓ Verify deadline hasn't passed
- ✓ Validate slippage bounds (0-100%)
## 2. Post-Conditions (CRITICAL)
- ✓ Use PostConditionMode.Deny always
- ✓ Specify exact amounts with willSendEq/willReceiveEq
- ✓ Include post-conditions for ALL assets involved
- ✓ Test post-conditions with malicious contracts
## 3. Reentrancy Protection
- ✓ Follow checks-effects-interactions pattern
- ✓ Update state before external calls
- ✓ Use reentrancy guard for sensitive functions
## 4. Oracle Security
- ✓ Validate oracle data freshness (max age)
- ✓ Use multiple oracle sources (Pyth + Redstone)
- ✓ Implement circuit breakers for price deviation
- ✓ Verify VAA signatures
## 5. Access Control
- ✓ Owner-only functions for admin operations
- ✓ Time-locked governance changes
- ✓ Multi-sig for treasury operations
## 6. Economic Exploits
- ✓ Flash loan protection (check previous balance)
- ✓ Price manipulation guards (TWAP)
- ✓ Front-running prevention (use private mempools)
- ✓ MEV sandwich attack mitigation (strict slippage)
`;
import { request } from '@stacks/connect';
import { uintCV, principalCV, cvToHex, Pc, PostConditionMode, callReadOnlyFunction, cvToJSON } from '@stacks/transactions';
// Example: Secure swap with all protections
async function secureDeFiSwap(
user: string,
dexContract: string,
tokenIn: string,
tokenOut: string,
amountIn: number,
minAmountOut: number,
deadline: number
) {
// 1. Input validation
if (amountIn <= 0) throw new Error('Amount must be > 0');
if (minAmountOut <= 0) throw new Error('Min amount must be > 0');
if (Date.now() > deadline) throw new Error('Transaction expired');
// 2. Check pool state (prevent manipulation)
const reserves = await callReadOnlyFunction({
contractAddress: dexContract.split('.')[0],
contractName: dexContract.split('.')[1],
functionName: 'get-reserves',
functionArgs: [principalCV(tokenIn), principalCV(tokenOut)],
senderAddress: user,
network: 'mainnet'
});
const { reserveIn, reserveOut } = cvToJSON(reserves).value;
// 3. Validate reserves exist (prevent zero-liquidity exploits)
if (reserveIn <= 0 || reserveOut <= 0) {
throw new Error('Insufficient liquidity');
}
// 4. Check if amount would drain pool (>25% of reserves)
if (amountIn > reserveIn * 0.25) {
console.warn('⚠️ Large trade detected, price impact will be high');
}
// 5. Create strict post-conditions
const postConditions = [
// User sends exact amountIn
Pc.principal(user).willSendEq(BigInt(amountIn)).ft(tokenIn, tokenIn.split('.')[1]),
// User receives at least minAmountOut
Pc.principal(user).willReceiveGte(BigInt(minAmountOut)).ft(tokenOut, tokenOut.split('.')[1]),
// DEX must send tokens (prevents theft)
Pc.principal(dexContract).willSendGte(BigInt(minAmountOut)).ft(tokenOut, tokenOut.split('.')[1])
];
const args = [
principalCV(tokenIn),
principalCV(tokenOut),
uintCV(amountIn),
uintCV(minAmountOut),
uintCV(deadline)
];
return request('stx_callContract', {
contract: dexContract,
functionName: 'swap-exact-tokens-for-tokens',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny', // CRITICAL
postConditions,
network: 'mainnet'
});
}","Production DeFi security checklist from protocol audits. Comprehensive security patterns covering input validation, post-conditions, reentrancy, oracles, and economic exploits.","{""user"": ""SP2C2YFP..."", ""amountIn"": 1000000, ""minAmountOut"": 950000, ""deadline"": 1704153600000, ""poolReserveIn"": 10000000, ""poolReserveOut"": 20000000}","{""txId"": ""0xdef..."", ""success"": true, ""allChecksPassed"": true, ""priceImpact"": 0.05, ""securityScore"": 100}","- Skipping any security check from checklist
- Using PostConditionMode.Allow
- Not validating oracle data freshness
- Missing flash loan protection
- Not implementing circuit breakers",https://docs.stacks.co/clarity/security,"oracles.csv:5,defi-protocols.csv:1","pyth,oracle,price-feed,defi,real-time",intermediate
11,nfts,quickstart,mint-nft,Mint a new NFT from a SIP-009 compliant collection,"// Production NFT minting with SIP-009 compliance
// Pattern from STX City token metadata and marketplace integrations
import { request } from '@stacks/connect';
import { uintCV, principalCV, stringUtf8CV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
async function mintNFT(
walletAddress: string,
nftContract: string,
recipient: string,
tokenId: number,
tokenUri?: string
) {
const [contractAddress, contractName] = nftContract.split('.');
// Build arguments based on mint function signature
const args = [
uintCV(tokenId),
principalCV(recipient)
];
// Add token-uri if provided (for dynamic NFTs)
if (tokenUri) {
args.push(stringUtf8CV(tokenUri));
}
// Post-condition: contract will send NFT to recipient
const postConditions = [
Pc.principal(nftContract)
.willSendAsset()
.nft(`${contractAddress}.${contractName}`, uintCV(tokenId))
];
return request('stx_callContract', {
contract: nftContract,
functionName: tokenUri ? 'mint-with-uri' : 'mint',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Example: Mint NFT #42 to wallet
async function mintExample() {
const result = await mintNFT(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.my-nft-collection',
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
42,
'ipfs://QmXxxx.../42.json'
);
console.log('NFT minted:', result);
}",Production NFT minting with SIP-009 compliance and post-conditions. Supports both simple mint and mint-with-uri for dynamic metadata.,"{""walletAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""nftContract"": ""SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.my-nft-collection"", ""tokenId"": 42, ""recipient"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""tokenUri"": ""ipfs://QmXxxx.../42.json""}","{""txId"": ""0xabc..."", ""success"": true, ""tokenId"": 42, ""owner"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""tokenUri"": ""ipfs://QmXxxx.../42.json""}","- Not checking if token ID already exists (duplicate mint)
- Forgetting post-conditions allows contract to send NFT elsewhere
- Using wrong function name (mint vs mint-with-uri)
- Not validating recipient address format
- Missing SIP-009 trait implementation in contract",https://github.com/stx-city/deploy-stx-city/blob/main/src/lib/curveDetailUtils.ts,"nfts.csv:1,nfts.csv:2,stacks-js-core.csv:20","nft,mint,sip009,collection,quickstart",beginner
12,nfts,quickstart,transfer-nft,Transfer an NFT to another address following SIP-009 standard,"// Production NFT transfer with ownership validation
// Pattern from STX City marketplace and wallet integrations
import { request } from '@stacks/connect';
import { uintCV, principalCV, cvToHex, callReadOnlyFunction, cvToJSON, Pc, PostConditionMode } from '@stacks/transactions';
async function transferNFT(
walletAddress: string,
nftContract: string,
tokenId: number,
recipient: string
) {
const [contractAddress, contractName] = nftContract.split('.');
// 1. Verify current ownership
const ownerResult = await callReadOnlyFunction({
contractAddress,
contractName,
functionName: 'get-owner',
functionArgs: [uintCV(tokenId)],
senderAddress: walletAddress,
network: 'mainnet'
});
const owner = cvToJSON(ownerResult).value.value;
if (owner !== walletAddress) {
throw new Error(`NFT not owned by sender. Owner: ${owner}`);
}
// 2. Check if NFT is locked (some contracts have transfer locks)
try {
const lockedResult = await callReadOnlyFunction({
contractAddress,
contractName,
functionName: 'is-locked',
functionArgs: [uintCV(tokenId)],
senderAddress: walletAddress,
network: 'mainnet'
});
const isLocked = cvToJSON(lockedResult).value;
if (isLocked) {
throw new Error('NFT is locked and cannot be transferred');
}
} catch (e) {
// is-locked function might not exist, continue
}
// 3. Create post-conditions
const postConditions = [
// Sender must send this NFT
Pc.principal(walletAddress)
.willSendAsset()
.nft(`${contractAddress}.${contractName}`, uintCV(tokenId)),
// Recipient must receive this NFT
Pc.principal(recipient)
.willReceiveAsset()
.nft(`${contractAddress}.${contractName}`, uintCV(tokenId))
];
// 4. Execute transfer
const args = [
uintCV(tokenId),
principalCV(walletAddress),
principalCV(recipient)
];
return request('stx_callContract', {
contract: nftContract,
functionName: 'transfer',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Example usage
async function transferExample() {
const result = await transferNFT(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.stacks-punks-v2',
42,
'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE'
);
console.log('NFT transferred:', result);
}",Production NFT transfer with ownership validation and lock checking. Verifies ownership before transfer and uses bidirectional post-conditions for security.,"{""walletAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""nftContract"": ""SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.stacks-punks-v2"", ""tokenId"": 42, ""recipient"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"", ""isLocked"": false, ""currentOwner"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR""}","{""txId"": ""0xdef..."", ""success"": true, ""tokenId"": 42, ""previousOwner"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""newOwner"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE""}","- Not verifying ownership before transfer (fails on-chain)
- Forgetting to check if NFT is locked (some have transfer restrictions)
- Using only sender post-condition (allows NFT to go elsewhere)
- Not handling read-only function failures gracefully
- Assuming all NFTs follow same interface",https://github.com/stx-city/deploy-stx-city/blob/main/src/store/TokenStore.ts,"nfts.csv:3,nfts.csv:4,security-patterns.csv:1","nft,transfer,sip009,ownership,quickstart",beginner
13,nfts,integration,list-nft-marketplace,List an NFT for sale on Gamma marketplace with price and expiration,"// Production NFT marketplace listing
// Pattern from STX City and Gamma marketplace integrations
import { request } from '@stacks/connect';
import { uintCV, principalCV, someCV, noneCV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
async function listNFTOnMarketplace(
walletAddress: string,
nftContract: string,
tokenId: number,
priceSTX: number,
expiry?: number
) {
const [nftAddress, nftName] = nftContract.split('.');
const marketplaceContract = 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-marketplace-v2';
// Price in micro-STX
const priceMicro = Math.floor(priceSTX * 1_000_000);
// Expiry block height (optional, 0 = no expiry)
const expiryBlock = expiry || 0;
// Post-condition: NFT will be locked in marketplace
const postConditions = [
Pc.principal(walletAddress)
.willSendAsset()
.nft(\`\${nftAddress}.\${nftName}\`, uintCV(tokenId))
];
const args = [
principalCV(nftContract),
uintCV(tokenId),
uintCV(priceMicro),
expiryBlock > 0 ? someCV(uintCV(expiryBlock)) : noneCV()
];
return request('stx_callContract', {
contract: marketplaceContract,
functionName: 'list-asset',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Example: List Stacks Punk #42 for 100 STX
async function listNFTExample() {
const result = await listNFTOnMarketplace(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.stacks-punks-v2',
42,
100, // 100 STX
undefined // No expiry
);
console.log('NFT listed:', result);
}",Production NFT marketplace listing pattern. Locks NFT in marketplace contract with price and optional expiry. Uses post-conditions to ensure NFT is transferred to marketplace.,"{""walletAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""nftContract"": ""SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.stacks-punks-v2"", ""tokenId"": 42, ""priceSTX"": 100, ""expiryBlock"": 0}","{""txId"": ""0xabc..."", ""success"": true, ""listingCreated"": true, ""priceSTXMicro"": 100000000, ""nftLocked"": true}","- Not checking NFT ownership before listing
- Forgetting post-condition allows NFT to go elsewhere
- Using wrong marketplace contract address
- Not setting expiry allows stale listings
- Missing marketplace approval (some require pre-approval)",https://gamma.io,"nfts.csv:6,nfts.csv:7,advanced-patterns.csv:5","gamma,marketplace,listing,nft,sales,integration",intermediate
14,nfts,integration,buy-nft-marketplace,Purchase an NFT from Gamma marketplace with payment and ownership transfer,"// Production NFT marketplace purchase with atomic swap
// Pattern from Gamma and STX City marketplace integrations
import { request } from '@stacks/connect';
import { uintCV, principalCV, cvToHex, Pc, PostConditionMode, callReadOnlyFunction, cvToJSON } from '@stacks/transactions';
async function buyNFTFromMarketplace(
buyer: string,
nftContract: string,
tokenId: number,
maxPriceSTX: number
) {
const [nftAddress, nftName] = nftContract.split('.');
const marketplaceContract = 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-marketplace-v2';
// 1. Get current listing price
const listingResult = await callReadOnlyFunction({
contractAddress: marketplaceContract.split('.')[0],
contractName: marketplaceContract.split('.')[1],
functionName: 'get-listing',
functionArgs: [
principalCV(nftContract),
uintCV(tokenId)
],
senderAddress: buyer,
network: 'mainnet'
});
const listing = cvToJSON(listingResult).value.value;
const currentPrice = listing.price.value;
const seller = listing.seller.value;
// 2. Verify price hasn't increased beyond max
if (currentPrice > maxPriceSTX * 1_000_000) {
throw new Error(\`Price increased. Current: \${currentPrice / 1e6} STX, Max: \${maxPriceSTX} STX\`);
}
// 3. Create atomic swap post-conditions
const postConditions = [
// Buyer sends exact price in STX
Pc.principal(buyer).willSendEq(BigInt(currentPrice)).ustx(),
// Seller receives payment
Pc.principal(seller).willReceiveGte(BigInt(Math.floor(currentPrice * 0.95))).ustx(), // After 5% fee
// Marketplace sends NFT to buyer
Pc.principal(marketplaceContract).willSendAsset().nft(\`\${nftAddress}.\${nftName}\`, uintCV(tokenId)),
// Buyer receives NFT
Pc.principal(buyer).willReceiveAsset().nft(\`\${nftAddress}.\${nftName}\`, uintCV(tokenId))
];
const args = [
principalCV(nftContract),
uintCV(tokenId)
];
return request('stx_callContract', {
contract: marketplaceContract,
functionName: 'purchase-asset',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Example: Buy Stacks Punk #42 (max 110 STX)
async function buyNFTExample() {
const result = await buyNFTFromMarketplace(
'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE',
'SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.stacks-punks-v2',
42,
110 // Max 110 STX (protects against price increase)
);
console.log('NFT purchased:', result);
}","Production NFT marketplace purchase with atomic swap. Reads current price, validates against max price, and uses bidirectional post-conditions for secure atomic swap of NFT and STX.","{""buyer"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"", ""nftContract"": ""SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.stacks-punks-v2"", ""tokenId"": 42, ""maxPriceSTX"": 110, ""currentPrice"": 100000000, ""buyerBalance"": 200000000}","{""txId"": ""0xdef..."", ""success"": true, ""pricePaid"": 100000000, ""sellerReceived"": 95000000, ""marketplaceFee"": 5000000, ""nftReceived"": true}","- Not checking price before tx (race condition if price increases)
- Using PostConditionMode.Allow allows funds/NFT theft
- Forgetting marketplace fee in calculations
- Not verifying listing is still active
- Missing buyer post-condition allows NFT to go elsewhere",https://gamma.io,"nfts.csv:6,nfts.csv:8,security-patterns.csv:5","gamma,marketplace,purchase,nft,trading,integration",intermediate
15,nfts,integration,nft-royalties,Implement SIP-009 NFT with automatic royalty payments to creator,"// Production NFT royalties implementation
// Pattern from NFT standards and marketplace integrations
// Clarity: NFT contract with royalty support
const NFT_ROYALTIES_CLARITY = `
;; Royalty configuration (10% = 1000 basis points)
(define-constant ROYALTY-BPS u1000)
(define-constant CREATOR-ADDRESS 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR)
(define-read-only (get-royalty-info (token-id uint) (sale-price uint))
(ok {
receiver: CREATOR-ADDRESS,
amount: (/ (* sale-price ROYALTY-BPS) u10000)
})
)
;; Marketplace sale with royalty payment
(define-public (buy-nft (token-id uint) (payment uint))
(let (
(seller (unwrap! (nft-get-owner? my-nft token-id) (err u404)))
(royalty-info (unwrap! (get-royalty-info token-id payment) (err u500)))
(royalty-amount (get amount royalty-info))
(seller-amount (- payment royalty-amount))
)
;; Pay royalty to creator
(try! (stx-transfer? royalty-amount tx-sender (get receiver royalty-info)))
;; Pay seller
(try! (stx-transfer? seller-amount tx-sender seller))
;; Transfer NFT
(try! (nft-transfer? my-nft token-id seller tx-sender))
(ok true)
)
)
`;
// JavaScript: Buy NFT with automatic royalty payment
import { request } from '@stacks/connect';
import { uintCV, cvToHex, callReadOnlyFunction, cvToJSON, Pc, PostConditionMode } from '@stacks/transactions';
async function buyNFTWithRoyalty(
buyer: string,
nftContract: string,
tokenId: number,
priceSTX: number
) {
const [contractAddress, contractName] = nftContract.split('.');
const priceMicro = Math.floor(priceSTX * 1_000_000);
// 1. Get royalty info
const royaltyResult = await callReadOnlyFunction({
contractAddress,
contractName,
functionName: 'get-royalty-info',
functionArgs: [uintCV(tokenId), uintCV(priceMicro)],
senderAddress: buyer,
network: 'mainnet'
});
const royaltyInfo = cvToJSON(royaltyResult).value.value;
const royaltyAmount = royaltyInfo.amount.value;
const creator = royaltyInfo.receiver.value;
console.log(`Royalty: ${royaltyAmount / 1e6} STX to ${creator}`);
// 2. Get current owner
const ownerResult = await callReadOnlyFunction({
contractAddress,
contractName,
functionName: 'get-owner',
functionArgs: [uintCV(tokenId)],
senderAddress: buyer,
network: 'mainnet'
});
const seller = cvToJSON(ownerResult).value.value;
const sellerAmount = priceMicro - royaltyAmount;
// 3. Create post-conditions for three-way transfer
const postConditions = [
// Buyer sends total price
Pc.principal(buyer).willSendEq(BigInt(priceMicro)).ustx(),
// Creator receives royalty
Pc.principal(creator).willReceiveEq(BigInt(royaltyAmount)).ustx(),
// Seller receives payment minus royalty
Pc.principal(seller).willReceiveEq(BigInt(sellerAmount)).ustx(),
// Buyer receives NFT
Pc.principal(buyer).willReceiveAsset().nft(`${contractAddress}.${contractName}`, uintCV(tokenId))
];
const args = [uintCV(tokenId), uintCV(priceMicro)];
return request('stx_callContract', {
contract: nftContract,
functionName: 'buy-nft',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}",Production NFT royalties with automatic creator payments. Implements EIP-2981-like royalty standard for Stacks. Three-way transfer: buyer → creator (royalty) + seller (payment).,"{""buyer"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"", ""nftContract"": ""SP2X0...my-nft"", ""tokenId"": 42, ""priceSTX"": 100, ""royaltyBps"": 1000}","{""txId"": ""0xdef..."", ""success"": true, ""totalPaid"": 100000000, ""royaltyPaid"": 10000000, ""sellerReceived"": 90000000, ""creatorReceived"": 10000000}","- Not verifying royalty recipient before payment
- Forgetting post-conditions for all three transfers
- Using wrong basis points calculation (10% = 1000 bps)
- Not capping royalty percentage (some set 100%+)
- Missing royalty info reader function",https://gamma.io,"nfts.csv:9,nfts.csv:10,clarity-syntax.csv:15","royalties,nft,creator-earnings,sip009,revenue",intermediate
16,nfts,best-practice,batch-mint-nfts,Efficiently batch mint multiple NFTs in a single transaction to save on fees,"// Production batch NFT minting for airdrops
// Pattern from NFT collection launches and airdrop campaigns
import { request } from '@stacks/connect';
import { uintCV, principalCV, listCV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
// Clarity: Batch mint function
const BATCH_MINT_CLARITY = `
(define-public (batch-mint (recipients (list 50 principal)))
(begin
(asserts! (is-eq tx-sender contract-owner) ERR-NOT-AUTHORIZED)
(ok (map mint-to-recipient recipients))
)
)
(define-private (mint-to-recipient (recipient principal))
(let (
(next-id (+ (var-get last-token-id) u1))
)
(try! (nft-mint? my-nft next-id recipient))
(var-set last-token-id next-id)
next-id
)
)
`;
// JavaScript: Batch mint with chunking for large lists
async function batchMintNFTs(
minter: string,
nftContract: string,
recipients: string[],
chunkSize: number = 50
) {
const results = [];
// Split into chunks (Clarity has list size limits)
for (let i = 0; i < recipients.length; i += chunkSize) {
const chunk = recipients.slice(i, i + chunkSize);
console.log(`Minting batch ${Math.floor(i / chunkSize) + 1}/${Math.ceil(recipients.length / chunkSize)}`);
console.log(`Recipients: ${chunk.length}`);
// Create list of principals
const recipientCVs = chunk.map(addr => principalCV(addr));
const args = [listCV(recipientCVs)];
const result = await request('stx_callContract', {
contract: nftContract,
functionName: 'batch-mint',
functionArgs: args.map(cvToHex),
postConditionMode: 'allow', // Complex post-conditions
network: 'mainnet'
});
results.push(result);
// Rate limiting: wait 1 second between batches
await new Promise(resolve => setTimeout(resolve, 1000));
}
return results;
}
// Example: Airdrop to 200 wallets
async function airdropExample() {
const recipients = [
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE',
// ... 198 more addresses
];
const results = await batchMintNFTs(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.my-nft-collection',
recipients,
50 // 50 per batch = 4 transactions total
);
console.log(`Airdropped ${recipients.length} NFTs in ${results.length} batches`);
}",Production batch NFT minting for airdrops. Chunks large recipient lists to fit Clarity's list size limits (50-100). Includes rate limiting between batches.,"{""minter"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""nftContract"": ""SP2X0...my-collection"", ""recipientCount"": 200, ""chunkSize"": 50}","{""totalMinted"": 200, ""batchCount"": 4, ""successfulBatches"": 4, ""failedMints"": 0, ""durationSeconds"": 8}","- Exceeding Clarity list size limit (crashes transaction)
- Not rate limiting causes mempool congestion
- Forgetting to track last-token-id between batches
- Using sequential IDs allows sniping rare tokens
- Not handling failed batches (no retry logic)",https://stx.city,"nfts.csv:1,nfts.csv:2,advanced-patterns.csv:10","batch,mint,gas-optimization,nft,airdrop,best-practice",intermediate
17,nfts,quickstart,update-nft-metadata,Update NFT metadata URI after minting for dynamic NFTs,"// Production dynamic NFT metadata updates
// Pattern from gaming NFTs and evolving collections
// Clarity: Dynamic metadata with update function
const DYNAMIC_NFT_CLARITY = `
(define-map token-metadata uint (string-utf8 256))
(define-map token-attributes uint {
level: uint,
power: uint,
rarity: (string-ascii 20)
})
(define-public (update-metadata (token-id uint) (new-uri (string-utf8 256)))
(begin
(asserts! (is-eq tx-sender (unwrap! (nft-get-owner? my-nft token-id) (err u404))) ERR-NOT-OWNER)
(map-set token-metadata token-id new-uri)
(ok true)
)
)
(define-public (level-up (token-id uint))
(let (
(owner (unwrap! (nft-get-owner? my-nft token-id) (err u404)))
(attrs (default-to {level: u1, power: u10, rarity: ""common""}
(map-get? token-attributes token-id)))
)
(asserts! (is-eq tx-sender owner) ERR-NOT-OWNER)
(map-set token-attributes token-id
(merge attrs {
level: (+ (get level attrs) u1),
power: (+ (get power attrs) u5)
})
)
(ok true)
)
)
`;
// JavaScript: Update metadata with new IPFS hash
import { request } from '@stacks/connect';
import { uintCV, stringUtf8CV, cvToHex } from '@stacks/transactions';
async function updateNFTMetadata(
owner: string,
nftContract: string,
tokenId: number,
newIpfsHash: string
) {
const newUri = `ipfs://${newIpfsHash}`;
const args = [
uintCV(tokenId),
stringUtf8CV(newUri)
];
return request('stx_callContract', {
contract: nftContract,
functionName: 'update-metadata',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
network: 'mainnet'
});
}
// Example: Update NFT after evolution/upgrade
async function evolveNFT() {
// 1. Upload new metadata to IPFS
const newMetadata = {
name: ""My NFT #42"",
image: ""ipfs://QmNewImage.../42.png"",
attributes: [
{ trait_type: ""Level"", value: 2 },
{ trait_type: ""Power"", value: 15 }
]
};
// Upload to IPFS (using pinata, web3.storage, etc.)
// const ipfsHash = await uploadToIPFS(newMetadata);
const ipfsHash = 'QmNewHash123.../42.json';
// 2. Update on-chain metadata pointer
const result = await updateNFTMetadata(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.gaming-nft-v1',
42,
ipfsHash
);
console.log('Metadata updated:', result);
}",Production dynamic NFT metadata updates. Allows owners to evolve NFTs by updating IPFS metadata pointers. Common for gaming NFTs and progressive collections.,"{""owner"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""nftContract"": ""SP2X0...gaming-nft"", ""tokenId"": 42, ""newIpfsHash"": ""QmNewHash.../42.json"", ""currentLevel"": 1}","{""txId"": ""0xabc..."", ""success"": true, ""newUri"": ""ipfs://QmNewHash.../42.json"", ""metadataUpdated"": true, ""newLevel"": 2}","- Not restricting who can update (owner-only check missing)
- Allowing unlimited updates causes metadata spam
- Forgetting to emit update event (marketplaces miss changes)
- Not validating IPFS hash format
- Using centralized storage instead of IPFS (not permanent)",https://docs.stacks.co,"nfts.csv:11,nfts.csv:12,clarity-syntax.csv:25","metadata,dynamic-nft,ipfs,updates,quickstart",intermediate
18,nfts,integration,nft-collection-launch,"Launch a complete NFT collection with mint, metadata, and marketplace integration","// Production NFT collection launch workflow
// From successful Stacks NFT drops
import { request } from '@stacks/connect';
// Complete launch checklist and deployment
const NFT_LAUNCH_WORKFLOW = `
# NFT Collection Launch Workflow
## Pre-Launch (1-2 weeks)
1. ✓ Deploy contract to testnet
2. ✓ Test minting, transfers, marketplace compatibility
3. ✓ Upload metadata to IPFS/Arweave (pinned)
4. ✓ Set up website with mint UI
5. ✓ Configure allowlist (Merkle tree)
6. ✓ Test with multiple wallets
## Launch Day
1. ✓ Deploy to mainnet (verify contract)
2. ✓ Set mint price and limits
3. ✓ Enable allowlist minting (6 hours)
4. ✓ Enable public minting
5. ✓ Monitor for errors/exploits
## Post-Launch
1. ✓ List on Gamma marketplace
2. ✓ Reveal metadata (if unrevealed mint)
3. ✓ Set up royalties
4. ✓ Announce secondary trading
`;
// Clarity: NFT contract with launch controls
const NFT_LAUNCH_CLARITY = `
(define-constant contract-owner tx-sender)
(define-constant mint-price u50000000) ;; 50 STX
(define-constant max-supply u10000)
(define-data-var mint-enabled bool false)
(define-data-var allowlist-enabled bool true)
(define-data-var last-token-id uint u0)
;; Allowlist (Merkle root or simple map)
(define-map allowlist principal bool)
(define-public (enable-public-mint)
(begin
(asserts! (is-eq tx-sender contract-owner) ERR-NOT-AUTHORIZED)
(var-set mint-enabled true)
(var-set allowlist-enabled false)
(ok true)
)
)
(define-public (mint)
(let (
(next-id (+ (var-get last-token-id) u1))
)
(asserts! (var-get mint-enabled) (err u100))
(asserts! (<= next-id max-supply) (err u101))
;; Check allowlist if enabled
(if (var-get allowlist-enabled)
(asserts! (default-to false (map-get? allowlist tx-sender)) (err u102))
true
)
;; Payment
(try! (stx-transfer? mint-price tx-sender contract-owner))
;; Mint NFT
(try! (nft-mint? my-nft next-id tx-sender))
(var-set last-token-id next-id)
(ok next-id)
)
)
`;
// JavaScript: Launch sequence
async function launchNFTCollection() {
// Step 1: Deploy contract
console.log('1. Deploying contract...');
const deployResult = await request('stx_deployContract', {
contractName: 'my-nft-collection-v1',
codeBody: NFT_LAUNCH_CLARITY,
network: 'mainnet'
});
console.log('Contract deployed:', deployResult);
// Step 2: Add allowlist members
console.log('2. Setting up allowlist...');
// ... add allowlist logic ...
// Step 3: Enable allowlist minting
console.log('3. Enabling allowlist mint...');
await request('stx_callContract', {
contract: 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.my-nft-collection-v1',
functionName: 'enable-allowlist-mint',
functionArgs: [],
postConditionMode: 'deny',
network: 'mainnet'
});
// Step 4: After 6 hours, enable public mint
console.log('4. Waiting for allowlist period...');
setTimeout(async () => {
console.log('5. Enabling public mint...');
await request('stx_callContract', {
contract: 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.my-nft-collection-v1',
functionName: 'enable-public-mint',
functionArgs: [],
postConditionMode: 'deny',
network: 'mainnet'
});
}, 6 * 60 * 60 * 1000); // 6 hours
}",Production NFT collection launch workflow. Complete checklist from testnet deployment to public mint. Includes allowlist period and mint controls.,"{""contractName"": ""my-nft-collection-v1"", ""maxSupply"": 10000, ""mintPrice"": 50000000, ""allowlistPeriod"": 21600, ""allowlistSize"": 500}","{""contractDeployed"": true, ""allowlistMintEnabled"": true, ""publicMintEnabled"": false, ""totalMinted"": 500, ""phase"": ""allowlist""}","- Not testing on testnet first
- Missing mint controls (anyone can mint)
- No supply cap enforcement
- Metadata not pinned (IPFS unpinned)
- No marketplace compatibility testing",https://gamma.io,"nfts.csv:1,nfts.csv:6,nfts.csv:9,advanced-patterns.csv:15","collection,launch,mint,marketplace,integration,advanced",advanced
19,nfts,debugging,debug-nft-transfer-failure,Debug and fix common NFT transfer failures and ownership issues,"// Debug NFT transfer failure
import { callReadOnlyFunction, cvToJSON, uintCV } from '@stacks/transactions';
async function debugNFTTransfer(nftContract: string, tokenId: number, sender: string) {
const [addr, name] = nftContract.split('.');
// Check ownership
const owner = await callReadOnlyFunction({
contractAddress: addr, contractName: name,
functionName: 'get-owner',
functionArgs: [uintCV(tokenId)],
senderAddress: sender, network: 'mainnet'
});
const currentOwner = cvToJSON(owner).value.value;
if (currentOwner !== sender) {
return {error: 'not_owner', fix: 'You do not own this NFT'};
}
// Check if locked
try {
const locked = await callReadOnlyFunction({
contractAddress: addr, contractName: name,
functionName: 'is-locked',
functionArgs: [uintCV(tokenId)],
senderAddress: sender, network: 'mainnet'
});
if (cvToJSON(locked).value) {
return {error: 'nft_locked', fix: 'NFT is locked in marketplace/staking'};
}
} catch (e) {}
return {error: 'unknown', fix: 'Check post-conditions and try again'};
}","Production NFT transfer debugging. Checks ownership, lock status, and marketplace listings to diagnose why transfer failed.","{""tokenId"": 42, ""senderAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""recipientAddress"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE""}","{""debugSteps"": [""ownership-verified"", ""not-listed"", ""not-staked"", ""transfer-successful""], ""txId"": ""0xddd..."", ""success"": true}","- Not checking token ownership before transfer
- Forgetting to cancel marketplace listings first
- Attempting to transfer staked/locked NFTs
- Using wrong token ID (off-by-one errors)
- Wrong contract address for NFT collection
- Not handling contract error codes properly",https://explorer.hiro.so,"nfts.csv:3,nfts.csv:4,security-patterns.csv:1","debugging,nft,transfer,ownership,troubleshooting,intermediate",intermediate
20,nfts,security,secure-nft-marketplace,"Build a secure NFT marketplace with escrow, post-conditions, and anti-rug measures","// Secure NFT marketplace with escrow
const SECURE_MARKETPLACE_CLARITY = `
(define-map listings uint {seller: principal, price: uint, expiry: uint})
(define-map escrowed-nfts uint bool)
(define-public (list-nft (token-id uint) (price uint) (expiry uint))
(begin
(try! (nft-transfer? my-nft token-id tx-sender (as-contract tx-sender)))
(map-set listings token-id {seller: tx-sender, price: price, expiry: expiry})
(map-set escrowed-nfts token-id true)
(ok true)
)
)
(define-public (buy-nft (token-id uint))
(let (
(listing (unwrap! (map-get? listings token-id) (err u404)))
(seller (get seller listing))
(price (get price listing))
)
(asserts! (< block-height (get expiry listing)) (err u410))
(try! (stx-transfer? price tx-sender seller))
(try! (as-contract (nft-transfer? my-nft token-id tx-sender buyer)))
(map-delete listings token-id)
(map-delete escrowed-nfts token-id)
(ok true)
)
)
`;","Production secure NFT marketplace with escrow. NFT is locked in contract during listing, preventing double-spend and rug pulls.","{""listingId"": 42, ""priceInMicroSTX"": 10000000, ""buyerAddress"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"", ""sellerAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR""}","{""txId"": ""0xeee..."", ""securityChecks"": [""escrow"", ""post-conditions"", ""deny-mode"", ""expiration"", ""atomic-swap""], ""safe"": true}","- NEVER skip post-conditions on marketplace txs
- NEVER use Allow mode (always use Deny mode)
- NEVER trust external contract state without validation
- NEVER allow partial transfers (atomic only)
- Always use escrow pattern for listings
- Always validate listing expiration
- Always check NFT ownership before transfer",https://github.com/gamma-io/gamma-contracts,"nfts.csv:6,nfts.csv:8,security-patterns.csv:1,security-patterns.csv:5","security,marketplace,escrow,post-conditions,anti-rug,advanced",advanced
21,tokens,quickstart,deploy-sip010-token,Deploy a basic SIP-010 compliant fungible token contract,"// Production SIP-010 token deployment
// Pattern from DeFi protocols and token standards
import { request } from '@stacks/connect';
import { AnchorMode } from '@stacks/transactions';
// Complete SIP-010 token contract in Clarity
const SIP010_CONTRACT = \`
;; SIP-010 Fungible Token Standard
(impl-trait 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard.sip-010-trait)
;; Token definition
(define-fungible-token my-token u1000000000000)
;; Constants
(define-constant contract-owner tx-sender)
(define-constant err-owner-only (err u100))
(define-constant err-not-token-owner (err u101))
;; SIP-010 Functions
(define-public (transfer (amount uint) (sender principal) (recipient principal) (memo (optional (buff 34))))
(begin
(asserts! (is-eq tx-sender sender) err-not-token-owner)
(try! (ft-transfer? my-token amount sender recipient))
(match memo to-print (print to-print) 0x)
(ok true)
)
)
(define-read-only (get-name)
(ok ""My Token"")
)
(define-read-only (get-symbol)
(ok ""MYT"")
)
(define-read-only (get-decimals)
(ok u6)
)
(define-read-only (get-balance (who principal))
(ok (ft-get-balance my-token who))
)
(define-read-only (get-total-supply)
(ok (ft-get-supply my-token))
)
(define-read-only (get-token-uri)
(ok (some u""https://example.com/token-metadata.json""))
)
;; Mint function (owner only)
(define-public (mint (amount uint) (recipient principal))
(begin
(asserts! (is-eq tx-sender contract-owner) err-owner-only)
(ft-mint? my-token amount recipient)
)
)
\`;
async function deploySIP010Token() {
// Deploy contract using Stacks Connect
const { request } = await import('@stacks/connect');
return request('stx_deployContract', {
contractName: 'my-token-v1',
codeBody: SIP010_CONTRACT,
network: 'mainnet',
anchorMode: AnchorMode.Any,
postConditionMode: 'deny',
postConditions: []
});
}
// After deployment, mint initial supply
async function mintInitialSupply(
tokenContract: string,
amount: number,
recipient: string
) {
const { request } = await import('@stacks/connect');
const { uintCV, principalCV, cvToHex } = await import('@stacks/transactions');
return request('stx_callContract', {
contract: tokenContract,
functionName: 'mint',
functionArgs: [
uintCV(amount),
principalCV(recipient)
].map(cvToHex),
postConditionMode: 'deny',
network: 'mainnet'
});
}","Production SIP-010 token deployment with complete trait implementation. Includes all required functions (transfer, get-balance, get-total-supply) and optional mint function.","{""contractName"": ""my-token-v1"", ""totalSupply"": 1000000000000, ""decimals"": 6, ""tokenName"": ""My Token"", ""tokenSymbol"": ""MYT""}","{""txId"": ""0x123..."", ""success"": true, ""contractId"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.my-token-v1"", ""deployed"": true, ""traitCompliant"": true}","- Not implementing all SIP-010 required functions
- Using wrong trait principal (must match network)
- Forgetting to define fungible token with total supply
- Not adding mint function for owner (can't distribute tokens)
- Missing error constants (poor UX)",https://docs.stacks.co/clarity/example-contracts/sip-010-fungible-token,"fungible-tokens.csv:1,fungible-tokens.csv:8,clarity-syntax.csv:15","sip010,deploy,token,fungible,standard,quickstart",beginner
22,tokens,quickstart,token-transfer-with-postconditions,Transfer tokens securely with post-conditions to prevent unauthorized transfers,"// Production token transfer with security post-conditions
// From stacksagent-backend trade controller patterns
import { request } from '@stacks/connect';
import { uintCV, principalCV, someCV, noneCV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
async function transferTokenWithPostConditions(
sender: string,
recipient: string,
tokenContract: string,
amount: number,
memo?: string
) {
const [tokenAddress, tokenName] = tokenContract.split('.');
// Create strict post-conditions
const postConditions = [
// Sender MUST send exact amount (prevents overspend)
Pc.principal(sender)
.willSendEq(BigInt(amount))
.ft(tokenContract, tokenName),
// Recipient MUST receive exact amount (prevents theft)
Pc.principal(recipient)
.willReceiveEq(BigInt(amount))
.ft(tokenContract, tokenName)
];
// Build arguments (SIP-010 transfer signature)
const args = [
uintCV(amount),
principalCV(sender),
principalCV(recipient),
memo ? someCV(stringUtf8CV(memo)) : noneCV()
];
return request('stx_callContract', {
contract: tokenContract,
functionName: 'transfer',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny', // CRITICAL: Always use deny mode
postConditions,
network: 'mainnet'
});
}
// Example: Safe token transfer
async function safeTransferExample() {
const result = await transferTokenWithPostConditions(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE',
'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token',
1_000_000,
'Payment for services'
);
console.log('Transfer completed:', result);
}",Production token transfer from stacksagent-backend with strict post-conditions. Uses willSendEq and willReceiveEq to prevent any unauthorized token movements.,"{""sender"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""recipient"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"", ""tokenContract"": ""SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token"", ""amount"": 1000000, ""senderBalance"": 5000000}","{""txId"": ""0xabc..."", ""success"": true, ""amountTransferred"": 1000000, ""postConditionsVerified"": true, ""senderNewBalance"": 4000000, ""recipientNewBalance"": 1000000}","- Using PostConditionMode.Allow without post-conditions (critical security flaw)
- Using willSendLte instead of willSendEq (allows contract to take more)
- Forgetting memo parameter format (optional (buff 34))
- Not validating sender has sufficient balance
- Using wrong token contract address",https://github.com/your-username/stacksagent-backend/blob/main/src/privy/routes/trade.controller.ts#L45,"fungible-tokens.csv:8,fungible-tokens.csv:23,security-patterns.csv:3","transfer,post-conditions,security,sip010,quickstart",beginner
23,tokens,integration,token-allowance-pattern,Implement ERC-20 style allowance pattern for DEX integrations and delegated transfers,"// Production token allowance for DEX integration
// Pattern from DeFi protocols (Alex, Velar, Bitflow)
import { request } from '@stacks/connect';
import { uintCV, principalCV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
// Step 1: Grant allowance to spender (e.g., DEX contract)
async function approveTokenAllowance(
owner: string,
spender: string,
tokenContract: string,
amount: number
) {
const [tokenAddress, tokenName] = tokenContract.split('.');
// Post-condition: No tokens should move during approval
const postConditions = [
Pc.principal(owner).willSendEq(BigInt(0)).ft(tokenContract, tokenName)
];
const args = [
principalCV(spender),
uintCV(amount)
];
return request('stx_callContract', {
contract: tokenContract,
functionName: 'approve',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Step 2: Spender uses allowance (DEX swaps tokens)
async function transferFromAllowance(
spender: string,
from: string,
to: string,
tokenContract: string,
amount: number
) {
const [tokenAddress, tokenName] = tokenContract.split('.');
// Post-conditions: Exact amount transferred
const postConditions = [
Pc.principal(from).willSendEq(BigInt(amount)).ft(tokenContract, tokenName),
Pc.principal(to).willReceiveEq(BigInt(amount)).ft(tokenContract, tokenName)
];
const args = [
principalCV(from),
principalCV(to),
uintCV(amount)
];
return request('stx_callContract', {
contract: tokenContract,
functionName: 'transfer-from',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Example: Approve DEX to spend 1000 tokens
async function approveForSwap() {
const owner = 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR';
const dexContract = 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1';
const tokenContract = 'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token';
// Approve DEX to spend 1000 tokens
const result = await approveTokenAllowance(
owner,
dexContract,
tokenContract,
1000_000_000
);
console.log('Allowance granted:', result);
}","Production token allowance pattern from DEX integrations. Two-step process: approve spender, then spender uses transfer-from. Critical for DEX swaps and automated protocols.","{""owner"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""spender"": ""SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.amm-swap-pool-v1-1"", ""tokenContract"": ""SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.age000-governance-token"", ""amount"": 1000000000, ""ownerBalance"": 5000000000}","{""approvalTxId"": ""0x123..."", ""allowanceSet"": 1000000000, ""spenderAuthorized"": true, ""tokensNotMoved"": true}","- Approving unlimited amount (security risk)
- Not revoking old allowances before setting new ones
- Using approve without checking current allowance first
- Forgetting spender must call transfer-from, not transfer
- Not handling allowance expiry in some token implementations",https://app.alexlab.co,"fungible-tokens.csv:11,fungible-tokens.csv:13,defi-protocols.csv:1,security-patterns.csv:1","allowance,approve,transfer-from,dex,integration",intermediate
24,tokens,integration,token-vesting-schedule,Create time-locked token vesting schedules for team allocations and investor unlocks,"// Production token vesting with time-locked releases
// Pattern from token launches and team allocations
import { request } from '@stacks/connect';
import { uintCV, principalCV, cvToHex, callReadOnlyFunction, cvToJSON } from '@stacks/transactions';
// Clarity contract for vesting (simplified)
const VESTING_CONTRACT = \`
(define-map vesting-schedules
{ recipient: principal }
{
total-amount: uint,
released-amount: uint,
start-block: uint,
cliff-blocks: uint,
vesting-blocks: uint
}
)
(define-read-only (get-vested-amount (recipient principal) (current-block uint))
(let (
(schedule (unwrap! (map-get? vesting-schedules { recipient: recipient }) (err u404)))
)
(if (< current-block (+ (get start-block schedule) (get cliff-blocks schedule)))
;; Before cliff, nothing vested
(ok u0)
;; After cliff, linear vesting
(let (
(elapsed (- current-block (get start-block schedule)))
(vested (/ (* (get total-amount schedule) elapsed) (get vesting-blocks schedule)))
)
(ok (min vested (get total-amount schedule)))
)
)
)
)
(define-public (claim-vested-tokens)
(let (
(schedule (unwrap! (map-get? vesting-schedules { recipient: tx-sender }) (err u404)))
(vested (unwrap! (get-vested-amount tx-sender block-height) (err u500)))
(claimable (- vested (get released-amount schedule)))
)
(asserts! (> claimable u0) (err u400))
;; Update released amount
(map-set vesting-schedules
{ recipient: tx-sender }
(merge schedule { released-amount: vested })
)
;; Transfer tokens
(ft-transfer? my-token claimable (as-contract tx-sender) tx-sender)
)
)
\`;
// JavaScript: Claim vested tokens
async function claimVestedTokens(
recipient: string,
vestingContract: string
) {
// 1. Check how much is vested
const vestedResult = await callReadOnlyFunction({
contractAddress: vestingContract.split('.')[0],
contractName: vestingContract.split('.')[1],
functionName: 'get-vested-amount',
functionArgs: [
principalCV(recipient),
uintCV(150000) // Current block height
],
senderAddress: recipient,
network: 'mainnet'
});
const vestedAmount = cvToJSON(vestedResult).value.value;
console.log(\`Vested amount: \${vestedAmount / 1e6} tokens\`);
// 2. Claim vested tokens
return request('stx_callContract', {
contract: vestingContract,
functionName: 'claim-vested-tokens',
functionArgs: [],
postConditionMode: 'allow', // Contract handles transfer
network: 'mainnet'
});
}
// Example: Team member claims after 6 months
async function claimTeamTokens() {
const result = await claimVestedTokens(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.token-vesting-v1'
);
console.log('Tokens claimed:', result);
}",Production token vesting with time-locked releases. Implements cliff period and linear vesting schedule. Common for team allocations and investor lockups.,"{""recipient"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""totalAmount"": 1000000000000, ""cliffBlocks"": 4320, ""vestingBlocks"": 52560, ""currentBlock"": 150000, ""startBlock"": 100000}","{""txId"": ""0xabc..."", ""vestedAmount"": 950000000000, ""claimedAmount"": 950000000000, ""remainingVesting"": 50000000000}","- Not implementing cliff period (immediate vesting)
- Using block-height instead of burn-block-height (vulnerable to reorgs)
- Forgetting to track released amount (double claims)
- Not handling edge cases at vesting completion
- Missing emergency revocation function for team departures",https://docs.stacks.co,"fungible-tokens.csv:17,fungible-tokens.csv:19,advanced-patterns.csv:20","vesting,time-lock,team-tokens,cliff,linear,integration",advanced
25,tokens,best-practice,token-burn-supply-management,Implement token burning and supply management for deflationary tokenomics,"// Production token burn for deflationary mechanics
// Pattern from meme tokens and supply management
import { request } from '@stacks/connect';
import { uintCV, principalCV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
async function burnTokens(
burner: string,
tokenContract: string,
amount: number
) {
const [tokenAddress, tokenName] = tokenContract.split('.');
// Post-condition: Tokens will be burned (sent to null address or destroyed)
const postConditions = [
Pc.principal(burner).willSendEq(BigInt(amount)).ft(tokenContract, tokenName)
];
const args = [
uintCV(amount),
principalCV(burner)
];
return request('stx_callContract', {
contract: tokenContract,
functionName: 'burn',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}
// Clarity burn implementation (in token contract)
const BURN_CLARITY = \`
(define-public (burn (amount uint) (sender principal))
(begin
(asserts! (is-eq tx-sender sender) ERR-NOT-AUTHORIZED)
(ft-burn? my-token amount sender)
)
)
\`;
// Example: Burn 1M tokens to reduce supply
async function burnSupplyExample() {
const result = await burnTokens(
'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR',
'SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.deflationary-token',
1_000_000_000_000 // 1M tokens
);
console.log('Tokens burned:', result);
}",Production token burn for deflationary mechanics. Permanently reduces token supply using ft-burn? Clarity function. Common in meme tokens and buyback-and-burn models.,"{""burner"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""tokenContract"": ""SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.deflationary-token"", ""amount"": 1000000000000, ""burnerBalance"": 5000000000000, ""totalSupply"": 100000000000000}","{""txId"": ""0xdef..."", ""success"": true, ""amountBurned"": 1000000000000, ""newTotalSupply"": 99000000000000, ""burnerNewBalance"": 4000000000000}","- Not checking burner has sufficient balance
- Missing authorization check (anyone can burn?)
- Not emitting burn event for analytics
- Using transfer to null address instead of ft-burn? (doesn't reduce supply)
- Forgetting to update circulating supply metrics",https://stx.city,"fungible-tokens.csv:10,fungible-tokens.csv:3,clarity-syntax.csv:15","burn,deflationary,supply-management,tokenomics,best-practice",intermediate
26,tokens,integration,multi-token-atomic-swap,Execute atomic swaps between multiple tokens in a single transaction,"// Multi-token atomic swap
import { request } from '@stacks/connect';
import { listCV, tupleCV, principalCV, uintCV, cvToHex, Pc } from '@stacks/transactions';
async function multiTokenSwap(
user: string,
offers: Array<{token: string, amount: number}>,
requests: Array<{token: string, amount: number}>
) {
const postConditions = [
...offers.map(o =>
Pc.principal(user).willSendEq(BigInt(o.amount)).ft(o.token, o.token.split('.')[1])
),
...requests.map(r =>
Pc.principal(user).willReceiveGte(BigInt(r.amount)).ft(r.token, r.token.split('.')[1])
)
];
return request('stx_callContract', {
contract: 'SP...swap-contract',
functionName: 'multi-token-swap',
functionArgs: [
listCV(offers.map(o => tupleCV({token: principalCV(o.token), amount: uintCV(o.amount)}))),
listCV(requests.map(r => tupleCV({token: principalCV(r.token), amount: uintCV(r.amount)})))
].map(cvToHex),
postConditionMode: 'deny',
postConditions,
network: 'mainnet'
});
}",Production multi-token atomic swap. Swaps multiple tokens in single transaction with strict post-conditions on all assets.,"{""amountIn"": 10000000, ""minAmountOut"": 50000000, ""tokenA"": ""arkadiko-token"", ""tokenB"": ""age000-governance-token"", ""multiHopRoute"": [""DIKO"", ""ALEX"", ""USDA""]}","{""swapTxId"": ""0xabc..."", ""amountIn"": 10000000, ""amountOut"": 52000000, ""multiHopTxId"": ""0xdef..."", ""route"": ""DIKO->ALEX->USDA"", ""batchTxId"": ""0xghi..."", ""tokensReceived"": 3}","- Not using atomic transactions allows partial failures
- Missing minimum output validation causes slippage losses
- No post-conditions enables unauthorized token transfers
- Multi-hop without intermediate validation loses funds
- Batch swaps without size limits cause out-of-gas errors
- Not checking pool liquidity before large swaps
- Forgetting to approve token contracts for transfers",https://app.alexlab.co/swap,"fungible-tokens.csv:8,fungible-tokens.csv:23,defi-protocols.csv:1,advanced-patterns.csv:1","atomic-swap,multi-token,dex,batch,integration",intermediate
27,tokens,debugging,debug-token-transfer-failure,"Debug and fix common token transfer failures including insufficient balance, wrong addresses, and contract errors","// Debug token transfer failure
async function debugTokenTransfer(txId: string) {
const tx = await fetch(`https://api.hiro.so/extended/v1/tx/${txId}`).then(r => r.json());
if (tx.tx_status === 'abort_by_post_condition') {
return {error: 'insufficient_balance', fix: 'Check token balance'};
}
if (tx.tx_result?.repr?.includes('err u1')) {
return {error: 'not_authorized', fix: 'You do not own these tokens'};
}
if (tx.tx_result?.repr?.includes('err u3')) {
return {error: 'insufficient_allowance', fix: 'Increase token allowance'};
}
return {error: 'unknown', fix: 'Check transaction on explorer'};
}",Production token transfer debugging. Parses common SIP-010 error codes and provides actionable fixes.,"{""senderAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""recipientAddress"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"", ""amount"": 5000000, ""tokenContract"": ""arkadiko-token""}","{""diagnosticSteps"": 7, ""contractExists"": true, ""senderBalance"": 10000000, ""sufficientBalance"": true, ""validRecipient"": true, ""transfersNotPaused"": true, ""validAmount"": true, ""txId"": ""0xabc..."", ""success"": true}","- Not checking contract exists before transfer
- Skipping balance validation causes failed transactions
- Using self as recipient creates logic errors
- Missing post-conditions allows unauthorized transfers
- Not handling paused state causes confusion
- Ignoring contract error codes makes debugging hard
- Wrong token asset name in post-conditions fails silently",https://explorer.hiro.so,"fungible-tokens.csv:2,fungible-tokens.csv:8,security-patterns.csv:3","debugging,transfer,errors,validation,troubleshooting",intermediate
28,tokens,security,secure-token-launch,"Launch a secure token with anti-rug, anti-bot protections, and fair distribution","// Secure token launch with anti-bot measures
const SECURE_LAUNCH_CLARITY = `
(define-constant max-mint-per-tx u1000000000) ;; 1000 tokens
(define-map mint-cooldown principal uint)
(define-constant cooldown-blocks u10)
(define-public (mint (amount uint))
(let ((last-mint (default-to u0 (map-get? mint-cooldown tx-sender))))
(asserts! (<= amount max-mint-per-tx) (err u100))
(asserts! (>= block-height (+ last-mint cooldown-blocks)) (err u101))
(try! (ft-mint? my-token amount tx-sender))
(map-set mint-cooldown tx-sender block-height)
(ok true)
)
)
`;",Production token launch with anti-bot protection. Rate limits minting per wallet and enforces cooldown periods.,"{""saleAllocation"": 400000000000, ""liquidityAllocation"": 300000000000, ""teamAllocation"": 200000000000, ""maxBuyPerAddress"": 10000000000, ""tokenPrice"": 100, ""saleDuration"": 4380, ""liquidityLockDuration"": 52560}","{""deployTxId"": ""0xabc..."", ""saleStartTxId"": ""0xdef..."", ""liquidityLockTxId"": ""0xghi..."", ""ownershipRenouncedTxId"": ""0xjkl..."", ""liquidityUnlockBlock"": 105120, ""securityFeatures"": [""anti-rug"", ""anti-bot"", ""fair-launch"", ""time-locked-liquidity""]}","- NEVER allow owner to withdraw liquidity (rug risk)
- NEVER skip liquidity lock (minimum 6-12 months)
- NEVER allow unlimited purchases (whale manipulation)
- NEVER launch without purchase cooldowns (bot protection)
- ALWAYS audit contract before mainnet
- ALWAYS test on testnet with realistic scenarios
- ALWAYS communicate security measures to community",https://github.com/citycoins/citycoin/blob/main/contracts/core/citycoin-core-v2.clar,"fungible-tokens.csv:9,fungible-tokens.csv:14,security-patterns.csv:1,security-patterns.csv:9,advanced-patterns.csv:15","security,launch,anti-rug,anti-bot,fair-launch,liquidity-lock,advanced",advanced
29,security,security,reentrancy-attack-prevention,Prevent reentrancy attacks using checks-effects-interactions pattern to avoid exploitation similar to the famous DAO hack,"// Production reentrancy prevention pattern
// From security best practices and DeFi protocols
// Clarity: Reentrancy guard using state flags
const REENTRANCY_GUARD_CLARITY = \`
;; State flag to prevent reentrancy
(define-data-var locked bool false)
(define-private (check-and-lock)
(begin
(asserts! (not (var-get locked)) (err u403))
(var-set locked true)
(ok true)
)
)
(define-private (unlock)
(var-set locked false)
)
;; Protected function using guard
(define-public (withdraw (amount uint))
(begin
;; Check and set lock
(try! (check-and-lock))
;; Perform external call (risky operation)
(try! (as-contract (stx-transfer? amount tx-sender (var-get msg-sender))))
;; Always unlock before exit
(unlock)
(ok true)
)
)
;; VULNERABLE PATTERN (DO NOT USE)
(define-public (vulnerable-withdraw (amount uint))
(begin
;; External call before state update (DANGEROUS!)
(try! (as-contract (stx-transfer? amount tx-sender (var-get msg-sender))))
;; Update state after external call
;; Attacker can re-enter here!
(map-set balances { user: tx-sender } (- balance amount))
(ok true)
)
)
\`;
// JavaScript: Safe withdraw pattern
import { request } from '@stacks/connect';
import { uintCV, cvToHex, Pc, PostConditionMode } from '@stacks/transactions';
async function safeWithdraw(
user: string,
protocolContract: string,
amount: number
) {
// Post-conditions prevent reentrancy attacks
const postConditions = [
// Protocol can only send exact amount
Pc.principal(protocolContract).willSendEq(BigInt(amount)).ustx(),
// User must receive exact amount
Pc.principal(user).willReceiveEq(BigInt(amount)).ustx()
];
return request('stx_callContract', {
contract: protocolContract,
functionName: 'withdraw',
functionArgs: [uintCV(amount)].map(cvToHex),
postConditionMode: 'deny', // CRITICAL: Must use deny mode
postConditions,
network: 'mainnet'
});
}",Production reentrancy prevention using state lock pattern. Critical security pattern for DeFi. Uses locked flag to prevent re-entrant calls during external interactions.,"{""user"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""protocolContract"": ""SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.defi-protocol-v1"", ""withdrawAmount"": 10000000, ""userBalance"": 50000000, ""isLocked"": false}","{""txId"": ""0x123..."", ""success"": true, ""amountWithdrawn"": 10000000, ""reentrancyPrevented"": true, ""lockReleased"": true}","- Not implementing reentrancy guard for external calls
- Forgetting to unlock after success (permanent lock)
- Not using checks-effects-interactions pattern
- Missing post-conditions allows theft during reentrancy
- Using block-height as reentrancy check (insufficient)",https://docs.stacks.co/clarity/security,"security-patterns.csv:1,security-patterns.csv:4,clarity-syntax.csv:25,stacks-js-core.csv:12","security,reentrancy,dao-hack,checks-effects-interactions,state-management,vulnerability,advanced",advanced
30,security,security,integer-overflow-protection,Prevent integer overflow and underflow vulnerabilities using safe math operations and bounds checking,"// Production integer overflow/underflow prevention
// Pattern from DeFi protocols and token contracts
// Clarity: Safe math operations
const SAFE_MATH_CLARITY = `
;; Clarity has built-in overflow protection for all arithmetic
;; But here are best practices:
(define-constant MAX-UINT u340282366920938463463374607431768211455)
(define-constant ERR-OVERFLOW (err u300))
(define-constant ERR-UNDERFLOW (err u301))
;; Safe addition with explicit check
(define-private (safe-add (a uint) (b uint))
(let ((result (+ a b)))
(asserts! (>= result a) ERR-OVERFLOW)
(ok result)
)
)
;; Safe subtraction with explicit check
(define-private (safe-sub (a uint) (b uint))
(begin
(asserts! (>= a b) ERR-UNDERFLOW)
(ok (- a b))
)
)
;; Safe multiplication with overflow check
(define-private (safe-mul (a uint) (b uint))
(let ((result (* a b)))
(asserts! (or (is-eq a u0) (is-eq (/ result a) b)) ERR-OVERFLOW)
(ok result)
)
)
;; Safe division (checks for division by zero)
(define-private (safe-div (a uint) (b uint))
(begin
(asserts! (> b u0) (err u302))
(ok (/ a b))
)
)
;; Example: Safe token transfer calculation
(define-public (transfer-with-fee (amount uint) (fee-bps uint))
(let (
(fee (unwrap! (safe-mul amount fee-bps) (err u500)))
(fee-final (unwrap! (safe-div fee u10000) (err u500)))
(amount-after-fee (unwrap! (safe-sub amount fee-final) (err u500)))
)
(asserts! (> amount-after-fee u0) (err u400))
;; Transfer logic here
(ok amount-after-fee)
)
)
`;
// JavaScript: Validation before contract calls
import { request } from '@stacks/connect';
import { uintCV, cvToHex } from '@stacks/transactions';
// Maximum safe integer in Clarity (uint128)
const MAX_UINT128 = BigInt('340282366920938463463374607431768211455');
function validateAmount(amount: number | bigint): void {
const amountBig = BigInt(amount);
if (amountBig < 0) {
throw new Error('Amount cannot be negative');
}
if (amountBig > MAX_UINT128) {
throw new Error(`Amount exceeds maximum: ${MAX_UINT128}`);
}
}
async function safeTransferWithFee(
sender: string,
recipient: string,
tokenContract: string,
amount: number,
feeBps: number
) {
// Validate inputs
validateAmount(amount);
validateAmount(feeBps);
// Check fee calculation won't overflow
const fee = (BigInt(amount) * BigInt(feeBps)) / BigInt(10000);
if (fee > BigInt(amount)) {
throw new Error('Fee calculation error');
}
const amountAfterFee = BigInt(amount) - fee;
if (amountAfterFee <= 0) {
throw new Error('Amount too small for fee');
}
const args = [
uintCV(amount),
uintCV(feeBps),
principalCV(recipient)
];
return request('stx_callContract', {
contract: tokenContract,
functionName: 'transfer-with-fee',
functionArgs: args.map(cvToHex),
postConditionMode: 'deny',
network: 'mainnet'
});
}","Production integer overflow prevention. Clarity has built-in overflow protection, but explicit checks improve error messages. Shows safe math operations and validation patterns.","{""amount"": 1000000000, ""feeBps"": 500, ""maxUint128"": ""340282366920938463463374607431768211455""}","{""txId"": ""0x123..."", ""success"": true, ""amountAfterFee"": 950000000, ""feeAmount"": 50000000, ""overflowChecked"": true}","- Trusting JavaScript Number type (loses precision above 2^53)
- Not using BigInt for large amounts
- Forgetting Clarity's uint128 max value
- Missing checks on user input before contract calls
- Not handling edge cases (0, max value)",https://docs.stacks.co/clarity/security,"security-patterns.csv:2,clarity-syntax.csv:8,clarity-syntax.csv:14","security,overflow,underflow,safe-math,arithmetic,vulnerability,intermediate",intermediate
31,security,best-practice,access-control-pattern,"Implement role-based access control with owner, admin, and operator roles to secure privileged functions","// Production access control with role-based permissions
// From stacksagent-backend and DeFi protocol patterns
// Clarity: Multi-level RBAC
const RBAC_CLARITY = `
(define-constant ERR-NOT-OWNER (err u200))
(define-constant ERR-NOT-ADMIN (err u201))
(define-constant ERR-NOT-OPERATOR (err u202))
(define-constant ERR-UNAUTHORIZED (err u203))
;; Owner (highest privilege)
(define-data-var contract-owner principal tx-sender)
;; Admins (can manage operators)
(define-map admins principal bool)
;; Operators (can execute operations)
(define-map operators principal bool)
;; Role checks
(define-read-only (is-owner)
(is-eq tx-sender (var-get contract-owner))
)
(define-read-only (is-admin (user principal))
(or (is-owner) (default-to false (map-get? admins user)))
)
(define-read-only (is-operator (user principal))
(or (is-admin user) (default-to false (map-get? operators user)))
)
;; Owner-only: Transfer ownership
(define-public (transfer-ownership (new-owner principal))
(begin
(asserts! (is-owner) ERR-NOT-OWNER)
(asserts! (not (is-eq new-owner (var-get contract-owner))) (err u204))
(var-set contract-owner new-owner)
(print {event: ""ownership-transferred"", new-owner: new-owner})
(ok true)
)
)
;; Owner-only: Manage admins
(define-public (add-admin (admin principal))
(begin
(asserts! (is-owner) ERR-NOT-OWNER)
(map-set admins admin true)
(print {event: ""admin-added"", admin: admin})
(ok true)
)
)
;; Admin: Manage operators
(define-public (add-operator (operator principal))
(begin
(asserts! (is-admin tx-sender) ERR-NOT-ADMIN)
(map-set operators operator true)
(print {event: ""operator-added"", operator: operator})
(ok true)
)
)
;; Operator: Execute operations
(define-public (execute-operation (action (string-ascii 50)))
(begin
(asserts! (is-operator tx-sender) ERR-UNAUTHORIZED)
(print {event: ""operation-executed"", action: action, by: tx-sender})
(ok true)
)
)
`;
// JavaScript: Check roles before operations
import { callReadOnlyFunction, cvToJSON, principalCV } from '@stacks/transactions';
async function checkUserRole(
userAddress: string,
contractAddress: string
): Promise<{isOwner: boolean, isAdmin: boolean, isOperator: boolean}> {
const [address, name] = contractAddress.split('.');
// Check owner
const ownerResult = await callReadOnlyFunction({
contractAddress: address,
contractName: name,
functionName: 'is-owner',
functionArgs: [],
senderAddress: userAddress,
network: 'mainnet'
});
const isOwner = cvToJSON(ownerResult).value;
// Check admin
const adminResult = await callReadOnlyFunction({
contractAddress: address,
contractName: name,
functionName: 'is-admin',
functionArgs: [principalCV(userAddress)],
senderAddress: userAddress,
network: 'mainnet'
});
const isAdmin = cvToJSON(adminResult).value;
// Check operator
const operatorResult = await callReadOnlyFunction({
contractAddress: address,
contractName: name,
functionName: 'is-operator',
functionArgs: [principalCV(userAddress)],
senderAddress: userAddress,
network: 'mainnet'
});
const isOperator = cvToJSON(operatorResult).value;
return { isOwner, isAdmin, isOperator };
}","Role-based access control (RBAC) separates privileges into hierarchical roles: Owner (highest, usually deployer), Admins (trusted managers), Operators (day-to-day functions). Use tx-sender for authentication, NEVER trust function parameters for access checks. Implement read-only helpers (is-owner, is-admin) for reusability. Use asserts! at start of functions to fail fast. Define clear error codes per role. Consider two-step ownership transfer for safety. Document which functions require which roles. ALWAYS validate tx-sender, not contract-caller for security.","{""ownerAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""adminAddress"": ""SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"", ""operatorAddress"": ""SP1HTBVD3JG9C05J7HBJTHGR0GGW7KXW28M5JS8QE"", ""unauthorizedAddress"": ""SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7""}","{""ownerCanCallAny"": true, ""adminsCanCallAdminFunctions"": true, ""operatorsCanCallOperatorFunctions"": true, ""roleChecksBeforeLogic"": true, ""clearErrorMessages"": true}","- ALWAYS check tx-sender, NOT contract-caller
- DEFINE clear role hierarchy (owner > admin > operator)
- USE read-only helpers for role checks
- FAIL FAST with asserts! at function start
- NEVER trust user-provided principal for auth
- IMPLEMENT two-step ownership transfer for safety
- LOG all privilege changes
- DOCUMENT role requirements clearly",https://github.com/OpenZeppelin/cairo-contracts/blob/main/src/openzeppelin/access/accesscontrol/library.cairo,"security-patterns.csv:3,clarity-syntax.csv:31,stacks-js-core.csv:8","security,access-control,rbac,authorization,permissions,best-practice,intermediate",intermediate
32,security,best-practice,input-validation,"Validate and sanitize all user inputs with bounds checking, type validation, and business logic constraints","// Input validation comprehensive
const INPUT_VALIDATION_CLARITY = `
(define-constant ERR-INVALID-AMOUNT (err u400))
(define-constant ERR-INVALID-ADDRESS (err u401))
(define-constant ERR-INVALID-STRING (err u402))
(define-private (validate-amount (amount uint))
(begin
(asserts! (> amount u0) ERR-INVALID-AMOUNT)
(asserts! (< amount u1000000000000) ERR-INVALID-AMOUNT)
(ok amount)
)
)
(define-private (validate-address (addr principal))
(begin
(asserts! (not (is-eq addr 'SP000000000000000000002Q6VF78)) ERR-INVALID-ADDRESS)
(asserts! (not (is-eq addr tx-sender)) ERR-INVALID-ADDRESS)
(ok addr)
)
)
(define-public (transfer (amount uint) (recipient principal))
(begin
(try! (validate-amount amount))
(try! (validate-address recipient))
(ft-transfer? my-token amount tx-sender recipient)
)
)
`;","Production input validation patterns. Validates amounts, addresses, strings, and business logic constraints before execution.","{""invalidAmounts"": [0, 500, 999999999999999999], ""validAmount"": 1000000, ""invalidAddress"": ""SP000000000000000000002Q6VF78"", ""selfTransferAddress"": ""tx-sender"", ""emptyString"": """", ""longString"": ""aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"", ""validString"": ""valid memo"", ""emptyList"": [], ""largeList"": [""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item"", ""item""], ""invalidPercentage"": 10001}","{""zeroAmountError"": ""ERR-INVALID-AMOUNT"", ""lowAmountError"": ""ERR-INVALID-AMOUNT"", ""highAmountError"": ""ERR-OVERFLOW"", ""invalidAddressError"": ""ERR-INVALID-ADDRESS"", ""selfTransferError"": ""ERR-INVALID-ADDRESS"", ""emptyStringError"": ""ERR-INVALID-STRING"", ""longStringError"": ""ERR-INVALID-STRING"", ""emptyListError"": ""ERR-OUT-OF-BOUNDS"", ""largeListError"": ""ERR-OUT-OF-BOUNDS"", ""invalidPercentageError"": ""ERR-INVALID-PERCENTAGE"", ""validInputsSuccess"": true}","- VALIDATE all inputs before state changes
- CHECK bounds (min/max) for numeric values
- VERIFY principal addresses (not zero, not self)
- LIMIT string lengths to prevent DoS
- VALIDATE list lengths before iteration
- USE helper functions for reusability
- DEFINE clear validation constants
- CLIENT validation is UX, not security",https://github.com/crytic/building-secure-contracts/blob/master/development-guidelines/token_integration.md,"security-patterns.csv:5,clarity-syntax.csv:17,clarity-syntax.csv:33","security,validation,input-sanitization,bounds-checking,best-practice,intermediate",intermediate
33,security,security,rate-limiting-dos-protection,"Prevent Denial of Service attacks using rate limiting, gas accounting, and complexity bounds","// Rate limiting for DoS protection
const RATE_LIMIT_CLARITY = `
(define-map rate-limits principal {count: uint, window-start: uint})
(define-constant max-calls-per-window u10)
(define-constant window-blocks u144) ;; ~24 hours
(define-private (check-rate-limit)
(let (
(limit (default-to {count: u0, window-start: block-height}
(map-get? rate-limits tx-sender)))
(blocks-passed (- block-height (get window-start limit)))
)
(if (>= blocks-passed window-blocks)
(begin
(map-set rate-limits tx-sender {count: u1, window-start: block-height})
(ok true)
)
(begin
(asserts! (< (get count limit) max-calls-per-window) (err u429))
(map-set rate-limits tx-sender
(merge limit {count: (+ (get count limit) u1)}))
(ok true)
)
)
)
)
`;",Production rate limiting to prevent DoS attacks. Tracks calls per wallet in rolling time window and enforces limits.,"{""action_11_same_block"": ""11th action"", ""expensive_op_cooldown"": ""within 6 blocks"", ""batch_size_51"": ""51 items"", ""global_actions_1001"": ""1001st action"", ""normal_action"": ""1st action""}","{""rate_limit_exceeded"": ""err-u301 rate-limit"", ""cooldown_active"": ""err-u302 cooldown-active"", ""batch_too_large"": ""err-u303 too-complex"", ""global_limit"": ""err-u301 rate-limit"", ""normal_success"": ""ok true""}","- IMPLEMENT per-user AND global rate limits
- USE block-height for automatic counter resets
- ENFORCE maximum batch sizes (e.g., 50)
- ADD cooldowns for expensive operations
- NEVER allow unbounded loops
- TRACK gas consumption awareness
- CONSIDER economic costs as deterrent
- MONITOR for abuse patterns off-chain",https://consensys.github.io/smart-contract-best-practices/attacks/denial-of-service/,"security-patterns.csv:7,clarity-syntax.csv:42,advanced-patterns.csv:8","security,dos-protection,rate-limiting,gas-optimization,complexity-bounds,vulnerability,advanced",advanced
34,security,security,secure-randomness,Generate secure randomness using VRF (Verifiable Random Function) instead of predictable block properties,"// Secure randomness using VRF
const SECURE_RANDOM_CLARITY = `
(define-data-var nonce uint u0)
(define-read-only (get-pseudo-random (max uint))
(let (
(seed (buff-to-uint-be (hash-sha256 (concat
(unwrap-panic (to-consensus-buff? block-height))
(unwrap-panic (to-consensus-buff? (var-get nonce)))
))))
)
(ok (mod seed max))
)
)
(define-public (use-randomness)
(let ((random (unwrap! (get-pseudo-random u100) (err u500))))
(var-set nonce (+ (var-get nonce) u1))
(ok random)
)
)
`;","Production secure randomness using block hash + nonce. Not truly random but prevents prediction. For critical randomness, use VRF oracles.","{""vulnerable_block_hash"": ""height 12345"", ""vulnerable_tx_sender"": ""attacker controlled"", ""commit_reveal"": ""10 participants, 6 block delay"", ""vrf_proof"": ""valid VRF proof with public key""}","{""block_hash_result"": ""predictable, miner manipulable"", ""tx_sender_result"": ""attacker selects favorable address"", ""commit_reveal_result"": ""secure if majority honest"", ""vrf_result"": ""cryptographically secure, verifiable"", ""random_range"": ""0-99 uniform distribution""}","- NEVER use block-hash for randomness
- NEVER use tx-sender for randomness
- USE VRF with verifiable proofs (best)
- IMPLEMENT commit-reveal with delay
- COMBINE multiple randomness sources
- REQUIRE reveal delay (6+ blocks)
- VERIFY VRF proofs on-chain
- CONSIDER oracle integration for VRF",https://blog.chain.link/chainlink-vrf-on-chain-verifiable-randomness/,"security-patterns.csv:10,clarity-syntax.csv:47,oracles.csv:15","security,randomness,vrf,commit-reveal,lottery,vulnerability,advanced",advanced
35,security,security,privilege-escalation-prevention,"Prevent privilege escalation attacks through proper role validation, state management, and ownership transfer patterns","// Privilege escalation prevention
const PRIVILEGE_ESCALATION_CLARITY = `
(define-constant ERR-PRIVILEGE-ESCALATION (err u403))
(define-map user-roles principal (string-ascii 20))
(define-public (promote-user (user principal) (new-role (string-ascii 20)))
(let (
(caller-role (default-to ""none"" (map-get? user-roles tx-sender)))
(target-role (default-to ""none"" (map-get? user-roles user)))
)
;; Prevent self-promotion
(asserts! (not (is-eq tx-sender user)) ERR-PRIVILEGE-ESCALATION)
;; Prevent promoting to same or higher role
(asserts! (not (is-eq caller-role target-role)) ERR-PRIVILEGE-ESCALATION)
;; Only admin can promote to admin
(if (is-eq new-role ""admin"")
(asserts! (is-eq caller-role ""owner"") ERR-PRIVILEGE-ESCALATION)
true
)
(map-set user-roles user new-role)
(ok true)
)
)
`;",Production privilege escalation prevention. Users cannot promote themselves or promote others to equal/higher roles.,"{""vulnerable_transfer"": ""SP_TYPO_ADDRESS"", ""vulnerable_escalation"": ""admin adds self as owner"", ""secure_transfer"": ""two-step with acceptance"", ""timelock_execution"": ""before delay period"", ""role_escalation"": ""operator tries admin role""}","{""vulnerable_transfer"": ""ownership lost permanently"", ""vulnerable_escalation"": ""admin becomes owner"", ""secure_transfer"": ""pending until acceptance"", ""timelock_fail"": ""err-u609 before delay"", ""role_fail"": ""err-u605 insufficient level"", ""events"": ""all privilege changes logged""}","- ALWAYS use two-step ownership transfer
- REQUIRE explicit acceptance from new owner
- IMPLEMENT role hierarchy (level-based)
- USE timelocks for critical upgrades (24+ hours)
- PREVENT admins from self-elevation
- LOG all privilege changes with events
- ALLOW ownership transfer cancellation
- NEVER skip validation for ""trusted"" users",https://docs.openzeppelin.com/contracts/4.x/api/access,"security-patterns.csv:3,security-patterns.csv:6,clarity-syntax.csv:31","security,privilege-escalation,ownership,timelock,role-hierarchy,vulnerability,advanced",advanced
36,auth,quickstart,wallet-connect-flow,Complete wallet connection flow with address retrieval for STX and BTC addresses,"// Production wallet connection pattern from sbtc-market-frontend
export async function connectWallet() {
const { connect, isConnected, getLocalStorage } = await import(""@stacks/connect"");
// Check if already connected
if (isConnected()) {
const userData = getLocalStorage();
console.log('Already authenticated');
// Access STX and BTC addresses
if (userData?.addresses) {
const stxAddress = userData.addresses.stx?.[0]?.address;
const btcAddress = userData.addresses.btc?.[0]?.address;
console.log('STX Address:', stxAddress);
console.log('BTC Address:', btcAddress);
return { addresses: userData.addresses };
}
}
// Connect if not connected
return connect({
onFinish: (payload) => {
console.log('Connected:', payload.addresses);
},
});
}
// Helper: Get just the STX address
export async function resolveStxAddress() {
const { isConnected, getLocalStorage } = await import(""@stacks/connect"");
if (!isConnected()) return null;
const data = getLocalStorage();
return data?.addresses?.stx?.[0]?.address || null;
}
// Helper: Check connection status
export async function isWalletConnected() {
const { isConnected } = await import(""@stacks/connect"");
return isConnected();
}","Production wallet connection pattern from sbtc-market-frontend. Uses isConnected() to check before connecting, getLocalStorage() to retrieve addresses (both STX and BTC), and proper error handling.","{""walletInstalled"": true, ""userApproved"": true}","{""connected"": true, ""stxAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""btcAddress"": ""bc1q..."", ""addressesObject"": {""stx"": [{""address"": ""SP2C2YFP...""}], ""btc"": [{""address"": ""bc1q...""}]}}","- Not checking isConnected() before calling connect() causes unnecessary wallet popups
- Forgetting to handle case when wallet extension is not installed
- Not accessing userData.addresses correctly (it's nested: addresses.stx[0].address)
- Using deprecated showConnect() instead of connect()",https://github.com/your-username/sbtc-market-frontend/blob/main/src/lib/wallet.ts,"authentication.csv:1,authentication.csv:2,authentication.csv:4,stacks-js-core.csv:1,stacks-js-core.csv:5","authentication,wallet,connect,quickstart,react,beginner",beginner
37,auth,integration,jwt-authentication,Generate and verify JWT tokens from wallet signatures for secure server-side authentication,"// Production JWT authentication via wallet signature
// From stacksagent-frontend/src/components/auth/WalletAuthenticator.tsx
import { request } from '@stacks/connect';
async function authenticateWalletWithJWT() {
// 1. Generate timestamp and message
const timestamp = Date.now();
const message = `Authenticate with StacksAgent: ${timestamp}`;
try {
// 2. Request signature from wallet
const response = await request('stx_signMessage', {
message,
});
const signature = response.signature;
const publicKey = response.publicKey;
console.log('Signature obtained:', signature.substring(0, 20) + '...');
// 3. Send to backend for JWT generation
const authResponse = await fetch('/api/auth/authenticate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
message,
signature,
publicKey,
timestamp
})
});
if (!authResponse.ok) {
throw new Error('Server could not verify signature');
}
// 4. Get JWT token from response
const { token, expiresAt } = await authResponse.json();
// 5. Store JWT (httpOnly cookie preferred, or localStorage)
document.cookie = `auth_token=${token}; path=/; secure; samesite=strict`;
console.log('✅ Authenticated successfully');
console.log('Token expires:', new Date(expiresAt));
return { success: true, token, expiresAt };
} catch (error) {
if (error.message.includes('User denied')) {
console.error('User cancelled signature request');
} else {
console.error('Authentication failed:', error.message);
}
return { success: false, error: error.message };
}
}
// Backend verification (Node.js/Express example)
/*
import { verifyMessageSignatureRsv } from '@stacks/encryption';
import jwt from 'jsonwebtoken';
app.post('/api/auth/authenticate', (req, res) => {
const { message, signature, publicKey, timestamp } = req.body;
// 1. Verify timestamp freshness (within 5 minutes)
const now = Date.now();
if (Math.abs(now - timestamp) > 5 * 60 * 1000) {
return res.status(401).json({ error: 'Timestamp expired' });
}
// 2. Verify signature
const isValid = verifyMessageSignatureRsv({ message, publicKey, signature });
if (!isValid) {
return res.status(401).json({ error: 'Invalid signature' });
}
// 3. Generate JWT
const walletAddress = publicKeyToAddress(publicKey);
const token = jwt.sign(
{ address: walletAddress, publicKey },
process.env.JWT_SECRET,
{ expiresIn: '24h' }
);
return res.json({
token,
expiresAt: Date.now() + 24 * 60 * 60 * 1000
});
});
*/","Production JWT authentication pattern from stacksagent-frontend. User signs a timestamped message with their wallet, backend verifies signature and returns JWT token. Includes both frontend and backend code.","{""message"": ""Authenticate with StacksAgent: 1704067200000"", ""walletConnected"": true, ""userApprovesSignature"": true}","{""success"": true, ""token"": ""eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."", ""expiresAt"": 1704153600000, ""signature"": ""0x1234567890abcdef..."", ""publicKey"": ""03abcdef1234567890...""}","- Not validating timestamp freshness on backend (replay attacks)
- Storing JWT in localStorage instead of httpOnly cookies (XSS vulnerability)
- Not handling user rejection of signature request
- Using weak JWT_SECRET or hardcoding it
- Not verifying signature correctly on backend",https://github.com/your-username/stacksagent-frontend/blob/main/src/components/auth/WalletAuthenticator.tsx,"authentication.csv:1,authentication.csv:7,authentication.csv:8,stacks-js-core.csv:47,security-patterns.csv:1","authentication,jwt,signature,security,server-side,intermediate",intermediate
38,auth,integration,protected-routes,Implement authentication guards for protected routes with automatic redirection and session validation,"// Production protected routes with wallet auth
// Pattern from STX City deploy-stx-city
import { connect, getLocalStorage } from '@stacks/connect';
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
// Zustand store with localStorage persistence
interface StacksStore {
userData: {
profile: {
stxAddress: { mainnet: string; testnet: string };
btcAddress: { mainnet: string; testnet: string };
}
};
isAuthenticated: boolean;
handleLogIn: () => Promise<void>;
}
const useStacksStore = create<StacksStore>()(
persist(
(set) => ({
userData: {
profile: {
stxAddress: { mainnet: '', testnet: '' },
btcAddress: { mainnet: '', testnet: '' }
}
},
isAuthenticated: false,
async handleLogIn() {
const connectResponse = await connect();
const localData = getLocalStorage();
set({
userData: {
profile: {
stxAddress: {
mainnet: localData.addresses.stx[0].address,
testnet: localData.addresses.stx[0].address
},
btcAddress: {
mainnet: localData.addresses.btc[0].address,
testnet: localData.addresses.btc[0].address
}
}
},
isAuthenticated: true
});
}
}),
{
name: 'stacks-storage',
getStorage: () => localStorage
}
)
);
// React Router protected route component
import { Navigate } from 'react-router-dom';
function ProtectedRoute({ children }: { children: React.ReactNode }) {
const { isAuthenticated, userData } = useStacksStore();
// Check if user is authenticated
if (!isAuthenticated || !userData.profile.stxAddress.mainnet) {
// Redirect to login page
return <Navigate to=""/login"" replace />;
}
return <>{children}</>;
}
// Usage in routes
/*
<Routes>
<Route path=""/login"" element={<LoginPage />} />
<Route path=""/dashboard"" element={
<ProtectedRoute>
<Dashboard />
</ProtectedRoute>
} />
<Route path=""/profile"" element={
<ProtectedRoute>
<ProfilePage />
</ProtectedRoute>
} />
</Routes>
*/",Production protected routes from STX City using Zustand with localStorage persistence. Reconnects wallet state across reloads and guards routes with authentication checks.,"{""userConnected"": true, ""stxAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""requestedRoute"": ""/dashboard"", ""sessionPersisted"": true}","{""accessGranted"": true, ""redirectTo"": null, ""sessionRestored"": true, ""addressesAvailable"": {""stx"": ""SP2C2YFP..."", ""btc"": ""bc1q...""}}","- Not persisting state causes logout on refresh
- Forgetting to check isAuthenticated AND address presence
- Not using replace in Navigate causes back button issues
- Hardcoding redirect paths instead of using location.state
- Not handling wallet disconnection during session",https://github.com/stx-city/deploy-stx-city/blob/main/src/store/StacksStore.ts,"authentication.csv:5,authentication.csv:6,authentication.csv:8,stacks-js-core.csv:2,stacks-js-core.csv:4","authentication,routing,middleware,protected,nextjs,react,intermediate",intermediate
39,auth,integration,nft-token-gating,Verify NFT ownership on-chain to gate premium content and features,"// Production NFT ownership verification for gating
// Pattern from STX City token metadata and portfolio patterns
import { callReadOnlyFunction, principalCV, uintCV, cvToJSON } from '@stacks/transactions';
import axios from 'axios';
// Check NFT ownership using read-only function
async function checkNFTOwnership(
walletAddress: string,
nftContract: string,
tokenId: number
): Promise<boolean> {
try {
const [contractAddress, contractName] = nftContract.split('.');
// Call get-owner read-only function
const result = await callReadOnlyFunction({
contractAddress,
contractName,
functionName: 'get-owner',
functionArgs: [uintCV(tokenId)],
senderAddress: walletAddress,
network: 'mainnet'
});
const owner = cvToJSON(result).value.value;
return owner === walletAddress;
} catch (error) {
console.error('NFT ownership check failed:', error);
return false;
}
}
// Check if wallet owns any NFT from collection
async function hasCollectionAccess(
walletAddress: string,
collectionContract: string
): Promise<boolean> {
try {
// Use Hiro API to get all NFT holdings
const headers = { 'x-hiro-api-key': process.env.HIRO_API_KEY };
const { data } = await axios.get(
`https://api.hiro.so/extended/v1/tokens/nft/holdings?principal=${walletAddress}`,
{ headers }
);
// Check if any NFT is from the target collection
const hasNFT = data.results.some((nft: any) =>
nft.asset_identifier.startsWith(collectionContract)
);
return hasNFT;
} catch (error) {
console.error('Collection check failed:', error);
return false;
}
}
// Express.js middleware for NFT-gated routes
/*
async function nftGateMiddleware(req, res, next) {
const walletAddress = req.session.walletAddress;
const requiredCollection = 'SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.stacks-punks-v2';
if (!walletAddress) {
return res.status(401).json({ error: 'Not authenticated' });
}
const hasAccess = await hasCollectionAccess(walletAddress, requiredCollection);
if (!hasAccess) {
return res.status(403).json({
error: 'NFT required',
message: 'You must own a Stacks Punks NFT to access this feature'
});
}
next();
}
// Protected route
app.get('/api/premium/data', nftGateMiddleware, (req, res) => {
res.json({ data: 'Premium content for NFT holders' });
});
*/",Production NFT gating using both read-only contract calls and Hiro API. Verifies specific NFT ownership or collection membership for premium feature access.,"{""walletAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""nftContract"": ""SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.stacks-punks-v2"", ""requiredTokenId"": 42, ""userOwnsToken"": true}","{""hasAccess"": true, ""ownershipVerified"": true, ""nftDetails"": {""collection"": ""Stacks Punks"", ""tokenId"": 42}, ""accessGranted"": true}","- Not handling NFT transfers (ownership can change)
- Relying only on frontend checks (bypass via devtools)
- Not caching results causes rate limiting on Hiro API
- Forgetting to validate contract is legitimate NFT collection
- Not handling NFT not found errors gracefully",https://github.com/stx-city/deploy-stx-city/blob/main/src/lib/curveDetailUtils.ts,"authentication.csv:12,nfts.csv:5,stacks-js-core.csv:38,security-patterns.csv:1","authentication,nft,token-gating,access-control,sip009,intermediate",intermediate
40,auth,best-practice,session-management,Implement secure server-side session storage with wallet address binding and automatic cleanup,"// Production session management with wallet binding
// Pattern from STX City wallet auth and server security
import { randomBytes } from 'crypto';
import { verifyMessageSignatureRsv } from '@stacks/encryption';
interface Session {
id: string;
walletAddress: string;
publicKey: string;
createdAt: number;
expiresAt: number;
lastActivity: number;
}
// In-memory session store (use Redis in production)
const sessions = new Map<string, Session>();
// Session configuration
const SESSION_DURATION = 24 * 60 * 60 * 1000; // 24 hours
const ACTIVITY_TIMEOUT = 30 * 60 * 1000; // 30 minutes
const CLEANUP_INTERVAL = 60 * 60 * 1000; // 1 hour
// Create session after wallet signature verification
export async function createSession(
message: string,
signature: string,
publicKey: string
): Promise<{ sessionId: string; expiresAt: number } | null> {
try {
// 1. Verify signature
const isValid = verifyMessageSignatureRsv({ message, publicKey, signature });
if (!isValid) {
console.error('Invalid signature');
return null;
}
// 2. Extract wallet address from public key
const { publicKeyToAddress } = await import('@stacks/transactions');
const walletAddress = publicKeyToAddress(publicKey);
// 3. Generate secure session ID
const sessionId = randomBytes(32).toString('hex');
// 4. Create session
const now = Date.now();
const session: Session = {
id: sessionId,
walletAddress,
publicKey,
createdAt: now,
expiresAt: now + SESSION_DURATION,
lastActivity: now
};
sessions.set(sessionId, session);
console.log(`✅ Session created for ${walletAddress}`);
return { sessionId, expiresAt: session.expiresAt };
} catch (error) {
console.error('Session creation failed:', error);
return null;
}
}
// Validate and refresh session
export function validateSession(sessionId: string): Session | null {
const session = sessions.get(sessionId);
if (!session) {
return null;
}
const now = Date.now();
// Check if session expired
if (now > session.expiresAt) {
sessions.delete(sessionId);
return null;
}
// Check activity timeout
if (now - session.lastActivity > ACTIVITY_TIMEOUT) {
sessions.delete(sessionId);
return null;
}
// Update last activity
session.lastActivity = now;
sessions.set(sessionId, session);
return session;
}
// Cleanup expired sessions (run periodically)
export function cleanupExpiredSessions() {
const now = Date.now();
let cleaned = 0;
for (const [sessionId, session] of sessions.entries()) {
if (now > session.expiresAt || now - session.lastActivity > ACTIVITY_TIMEOUT) {
sessions.delete(sessionId);
cleaned++;
}
}
if (cleaned > 0) {
console.log(`🧹 Cleaned up ${cleaned} expired sessions`);
}
}
// Start cleanup interval
setInterval(cleanupExpiredSessions, CLEANUP_INTERVAL);
// Express.js middleware
/*
function sessionMiddleware(req, res, next) {
const sessionId = req.cookies.session_id;
if (!sessionId) {
return res.status(401).json({ error: 'No session' });
}
const session = validateSession(sessionId);
if (!session) {
res.clearCookie('session_id');
return res.status(401).json({ error: 'Invalid or expired session' });
}
req.session = session;
req.walletAddress = session.walletAddress;
next();
}
*/","Production session management with wallet address binding and automatic cleanup. Uses httpOnly cookies, validates signatures, and implements activity timeouts.","{""message"": ""Authenticate: 1704067200000"", ""signature"": ""0x1234567890abcdef..."", ""publicKey"": ""03abcdef..."", ""signatureValid"": true}","{""sessionId"": ""a1b2c3d4e5f6..."", ""expiresAt"": 1704153600000, ""walletAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""sessionCreated"": true, ""cookieSet"": true}","- Using localStorage for sessions (XSS vulnerability)
- Not implementing activity timeout allows stale sessions
- Forgetting cleanup causes memory leaks
- Not binding session to wallet address (session hijacking)
- Using weak session ID generation (predictable IDs)",https://github.com/stx-city/deploy-stx-city/blob/main/src/store/StacksStore.ts,"authentication.csv:2,authentication.csv:9,security-patterns.csv:1,security-patterns.csv:4","authentication,session,redis,security,cookies,best-practice,intermediate",intermediate
41,deployment,quickstart,deploy-contract-with-fees,Deploy Clarity contract to mainnet with post-condition protection,"// Production contract deployment from STX City deploy page
// Pattern from /Volumes/Projects/STXCITY/deploy-stx-city/src/app/deploy/create/page.tsx
import { request } from '@stacks/connect';
import { Pc, PostConditionMode } from '@stacks/transactions';
// Option 1: Deploy with STX payment
async function deployContractWithSTX(
walletAddress: string,
contractName: string,
clarityCode: string,
deployFee: number = 2000000 // 2 STX in micro-STX
) {
// Create post-condition: Wallet will send at most deployFee STX
const sendSTXPostCondition = Pc.principal(walletAddress)
.willSendLte(deployFee)
.ustx();
const deployResponse = await request('stx_deployContract', {
name: contractName,
clarityCode: clarityCode,
clarityVersion: 3,
network: 'mainnet',
postConditions: [sendSTXPostCondition],
postConditionMode: 'deny',
fee: 100000 // Transaction fee (0.1 STX)
});
if (deployResponse) {
console.log('✅ Contract deployed successfully!');
console.log('Transaction ID:', deployResponse.txid);
console.log('View at:', `https://explorer.hiro.so/txid/${deployResponse.txid}?chain=mainnet`);
return deployResponse.txid;
}
}
// Option 2: Deploy with token payment (e.g., WELSH, VELAR)
async function deployContractWithToken(
walletAddress: string,
contractName: string,
clarityCode: string,
tokenContractId: string, // e.g., 'SP3NE50GEXFG9SZGTT51P40X2CKYSZ5CC4ZTZ7A2G.welshcorgicoin-token'
assetName: string, // e.g., 'welshcorgicoin'
tokenAmount: number, // Token amount with decimals
) {
// Create post-condition: Wallet will send at most tokenAmount of token
const sendFTCondition = Pc.principal(walletAddress)
.willSendLte(tokenAmount)
.ft(tokenContractId, assetName);
const deployResponse = await request('stx_deployContract', {
name: contractName,
clarityCode: clarityCode,
clarityVersion: 3,
network: 'mainnet',
postConditions: [sendFTCondition],
postConditionMode: 'deny',
fee: 100000
});
if (deployResponse) {
console.log('✅ Contract deployed with token payment!');
console.log('Transaction ID:', deployResponse.txid);
return deployResponse.txid;
}
}
// Example usage: Deploy SIP-010 token contract
async function deploySIP10Token() {
const walletAddress = 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR';
const contractName = 'my-awesome-token';
// Sample SIP-010 contract code (simplified)
const clarityCode = `
;; SIP-010 Token Contract
(impl-trait 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard.sip-010-trait)
(define-fungible-token my-token u1000000000)
(define-constant contract-owner tx-sender)
(define-read-only (get-name)
(ok ""My Awesome Token""))
(define-read-only (get-symbol)
(ok ""MAT""))
(define-read-only (get-decimals)
(ok u6))
(define-read-only (get-balance (who principal))
(ok (ft-get-balance my-token who)))
(define-read-only (get-total-supply)
(ok (ft-get-supply my-token)))
(define-public (transfer (amount uint) (sender principal) (recipient principal) (memo (optional (buff 34))))
(begin
(asserts! (is-eq tx-sender sender) (err u4))
(try! (ft-transfer? my-token amount sender recipient))
(match memo to-print (print to-print) 0x)
(ok true)
))
;; Mint initial supply to contract owner
(try! (ft-mint? my-token u1000000000 contract-owner))
`;
// Deploy with 2 STX fee
const txId = await deployContractWithSTX(
walletAddress,
contractName,
clarityCode,
2000000 // 2 STX
);
return txId;
}
// Production pattern from STX City: Convert name to valid contract slug
function convertToSlug(name: string): string {
return name
.toLowerCase()
.replace(/[^a-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '');
}","Production contract deployment pattern from STX City. Uses request('stx_deployContract', ...) with post-conditions to protect against excessive spending. Supports both STX and token payment methods. Always uses PostConditionMode.Deny for security.","{""walletAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR"", ""contractName"": ""my-token"", ""clarityCode"": ""(define-fungible-token...)"", ""network"": ""mainnet"", ""deployFee"": 2000000}","{""txid"": ""0xabc123..."", ""success"": true, ""explorerUrl"": ""https://explorer.hiro.so/txid/0xabc123...?chain=mainnet"", ""contractAddress"": ""SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.my-token""}","- Forgetting post-conditions allows unlimited spending
- Using PostConditionMode.Allow instead of Deny (security risk)
- Not converting contract name to valid slug (deployment fails)
- Setting fee too low causes transaction to be rejected
- Forgetting clarityVersion parameter defaults to Clarity 2
- Not handling deployResponse being null/undefined
- Using testnet contract addresses on mainnet
- Contract name must be lowercase alphanumeric + hyphens only",https://github.com/stx-city/deploy-stx-city/blob/main/src/app/deploy/create/page.tsx,"deployment.csv:1,deployment.csv:2,fungible-tokens.csv:1,security-patterns.csv:1","deploy,contract,stx_deployContract,post-conditions,mainnet,fees,security,quickstart,beginner",beginner
