@lazysuperheroes/farming-sdk

TypeScript SDK for interacting with the Lazy Superheroes NFT farming and staking system on Hedera.

Installation

npm install @lazysuperheroes/farming-sdk
# or
yarn add @lazysuperheroes/farming-sdk

Peer Dependencies

This SDK requires the following peer dependencies:

npm install @hashgraph/sdk ethers

Quick Start

import { createMainnetClient, MAINNET_CONTRACTS } from '@lazysuperheroes/farming-sdk';

// Create a client for mainnet
const client = createMainnetClient(
  '0.0.123456',        // Your operator account ID
  'your-private-key',   // ED25519 private key
  'signing-key'         // Optional: ECDSA key for staking signatures
);

// Get staking info
const stakingInfo = await client.getStakingInfo();
console.log(`Total NFTs staked: ${stakingInfo.totalStaked}`);
console.log(`Total $LAZY distributed: ${stakingInfo.totalDistributed}`);

// Get mission info
const mission = await client.getMissionInfo('0.0.789012');
console.log(`Mission: ${mission.name}`);
console.log(`Duration: ${mission.duration} seconds`);
console.log(`Slots available: ${mission.slotsAvailable}`);

Configuration

Network Environments

import { createClient } from '@lazysuperheroes/farming-sdk';

// Mainnet
const mainnetClient = createClient({
  environment: 'mainnet',
  operatorId: '0.0.123456',
  operatorKey: 'your-private-key',
});

// Testnet
const testnetClient = createClient({
  environment: 'testnet',
  operatorId: '0.0.123456',
  operatorKey: 'your-private-key',
});

// Custom contract addresses (for testnet)
testnetClient.setContracts({
  lazyNftStaking: '0.0.TESTNET_STAKING',
  missionFactory: '0.0.TESTNET_FACTORY',
});

Mainnet Contract Addresses

The SDK includes mainnet addresses by default:

import { MAINNET_CONTRACTS } from '@lazysuperheroes/farming-sdk';

console.log(MAINNET_CONTRACTS.LAZY_TOKEN);      // 0.0.1311037
console.log(MAINNET_CONTRACTS.NFT_STAKING);     // 0.0.7221488
console.log(MAINNET_CONTRACTS.MISSION_FACTORY); // 0.0.8257122
console.log(MAINNET_CONTRACTS.BOOST_MANAGER);   // 0.0.8257105
console.log(MAINNET_CONTRACTS.PRNG);            // 0.0.10583667
console.log(MAINNET_CONTRACTS.GEM_TOKEN);       // 0.0.10580248

Staking Operations

Get Staking Info

const info = await client.getStakingInfo();

console.log({
  totalStaked: info.totalStaked,
  totalDistributed: info.totalDistributed.toString(),
  distributionPeriod: info.distributionPeriod,
  burnPercentage: info.burnPercentage,
  hodlBonusRate: info.hodlBonusRate,
  maxBonusPeriods: info.maxBonusPeriods,
});

Get Stakeable Collections

const collections = await client.getStakeableCollections();

for (const collection of collections) {
  console.log(`Collection: ${collection.tokenId}`);
  console.log(`Max reward rate: ${collection.maxRewardRate}`);
}

Stake NFTs

import { createStake } from '@lazysuperheroes/farming-sdk';

// Create stake objects (collection must be in EVM address format)
const stakes = [
  createStake(
    '0x0000000000000000000000000000000000123456', // Collection EVM address
    [1, 2, 3],      // Serial numbers
    [100, 100, 100] // Reward rates
  ),
];

// Generate reward proof (requires ECDSA signing key)
const rewardProof = await client.generateRewardProof(0, stakes);

// Execute stake
const result = await client.stake(stakes, rewardProof);

if (result.success) {
  console.log(`Staked successfully! TX: ${result.transactionId}`);
} else {
  console.error(`Stake failed: ${result.error}`);
}

Unstake NFTs

const result = await client.unstake(stakes, rewardProof);

Mission Operations

Get Mission Info

const mission = await client.getMissionInfo('0.0.789012');

console.log({
  name: mission.name,
  duration: mission.duration,
  entryFee: mission.entryFee.toString(),
  currentParticipants: mission.currentParticipants,
  slotsAvailable: mission.slotsAvailable,
  isPaused: mission.isPaused,
});

Enter a Mission

const result = await client.enterMission(
  '0.0.789012',      // Mission contract
  '0.0.COLLECTION',  // NFT collection
  [1, 2, 3]          // Serial numbers to commit
);

if (result.success) {
  console.log('Entered mission!');
}

Leave a Mission

const result = await client.leaveMission('0.0.789012');

Claim Mission Rewards

const result = await client.claimMissionRewards('0.0.789012');

Boost Operations

Boost with Gem NFT

const result = await client.boostWithGem(
  '0.0.MISSION',     // Mission to boost
  '0.0.GEM_COLLECTION',  // Gem NFT collection
  42                     // Gem serial number
);

Boost with $LAZY

const result = await client.boostWithLazy(
  '0.0.MISSION',
  BigInt(1000)  // $LAZY amount
);

Gem Operations

List an Account's Gems

getOwnedGems reads which gem NFTs an account holds (from the mirror node) and groups them by boost level. It defaults to the mainnet gems collection (MAINNET_CONTRACTS.GEM_TOKEN), so callers don't need to know the token id.

import { lookupGemLevel } from '@lazysuperheroes/farming-sdk';

const gems = await client.getOwnedGems('0.0.123456');

console.log(`Total gems: ${gems.total}`);
console.log(`Best gem: ${gems.bestLevel !== null ? lookupGemLevel(gems.bestLevel) : 'none'}`);

// holdings are ordered highest-reduction first; empty levels are omitted
for (const h of gems.holdings) {
  console.log(`${h.levelName}: ${h.serials.length} gems (${h.reduction}% boost) -> ${h.serials.join(', ')}`);
}

// Pass a different collection if needed:
// const gems = await client.getOwnedGems('0.0.123456', '0.0.10580248');

Each serial is mapped to its level via the published GEM_SERIAL_RANGES, which mirror the on-chain BoostManager config. For an authoritative per-serial check, query BoostManager.getBoostLevel directly.

Delegation Operations

Delegate an NFT

const result = await client.delegate(
  '0.0.COLLECTION',  // NFT collection
  42,                // Serial number
  '0.0.DELEGATE'     // Delegate to this account
);

Revoke Delegation

const result = await client.revokeDelegation(
  '0.0.COLLECTION',
  42
);

Helper Functions

Staking Helpers

import {
  createStake,
  validateStake,
  countTotalNFTs,
  generateStakingRewardProof,
} from '@lazysuperheroes/farming-sdk';

// Create a stake object
const stake = createStake(evmAddress, serials, rewards);

// Validate stake data
validateStake(stake); // Throws if invalid

// Count total NFTs across multiple stakes
const total = countTotalNFTs([stake1, stake2]);

Farming Helpers

import {
  formatDuration,
  calculateTimeRemaining,
  canClaimRewards,
  calculateBoostedDuration,
  lookupLevel,
} from '@lazysuperheroes/farming-sdk';

// Format duration for display
formatDuration(3600);  // "1h"
formatDuration(90000); // "1d 1h"

// Calculate remaining time
const remaining = calculateTimeRemaining(entryTime, duration);

// Check if rewards can be claimed
const canClaim = canClaimRewards(entryTime, duration, boostPercent);

// Calculate boosted duration
const boosted = calculateBoostedDuration(86400, 25); // 75% of original

// Gem level helpers
lookupLevel(3); // "UR"
getLevel("SR"); // 2

Constants

import { GAS, DELAYS, TIME, DECIMALS } from '@lazysuperheroes/farming-sdk';

// Gas limits
GAS.MISSION_ENTER;  // 2_000_000
GAS.STAKE_BASE;     // 400_000

// Calculate stake gas
calculateStakeGas(5); // 2_400_000

// Time constants
TIME.DAY;   // 86400
TIME.WEEK;  // 604800

// Token decimals
DECIMALS.LAZY; // 1
DECIMALS.HBAR; // 8

TypeScript Types

All types are exported for TypeScript users:

import type {
  SDKConfig,
  StakingInfo,
  MissionInfo,
  Stake,
  RewardProof,
  TransactionResult,
  OwnedGems,
  GemHolding,
} from '@lazysuperheroes/farming-sdk';

Error Handling

const result = await client.stake(stakes, proof);

if (!result.success) {
  console.error(`Transaction failed: ${result.error}`);
  return;
}

console.log(`Success! TX ID: ${result.transactionId}`);
console.log(`Gas used: ${result.gasUsed}`);

License

MIT

Links

• Main Repository
• Lazy Superheroes
• Hedera Developer Docs