This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

@thanpolas/dfk-hero

DeFi Kingdoms Hero

Utility library for fetching and working with DFK Heroes.

Install

Install the module using NPM:

npm install @thanpolas/dfk-hero --save

Documentation

Quick Start

const { getHeroesChain } = require('@thanpolas/dfk-hero');

const [hero] = await getHeroesChain([10000]);

console.log(hero);

Configuration

Configuring RPC

By default the library will use the Official Harmony RPC. You may override this by configuring dfk-hero:

dfkHero.config('getProvider', async () => {
    return {
        name: 'Pokt',
        provider: new ethers.providers.JsonRpcProvider('https://....'),
    };
});

What has been done above is to set the configuration key named getProvider and give it a value of a callback function. This function will be invoked by the library and it expects to receive an object with two keys:

• name {string} An arbitrary name (label) of the RPC.
• provider {Object} An ethers.js instance of a provider.

ℹ️ The callback function can be a Promise returning function.

Other Configuration Options

• maxRetries {number} Default: 6 - Define how many times the queries will retry on fail until they give up.
• concurrentBlockChainRequests {number} Default: 30 - Define how many concurrent blockchain queries the library should perform.

Configuring Using an Object

The config function accepts an object as well:

dfkHero.config({
    getProvider: async () => {
        return {
            name: 'Pokt',
            provider: new ethers.providers.JsonRpcProvider('https://....'),
        };
    },
    maxRetries: 8,
    concurrentBlockChainRequests: 50,
});

Available Commands

dfkHero.getHeroesChain(heroIds)

Will fetch and normalize heroes from the blockchain using provided hero ids. It will augment the hero object using multiple queries and functions to also include sales data, owner profile and decode all stat and visual genes.

• heroIds {Array<number|string|bigint>} An array with the hero Ids.
• Returns {Promise<Array<Object>>} A Promise with an array of the normalized hero data objects.

const { getHeroesChain } = require('@thanpolas/dfk-hero');

const [hero] = await getHeroesChain([10000]);

console.log(hero);

View the Hero Data Object at the relative section..

fetchHeroesByOwnerChain(ownerAddress)

Fetches and normalizes heroes based on the owner.

• ownerAddress {string} The owner's address.
• Returns {Promise<Array<Object>>} A Promise with an array of the normalized hero data objects.

const { fetchHeroesByOwnerChain } = require('@thanpolas/dfk-hero');

const heroes = await fetchHeroesByOwnerChain(myAddress);

console.log(heroes);

fetchHeroesByOwnerAndProfessionChain(ownerAddress, profession)

Fetches and normalizes heroes based on the owner and profession.

• ownerAddress {string} The owner's address.
• profession {string} The desired profession to filter by, can be one of: mining, gardening, fishing and foraging.
• Returns {Promise<Array<Object>>} A Promise with an array of the normalized hero data objects filtered by profession.

const { fetchHeroesByOwnerAndProfessionChain } = require('@thanpolas/dfk-hero');

const myAddress = '0x....';
const heroes = await fetchHeroesByOwnerAndProfessionChain(myAddress, 'mining');

console.log(heroes);

Note: There is no per-profession filter on the blockchain, all of the address' heroes will be fetched and filter at runtime.

heroToString(hero, params)

Renders the normalized hero object into a string representation.

• hero {Object} The hero to render.
• params {Object=} Optionally, define some parameters for the rendering:
  • params.cli {boolean} Set to true to get a CLI rendering.
  • params.showActivePassive {boolean} Show active passive genes.
  • params.showStats {boolean} Show hero stats.
  • params.showParents {boolean} Show hero's parents.
  • params.showSale {boolean} Show hero sales information.
  • params.showQuest {boolean} Show hero quest information.
  • params.short {boolean} Short version.
• Returns {string} The string representation of the hero.

const { heroToString, getHeroesChain } = require('@thanpolas/dfk-hero');

const [hero] = await getHeroesChain([10000]);
const heroStr = await heroToString(hero, { cli: true });

console.log(heroStr);

getSalesData(heroId)

Queries blockchain and returns auction (sales) data of hero.

• heroId {string|number} The hero's id.
• Returns {Promise<Object>} A Promise with an object of the sales data.

const { getSalesData } = require('@thanpolas/dfk-hero');

const salesData = await getSalesData(10000);

console.log(salesData);
// {
//       onSale: false,
//       auctionId: null,
//       seller: '',
//       startingPrice: 0,
//       endingPrice: 0,
//       duration: 0,
//       startedAt: 0,
// };

calculateRemainingStamina(hero)

Calculates and returns the remaining stamina of the hero.

• hero {Object} The normalized hero object.
• Returns {number} Remaining stamina.

const {
    calculateRemainingStamina,
    getHeroesChain,
} = require('@thanpolas/dfk-hero');

const [hero] = await getHeroesChain([10000]);
const heroStamina = await calculateRemainingStamina(hero);

console.log(heroStamina);
// 20

decodeStatGenes(statGenes)

Decodes the raw stat genes string.

• statGenes {string} The raw stat genes string.
• Returns {Object} The decoded stat genes as per the example bellow.

const statGenes =
    '55595053337262517174437940546058771473513094722680050621928661284030532';

const decodedStatGenes = decodeStatGenes(statGenes);

console.log(decodedStatGenes);
// {
//   class: 'thief',
//   subClass: 'wizard',
//   profession: 'gardening',
//   passive1: 'Basic1',
//   passive2: 'Basic2',
//   active1: 'Basic3',
//   active2: 'Basic4',
//   statBoost1: 'INT',
//   statBoost2: 'LCK',
//   statsUnknown1: 0,
//   element: 'fire',
//   statsUnknown2: 4
// }

decodeVisualGenes(visualGenes)

Decodes the raw visuals genes string.

• visualGenes {string} The raw visual genes string.
• Returns {Object} The decoded visual genes as per the example bellow.

const visualGenes =
    '170877259497388213840353281232231169976585066888929467746175634464967719';

const decodedVisualGenes = decodeStatGenes(visualGenes);

console.log(decodedVisualGenes);

// {
//   gender: 'female',
//   headAppendage: 1,
//   backAppendage: 6,
//   background: 'plains',
//   hairStyle: 1,
//   hairColor: 'd7bc65',
//   visualUnknown1: 0,
//   eyeColor: '2494a2',
//   skinColor: 'e6a861',
//   appendageColor: 'a0304d',
//   backAppendageColor: '830e18',
//   visualUnknown2: 7
// }

decodeRecessiveGeneAndNormalize(statGenesRaw)

Decodes the raw stat genes to produce recessive genes.

• statGenes {string|bigint} The raw stat genes string or bigint number.
• Returns {Object} The decoded stat genes as per the example bellow.

const statGenes =
    '119067243983457416993287681075686535166558725967282153752039019969001550';

const recessiveGenes = decodeStatGenes(statGenes);

console.log(recessiveGenes);
// {
//     mainClassGenes: ['pirate','warrior','wizard','thief'],
//     subClassGenes: ['warrior', 'pirate', 'wizard', 'monk'],
//     professionGenes: ['mining','gardening','mining','foraging'],
// }

getProfileByAddress(address)

Will query the blockchain, profile contract, for the member data that belong to the provided address.

• address {string} The address to query by, accepts both checksum and lowercased addresses.
• Returns {Promise<Object|null>} Will return a normalized response or null if not found.

const { getProfileByAddress } = require('@thanpolas/dfk-hero');

const profile = await getProfileByAddress(
    '0x67221b267cee49427bAa0974ceac988682192977',
);

console.log(profile);
//   {
//     id: 0,
//     owner: '0x67221b267cee49427baa0974ceac988682192977',
//     name: 'Degen Heroes',
//     created: new Date('2022-02-11T15:00:57.000Z'),
//     picId: 0,
//     heroId: 1,
//     points: 0,
//   }

Hero Data Object

Click here to expand the full Hero Data Object.

const hero = {
    rawHero: { /** Raw hero object as fetched from blockchain **/ },
    source: 'chain',
    id: 59760,
    ownerId: 19192,
    ownerName: 'miamiblue',
    ownerAddress: '0x6e9426c100dec5abc50bebe309cd85d304209096',
    mainClass: 'warrior',
    subClass: 'archer',
    profession: 'gardening',
    generation: 1,
    summons: 7,
    maxSummons: 10,
    statBoost1: 'LCK',
    statBoost2: 'DEX',
    active1: 'Basic8',
    active2: 'Basic3',
    passive1: 'Basic6',
    passive2: 'Basic4',
    rarity: 0,
    rarityStr: 'Common',
    mining: 0.5,
    gardening: 0,
    foraging: 0.7,
    fishing: 1.1,
    shiny: false,
    xp: 1298,
    level: 1,
    statGenes: {
        class: 'warrior',
        subClass: 'archer',
        profession: 'gardening',
        passive1: 'Basic6',
        passive2: 'Basic4',
        active1: 'Basic8',
        active2: 'Basic3',
        statBoost1: 'LCK',
        statBoost2: 'DEX',
        statsUnknown1: 0,
        element: 'lightning',
        statsUnknown2: undefined
    },
    visualGenes: {
        gender: 'male',
        headAppendage: 5,
        backAppendage: 5,
        background: 'mountains',
        hairStyle: 5,
        hairColor: '62a7e6',
        visualUnknown1: 5,
        eyeColor: 'bb3f55',
        skinColor: '985e1c',
        appendageColor: '566f7d',
        backAppendageColor: '566f7d',
        visualUnknown2: 0
    },
    statGenesRaw: '112261588165465148833973414848613658505090605198079167959458376446967944',
    visualGenesRaw: '167531060423278867008632326821039556379772927070476330103731967115858144',
    summonedTime: 2021-12-07T23:03:23.000Z,
    nextSummonTime: 2021-12-21T23:09:05.000Z,
    summonerId: 83,
    assistantId: 747,
    staminaFullAt: 2022-01-17T17:02:16.000Z,
    hpFullAt: 1970-01-01T00:00:00.000Z,
    mpFullAt: 1970-01-01T00:00:00.000Z,
    currentQuest: '0x0000000000000000000000000000000000000000',
    sp: 0,
    status: 0,
    intelligence: 5,
    luck: 9,
    vitality: 9,
    dexterity: 8,
    strength: 11,
    wisdom: 5,
    agility: 7,
    endurance: 8,
    statsSum: 62,
    hp: 150,
    mp: 25,
    stamina: 25,
    onSale: true,
    auctionId: 611485,
    seller: '0x6e9426c100Dec5AbC50bEbe309Cd85d304209096',
    startingPrice: 45,
    endingPrice: 45,
    startingPriceFormatted: '45',
    endingPriceFormatted: '45',
    duration: 60,
    startedAt: 2022-01-26T15:19:26.000Z,
    summonCost: 30,
    classTier: 'basic',
    summonMinTears: 10,
    summonMaxTears: 10,
    currentStamina: 25,
    currentRank: 14,
    estJewelPerTick: 0.26188,
    estJewelPer100Ticks: 26.1875,
    mainClassGenes: [ 'warrior', 'thief', 'knight', 'thief' ],
    subClassGenes: [ 'archer', 'warrior', 'knight', 'pirate' ],
    professionGenes: [ 'gardening', 'gardening', 'gardening', 'gardening' ]
}

Maintenance and Contributing

Update Node Version

When a new node version is available you need to updated it in the following:

• /package.json
• /.nvmrc
• /.circleci/config.yml

Releasing

1. Update the changelog bellow ("Release History").
2. Ensure you are on master and your repository is clean.
3. Type: npm run release for patch version jump.
   • npm run release:minor for minor version jump.
   • npm run release:major for major major jump.

Release History

• v0.3.0, 19/Mar/2022
  • Implemented and exported getProfileByAddress() function.
  • Fixed a minor issue on profile propagation when profile not found on hero query.
• v0.2.2, 15/Mar/2022
  • Export decodeStatGenes() and decodeVisualGenes() functions.
  • Implement and export decodeRecessiveGeneAndNormalize() function.
  • Will not break if hero belongs to an account that does not have a profile in-game.
  • Fixed and tweaked tests.
• v0.2.1, 03/Mar/2022
  • Uses profile V2.
• v0.2.0, 07/Feb/2022
  • Exported new functions (getSalesData(), calculateRemainingStamina()).
  • Will no longer log user fetching failure retries, will only log final failure.
• v0.1.1, 02/Feb/2022
  • Fixes weird require issue with React Applications and a date-fns function.
  • Fixes bug in the fetchHeroesByOwnerChain() function.
• v0.1.0, 26/Jan/2022
  • Big Bang

License

Copyright © Thanos Polychronakis and Authors, Licensed under ISC.

Tip Jar

thanpolas.eth - 0x67221b267cee49427bAa0974ceac988682192977