Skip to main content

​
Overview

Create custom achievements that users can earn based on specific actions or milestones in your protocol or application.

​
Prerequisites

  • Protocol Registration: Your protocol must be registered
  • Admin Permissions: Must have achievement creation permissions
  • Gas Fees: Sufficient ETH for transaction fees
  • Achievement Design: Well-defined achievement criteria

​
Achievement Creation Process

​
1. Define Achievement Parameters

// Achievement parameters
const achievementData = {
  name: 'DeFi Pioneer',
  description: 'Complete your first DeFi transaction',
  category: 'defi',
  rarity: 'common', // common, uncommon, rare, epic, legendary
  points: 50,
  requirements: {
    type: 'transaction_count',
    protocol: 'uniswap',
    minimum: 1
  },
  imageUrl: 'https://api.onzks.com/achievements/defi-pioneer.png',
  metadata: {
    protocol: 'uniswap',
    version: 'v3'
  }
};

​
2. Create Achievement

// Create achievement
const tx = await achievementRegistry.createAchievement(
  achievementData.name,
  achievementData.description,
  achievementData.category,
  achievementData.rarity,
  achievementData.points,
  achievementData.requirements,
  achievementData.imageUrl,
  achievementData.metadata
);

await tx.wait();
console.log('Achievement created!', tx.hash);

​
3. Verify Creation

// Get achievement details
const achievementId = await achievementRegistry.getLatestAchievementId();
const achievement = await achievementRegistry.getAchievement(achievementId);

console.log('Achievement created:', achievement);
console.log('Achievement ID:', achievementId.toString());

​
Achievement Parameters

​
Required Parameters

  • name: Achievement display name
  • description: Detailed description
  • category: Achievement category (defi, nft, social, etc.)
  • rarity: Rarity level (common, uncommon, rare, epic, legendary)
  • points: Points awarded
  • requirements: Requirements object
  • imageUrl: Achievement badge image URL

​
Optional Parameters

  • metadata: Additional metadata object
  • expiration: Optional expiration timestamp
  • maxClaims: Maximum number of claims allowed
  • protocol: Associated protocol identifier

​
Requirement Types

​
Transaction Count

const requirements = {
  type: 'transaction_count',
  protocol: 'uniswap',
  minimum: 10,
  timeframe: 30 * 24 * 60 * 60 // 30 days in seconds
};

​
Score Threshold

const requirements = {
  type: 'score_threshold',
  category: 'defi',
  minimum: 500
};

​
Achievement Prerequisites

const requirements = {
  type: 'achievement_prerequisites',
  achievements: ['defi-pioneer', 'liquidity-provider']
};

​
Custom Logic

const requirements = {
  type: 'custom',
  contract: '0x...', // Custom verification contract
  function: 'verifyAchievement',
  parameters: ['user', 'data']
};

​
Rarity and Points

​
Rarity Levels

RarityPointsDescription
Common10-50Easy to earn
Uncommon50-100Moderate difficulty
Rare100-250Challenging
Epic250-500Very difficult
Legendary500-1000Extremely rare

​
Points Calculation

// Calculate points based on rarity
function calculatePoints(rarity) {
  const basePoints = {
    common: 25,
    uncommon: 75,
    rare: 175,
    epic: 375,
    legendary: 750
  };
  
  return basePoints[rarity] || 25;
}

​
Error Handling

​
Common Errors

ErrorDescriptionSolution
PROTOCOL_NOT_REGISTEREDProtocol not registeredRegister protocol first
INSUFFICIENT_PERMISSIONSNo creation permissionsGet admin permissions
INVALID_REQUIREMENTSInvalid requirements formatFix requirements object
ACHIEVEMENT_EXISTSAchievement name already existsUse unique name

​
Error Handling Example

try {
  const tx = await achievementRegistry.createAchievement(
    'DeFi Pioneer',
    'Complete your first DeFi transaction',
    'defi',
    'common',
    50,
    requirements,
    imageUrl,
    metadata
  );
  
  await tx.wait();
  console.log('Achievement created successfully!');
} catch (error) {
  if (error.code === 'PROTOCOL_NOT_REGISTERED') {
    console.error('Protocol not registered. Register first.');
  } else if (error.code === 'INSUFFICIENT_PERMISSIONS') {
    console.error('Insufficient permissions to create achievements.');
  } else {
    console.error('Achievement creation failed:', error.message);
  }
}

​
Best Practices

  1. Clear Requirements: Define clear, measurable requirements
  2. Appropriate Rarity: Match rarity to difficulty
  3. Unique Names: Use unique achievement names
  4. Test Thoroughly: Test requirements before deployment
  5. Monitor Usage: Track achievement claiming patterns