This is the SDK for the Humanode Biomapper - a biometrics-based sybil-resistance utility for EVM smart contracts.
To learn more about the Humanode Biomapper itself (and not this SDK) see the docs.
Contract Addresses
Find the up-to-date contract addresses here.
Implementation Table
| Contract | Implemented Interfaces |
|---|---|
Biomapper | IGenerationChangeEvents, IProveUniquenessEvents |
BiomapperLog | IBiomapperLogRead, IBiomapperLogAddressesPerGenerationEnumerator |
BridgedBiomapper | IBridgedBiomapperRead, IBridgeBiomappingEvents |
Installation
With NPM/Yarn
Install the packages:
npm install --save @biomapper-sdk/core @biomapper-sdk/libraries @biomapper-sdk/events
or with yarn:
yarn add @biomapper-sdk/core @biomapper-sdk/libraries @biomapper-sdk/events
Import the dependencies from the @biomapper-sdk like this:
import {IBiomapperLogRead} from "@biomapper-sdk/core/IBiomapperLogRead.sol";
import {IBridgedBiomapperRead} from "@biomapper-sdk/core/IBridgedBiomapperRead.sol";
import {IBiomapperLogAddressesPerGenerationEnumerator} from "@biomapper-sdk/core/IBiomapperLogAddressesPerGenerationEnumerator.sol";
import {BiomapperLogLib} from "@biomapper-sdk/libraries/BiomapperLogLib.sol";
import {BridgedBiomapperLib} from "@biomapper-sdk/libraries/BridgedBiomapperLib.sol";
With Foundry
Install the dependency:
forge install humanode-network/biomapper-sdk
Import the dependencies from biomapper-sdk like this:
import {IBiomapperLogRead} from "biomapper-sdk/core/IBiomapperLogRead.sol";
import {IBridgedBiomapperRead} from "biomapper-sdk/core/IBridgedBiomapperRead.sol";
import {IBiomapperLogAddressesPerGenerationEnumerator} from "biomapper-sdk/core/IBiomapperLogAddressesPerGenerationEnumerator.sol";
import {BiomapperLogLib} from "biomapper-sdk/libraries/BiomapperLogLib.sol";
import {BridgedBiomapperLib} from "biomapper-sdk/libraries/BridgedBiomapperLib.sol";
Usage
See the usage directory for the simple usage examples, and
the examples directory for a more complete use cases
demonstration.
IBiomapperLogAddressesPerGenerationEnumerator
Functions
listAddressesPerGeneration
Retrieves all biomapped accounts within a specified generation.
function listAddressesPerGeneration(uint256 generationPtr, address cursor, uint256 maxPageSize)
external
view
returns (address nextCursor, address[] memory biomappedAccounts);
Parameters
| Name | Type | Description |
|---|---|---|
generationPtr | uint256 | The block number marking the start of the generation to get the list of biomapped accounts. |
cursor | address | The starting index of the page. For the first request, set cursor to address(0). |
maxPageSize | uint256 | The maximum number of elements to return in this call (also soft-capped in the contract). |
Returns
| Name | Type | Description |
|---|---|---|
nextCursor | address | The starting index for the next page of results. |
biomappedAccounts | address[] | An array of addresses that were biomapped within a specified generation. Notes: - For the first request, set cursor to address(0) to start from the beginning of the dataset. - If nextCursor is address(0), all available elements have been retrieved, indicating the end of the dataset. - There is a soft cap on the max page size that is implementation-dependent. |
IBiomapperLogRead
View historical biomapping state for a given account, and overall generation changes.
Examples
See the BiomapperLogExamples.
Interface for the BiomapperLog contract.
Functions
biomappingsHead
Returns the most recent biomapping pointer for a given account address.
function biomappingsHead(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the most recent biomap occurred, or 0 if the account was never biomapped. |
biomappingsTail
Returns the oldest biomapping pointer for a given account address.
function biomappingsTail(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest biomap occurred, or 0 if the account was never biomapped. |
biomappingsListItem
Returns the Biomapping struct for a given biomapping pointer and account address.
function biomappingsListItem(address account, uint256 ptr) external view returns (Biomapping memory);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
ptr | uint256 | The biomapping pointer of the requested biomapping. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | Biomapping | The Biomapping structure. |
generationBiomapping
Returns the biomapping pointer for a given account address and generation pointer.
function generationBiomapping(address account, uint256 generationPtr) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
generationPtr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the requested user was biomapped in the requested generation, or 0 if there was no biomapping. |
generationsHead
Returns the block number in which the current generation began.
function generationsHead() external view returns (uint256);
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the current generation began, 0 if no generations initialized. |
generationsTail
Returns the block number in which the oldest generation began.
function generationsTail() external view returns (uint256);
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest generation began, 0 if no generations initialized. |
generationsListItem
Returns the generation struct for a given generation pointer.
function generationsListItem(uint256 ptr) external view returns (Generation memory);
Parameters
| Name | Type | Description |
|---|---|---|
ptr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | Generation | The Generation structure. |
Structs
Generation
Structure representing a biomapper generation as an element of a doubly linked list.
Pointer of Generation is a number of block that contains a 'generation change' transaction.
Fields
| Name | Type | Description |
|---|---|---|
| generation | bytes32 | A salted hash of some deployment data. Deprecated, do not use. |
| prevPtr | uint256 | Block number of the previous generation. 0 for the oldest generation. |
| nextPtr | uint256 | Block number of the next generation. 0 for the current generation. |
struct Generation {
bytes32 generation;
uint256 prevPtr;
uint256 nextPtr;
}
Biomapping
Structure representing a biomapping as an element of a doubly linked list.
Pointer of Biomapping is a number of block that contains a 'prove uniqueness' transaction.
Fields
| Name | Type | Description |
|---|---|---|
| generationPtr | uint256 | Pointer to the generation that has this biomapping. |
| prevPtr | uint256 | Block number of the previous biomapping. 0 for the oldest biomapping. |
| nextPtr | uint256 | Block number of the next biomapping. 0 for the current biomapping. |
struct Biomapping {
uint256 generationPtr;
uint256 prevPtr;
uint256 nextPtr;
}
IBridgedBiomapperRead
View bridged historical biomapping state for a given account,
and overall generation changes.
A bridging tx is a transaction included in a block at the bridged chain that imports data from Humanode chain.
Bridging tx point corresponds to a number of the block at the bridged chain in which a bridging tx is included.
A bridging tx contains a set of generations and potentially biomappings at Humanode chain.
The generations set can contain up to one generation that is "being bridged" and zero or more historical generations.
A historical generation is a generation that is included in the bridging tx while not being the latest generation at Humanode chain.
A historical generation does not create corresponding GenerationBridgingTxPoint or BiomappingBridgingTxPoint,
however it does create the Generation and (if needed) Biomapping.
Interface for the BridgedBiomapper contract.
Functions
generationsHead
Returns the block number at Humanode chain in which the current generation began.
function generationsHead() external view returns (uint256);
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the current generation began, 0 if no generations initialized. |
generationsTail
Returns the block number at Humanode chain in which the oldest generation began.
function generationsTail() external view returns (uint256);
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest generation began, 0 if no generations initialized. |
generationsListItem
Returns the generation struct for a given generation pointer.
function generationsListItem(uint256 ptr) external view returns (Generation memory);
Parameters
| Name | Type | Description |
|---|---|---|
ptr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | Generation | The Generation structure. |
generationsBridgingTxPointsHead
Returns the block number at bridged chain in which the current generation was bridged.
function generationsBridgingTxPointsHead() external view returns (uint256);
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the current generation bridged, 0 if no generations bridged. |
generationsBridgingTxPointsTail
Returns the block number at bridged chain in which the oldest generation was bridged.
function generationsBridgingTxPointsTail() external view returns (uint256);
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest generation bridged, 0 if no generations bridged. |
generationsBridgingTxPointsListItem
Returns the generation bridging tx point struct for a given pointer.
function generationsBridgingTxPointsListItem(uint256 ptr) external view returns (GenerationBridgingTxPoint memory);
Parameters
| Name | Type | Description |
|---|---|---|
ptr | uint256 | The pointer of the requested bridging tx point. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | GenerationBridgingTxPoint | The GenerationBridgingTxPoint structure. |
biomappingsHead
Returns the most recent biomapping pointer for a given account address.
function biomappingsHead(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the most recent biomap occurred, or 0 if the account was never bridged. |
biomappingsTail
Returns the oldest biomapping pointer for a given account address.
function biomappingsTail(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest biomap occurred, or 0 if the account was never bridged. |
biomappingsListItem
Returns the Biomapping struct for a given biomapping pointer and account address.
function biomappingsListItem(address account, uint256 ptr) external view returns (Biomapping memory);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
ptr | uint256 | The biomapping pointer of the requested biomapping. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | Biomapping | The Biomapping structure. |
biomappingsBridgingTxPointsHead
Returns the most recent biomapping bridging tx point for a given account address.
function biomappingsBridgingTxPointsHead(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the most recent biomap was bridged, or 0 if the account was never bridged. |
biomappingsBridgingTxPointsTail
Returns the oldest biomapping bridging tx point for a given account address.
function biomappingsBridgingTxPointsTail(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest biomap was bridged, or 0 if the account was never bridged. |
biomappingsBridgingTxPointsListItem
Returns the BiomappingBridgingTxPoint struct for a given pointer and account address.
function biomappingsBridgingTxPointsListItem(address account, uint256 ptr)
external
view
returns (BiomappingBridgingTxPoint memory);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
ptr | uint256 | The pointer of the requested bridging tx point. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | BiomappingBridgingTxPoint | The BiomappingBridgingTxPoint structure. |
lookupBiomappingPtr
Returns the biomapping pointer for a given account address and generation pointer.
Returns non-zero if the account is known to be biomapped in a given generation.
function lookupBiomappingPtr(address account, uint256 generationPtr) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
generationPtr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the requested user was biomapped in the requested generation, or 0 if there was no biomapping. Note: can return zero if biomapped at Humanode chain but the information about it is not bridged yet. |
lookupBiomappingBridgedTxPointPtr
Returns the BiomappingBridgingTxPoint ptr for a given account address and generation bridged tx point.
Returns non-zero if the account biomapping was bridged in a given generation.
function lookupBiomappingBridgedTxPointPtr(address account, uint256 generationBridgedTxPointPtr)
external
view
returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
generationBridgedTxPointPtr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the requested user was biomapped in the requested generation, or 0 if there was no biomapping. Note: there is a possibility that the biomapping was bridged as part of a bridge tx where the generation it belonged to is a historical generation, in which case the Biomapping will exist, but the BiomappingBridgedTxPoint will be absent. |
Structs
Generation
Describes a generation on Humanode chain.
*Stored in a map where key is a block number at Humanode chain.
Allows navigating through generations via prevPtr and nextPtr.
Allows locating GenerationBridgingTxPoint via generationBridgingTxPointPtr.
A new key is populated by the bridging tx for the generation being bridged and
for each historical generations that occurred prior to the generation being bridged
if the corresponding Generation is not present at the bridged chain.
For historical generations generationBridgingTxPointPtr will be zero.
Fields
| Name | Type | Description |
|---|---|---|
| generationBridgingTxPointPtr | uint256 | The block number at the bridged chain when this generation was ported from Humanode chain to this chain. Zero if this generation was bridged as a non-target generation (historical) in the bridging tx. |
| prevPtr | uint256 | The block number at Humanode chain that points to the previous generation. Zero if this generation is the oldest generation at Humanode chain. |
| nextPtr | uint256 | The block number at Humanode chain that points to the next generation. Zero if this generation is the newest known (bridged) generation at Humanode chain. |
struct Generation {
uint256 generationBridgingTxPointPtr;
uint256 prevPtr;
uint256 nextPtr;
}
GenerationBridgingTxPoint
Describes a point in time (block number at the bridged chain) when a generation was bridged from Humanode chain.
*Stored in a map where key is a block number at the bridged chain.
Allows navigating through generation bridging tx points via prevPtr and nextPtr.
Allows locating Generation via generationPtr.
A new key is populated by the bridging tx when it is determined that the
Generation being bridged (i.e. non-historical) is not present at the bridged chain.
Fields
| Name | Type | Description |
|---|---|---|
| generationPtr | uint256 | The block number at Humanode chain corresponding to when the generation was initialized. Never zero. |
| prevPtr | uint256 | The block number at the bridged chain that points to the previous generation bridging tx point. Zero if this generation bridging tx point is the oldest point at the bridged chain. |
| nextPtr | uint256 | The block number at the bridged chain that points to the next generation bridging tx point. Zero if this generation bridging tx point is the newest point at the bridged chain. |
struct GenerationBridgingTxPoint {
uint256 generationPtr;
uint256 prevPtr;
uint256 nextPtr;
}
Biomapping
Describes a biomapping on Humanode chain.
*Stored in a double map where the keys are an account and a block number at Humanode chain.
Allows navigating through biomappings within a given account via prevPtr and nextPtr.
Allows locating Generation via generationPtr.
Allows locating BiomappingBridgingTxPoint via biomappingBridgingTxPointPtr.
A new key is populated by the bridging tx for the generation being bridged and
for each historical generations that occurred prior to the generation being bridged
if the bridging tx indicates that the account in the bridging tx has the biomapping in a given generation
and the corresponding Biomapping is not present at the bridged chain.
Fields
| Name | Type | Description |
|---|---|---|
| generationPtr | uint256 | The block number at Humanode chain that corresponds to generation in which biomapping has occurred. Never zero. |
| biomappingBridgingTxPointPtr | uint256 | The block number at the bridged chain when biomapping was ported from Humanode chain to this chain. Zero if this biomapping corresponds to a generation than was bridged as a non-target generation (historical) in the bridging tx. |
| prevPtr | uint256 | The block number at Humanode chain that points to the previous biomapping for the corresponding account. Zero if this biomapping is the oldest biomapping for the corresponding account at Humanode chain. |
| nextPtr | uint256 | The block number at Humanode chain that points to the next biomapping for the corresponding account. Zero if this biomapping is the newest known (bridged) biomapping for the corresponding account at Humanode chain. |
struct Biomapping {
uint256 generationPtr;
uint256 biomappingBridgingTxPointPtr;
uint256 prevPtr;
uint256 nextPtr;
}
BiomappingBridgingTxPoint
Describes a point in time (block number at the bridged chain) when a biomapping was bridged from Humanode chain.
*Stored in a double map where the keys are an account and a block number at the bridged chain.
Allows navigating through biomapping bridging tx points within a given account via prevPtr and nextPtr.
Allows locating GenerationBridgingTxPoint via generationBridgingTxPointPtr.
Allows locating Biomapping via biomappingPtr.
A new key is populated by the bridging tx when a Biomapping is present for a given account in a non-historical generation.
Fields
| Name | Type | Description |
|---|---|---|
| generationBridgingTxPointPtr | uint256 | The block number at the bridged chain that corresponds to generation bridging tx point when this biomapping was bridged. Never zero. |
| biomappingPtr | uint256 | The block number at Humanode chain corresponding to when the biomap happened. Never zero. |
| prevPtr | uint256 | The block number at the bridged chain that points to the previous biomapping bridging tx point. Zero if this biomapping bridging tx point is the oldest point at the bridged chain. |
| nextPtr | uint256 | The block number at the bridged chain that points to the next biomapping bridging tx point. Zero if this biomapping bridging tx point is the newest point at the bridged chain. |
struct BiomappingBridgingTxPoint {
uint256 generationBridgingTxPointPtr;
uint256 biomappingPtr;
uint256 prevPtr;
uint256 nextPtr;
}
IBridgeBiomappingEvents
Interface for events related to bridging biomappings.
Interface for the BridgedBiomapper contract.
Events
NewBridgedBiomapping
New biomapping was bridged.
event NewBridgedBiomapping(
address account,
uint256 biomappingPtr,
uint256 generationPtr,
uint256 referenceHumanodeBlockNumber,
bytes32 referenceHumanodeBlockHash
);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address that bridged their biomap. |
biomappingPtr | uint256 | The block number on the Humanode chain when the biomapping event occurred. |
generationPtr | uint256 | The block number representing the generation to which this biomapping belongs. |
referenceHumanodeBlockNumber | uint256 | The block number on the Humanode chain when data was taken. |
referenceHumanodeBlockHash | bytes32 | The block hash on the Humanode chain when data was taken. |
NewBridgedGeneration
New generation was bridged.
event NewBridgedGeneration(
uint256 generationPtr, uint256 referenceHumanodeBlockNumber, bytes32 referenceHumanodeBlockHash
);
Parameters
| Name | Type | Description |
|---|---|---|
generationPtr | uint256 | The block number on the Humanode chain when the generation started. |
referenceHumanodeBlockNumber | uint256 | The block number on the Humanode chain when data was taken. |
referenceHumanodeBlockHash | bytes32 | The block hash on the Humanode chain when data was taken. |
IGenerationChangeEvents
Interface for events related to the biomapper generation changes.
Exhaustiveness
Contract may emit other events not covered by this interface.
Interface for the Biomapper contract.
Events
GenerationChanged
Emitted when the biomapper generation has been changed.
event GenerationChanged();
IProveUniquenessEvents
Interface for events related to proving uniqueness.
Exhaustiveness
Contract may emit other events not covered by this interface.
Interface for the Biomapper contract.
Events
NewBiomapping
Emitted when uniqueness is successfully proven and a new biomapping is added.
event NewBiomapping(address account, bytes32 biotoken);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the account for which uniqueness is proven. |
biotoken | bytes32 | The biotoken associated with the account. |
BiomapperLogLib
A utility library for the BiomapperLog contract.
Functions
isUniqueInLastGeneration
Determines the uniqueness status of a given address in the current biomapper generation.
This call does not guarantee uniqueness across generations, meaning the same person can pass this check more than once (perform a Sybil-attack): with same biometrics but different account after each generation change. Ensure you are fully understand the implications of generations and the security guarantees they provide, and consider explicitly scoping your uniqueness check by a particular generation.
function isUniqueInLastGeneration(IBiomapperLogRead biomapperLog, address who) external view returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
biomapperLog | IBiomapperLogRead | The BiomapperLog contract. |
who | address | The address to check for uniqueness. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | A boolean value indicating whether the address is biomapped (true) or not (false). |
countBiomappedBlocks
Counts the number of blocks a user has been biomapped for.
function countBiomappedBlocks(IBiomapperLogRead biomapperLog, address who, uint256 fromBlock)
public
view
returns (uint256 blocks);
Parameters
| Name | Type | Description |
|---|---|---|
biomapperLog | IBiomapperLogRead | The BiomapperLog contract. |
who | address | The address to count. |
fromBlock | uint256 | The starting block number. |
Returns
| Name | Type | Description |
|---|---|---|
blocks | uint256 | The number of blocks the user has been biomapped for. |
firstBiomappedGeneration
Finds the first generation a user was biomapped in.
function firstBiomappedGeneration(IBiomapperLogRead biomapperLog, address who) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
biomapperLog | IBiomapperLogRead | The BiomapperLog contract. |
who | address | The address to check. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number of the first biomapping for the user, or 0 if never biomapped. |
firstSequentialBiomappedGeneration
Finds the block number of the oldest sequential biomapping for a user.
function firstSequentialBiomappedGeneration(IBiomapperLogRead biomapperLog, address who)
external
view
returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
biomapperLog | IBiomapperLogRead | The BiomapperLog contract. |
who | address | The address of the user to check. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number of the oldest sequential biomapping for the user, or 0 if not biomapped in the current generation. |
BridgedBiomapperLib
A utility library for the BridgedBiomapper contract.
Functions
isUniqueInLastKnownGeneration
Determines the uniqueness status of a given address in the last known biomapper generation.
This call does not guarantee uniqueness across generations, meaning the same person can pass this check more than once (perform a Sybil-attack): with same biometrics but different account after each generation change. Ensure you are fully understand the implications of generations and the security guarantees they provide, and consider explicitly scoping your uniqueness check by a particular generation.
function isUniqueInLastKnownGeneration(IBridgedBiomapperRead bridgedBiomapperRead, address who)
external
view
returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
bridgedBiomapperRead | IBridgedBiomapperRead | The bridgedBiomapperRead contract. |
who | address | The address to check for uniqueness. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | A boolean value indicating whether the address is biomapped (true) or not (false). |
countBiomappedBlocks
Counts the number of blocks a user has been biomapped for.
function countBiomappedBlocks(IBridgedBiomapperRead bridgedBiomapperRead, address who, uint256 fromBlock)
public
view
returns (uint256 blocks);
Parameters
| Name | Type | Description |
|---|---|---|
bridgedBiomapperRead | IBridgedBiomapperRead | The IBridgedBiomapperRead contract. |
who | address | The address to count. |
fromBlock | uint256 | The starting block number. |
Returns
| Name | Type | Description |
|---|---|---|
blocks | uint256 | The number of blocks the user has been biomapped for. |
firstBiomappedGeneration
Finds the first generation a user was biomapped in.
function firstBiomappedGeneration(IBridgedBiomapperRead bridgedBiomapperRead, address who)
external
view
returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
bridgedBiomapperRead | IBridgedBiomapperRead | The IBridgedBiomapperRead contract. |
who | address | The address to check. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number of the first biomapping for the user, or 0 if never biomapped. |
IMockBiomapperControl
Mock controls for the MockBiomapper.
Interface for the MockBiomapper contract.
Functions
initGeneration
Initializes a new generation.
function initGeneration() external;
biomap
Creates a new biomapping for the specified account.
function biomap(address account, bytes32 biotoken) external;
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the account to biomap. |
biotoken | bytes32 | The biotoken to map to the account. |
IMockBiomapperLogWrite
Mock access for writing biomapper log.
Interface for the MockBiomapperLock contract.
Functions
initGeneration
Initializes a new generation.
function initGeneration(bytes32 generation) external;
Parameters
| Name | Type | Description |
|---|---|---|
generation | bytes32 | Arbitrarty bytes to represent the generation. |
biomap
Creates a new biomapping for the specified account.
function biomap(address account) external;
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the account to biomap. |
IMockBridgedBiomapperControl
Mock controls for the MockBridgedBiomapper.
Interface for the MockBridgedBiomapper contract.
Functions
updateBiomappings
Bridge the generations and biomappings.
function updateBiomappings(BiomappingData[] memory biomappingsData, address account) external;
Parameters
| Name | Type | Description |
|---|---|---|
biomappingsData | BiomappingData[] | The info about biomapping events. |
account | address | The address of the requested account. |
addTestData
A quick and easy way to add test data to the mock contract, as well as an example of how to add new data.
The test data represents the history of 2 accounts across 6 generations.
This function can be executed up to 4 times in different blocks to add test data.
function addTestData() external;
Structs
BiomappingData
The info about one biomapping event.
Fields
| Name | Type | Description |
|---|---|---|
| generationPtr | uint256 | The generation, Humanode chain block number. |
| biomappingPtr | uint256 | The biomapping, Humanode chain block number. |
struct BiomappingData {
uint256 generationPtr;
uint256 biomappingPtr;
}
MockBiomapper
Inherits: IGenerationChangeEvents, IProveUniquenessEvents, IMockBiomapperControl
Mock contract implementing Biomapper contract interfaces.
Use this contract is your tests and development stages to emulate
the behaviour of the Biomapper contract.
When created, the MockBiomapper contract is empty.
Use the IMockBiomapperControl interface to drive the mock state
as needed. Use getMockBiomapperLogAddress to obtain the address of
the corresponding MockBiomapperLog contract.
State Variables
_unique
Mapping account => true for quick access to unique accounts.
mapping(uint256 => mapping(address => bool)) private _unique;
_biotokens
Mapping biotoken => account for storing biotokens.
mapping(uint256 => mapping(bytes32 => address)) private _biotokens;
_currentGeneration
uint256 private _currentGeneration;
_MOCK_BIOMAPPER_LOG
MockBiomapperLog contract instance for logging biomapper events.
MockBiomapperLog private immutable _MOCK_BIOMAPPER_LOG;
Functions
constructor
constructor();
getMockBiomapperLogAddress
Returns the address of the MockBiomapperLog contract instance.
function getMockBiomapperLogAddress() public view returns (address mockBiomapperLogAddress);
initGeneration
Initializes a new generation.
function initGeneration() public;
biomap
Creates a new biomapping for the specified account.
function biomap(address account, bytes32 biotoken) external;
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the account to biomap. |
biotoken | bytes32 | The biotoken to map to the account. |
Errors
BiomappingAlreadyExists
Sender account is already mapped to a given biotoken. No further actions required.
error BiomappingAlreadyExists();
AccountHasAnotherBiotokenAttached
Sender account is already mapped to another biotoken. User can try again using another account.
error AccountHasAnotherBiotokenAttached();
BiotokenAlreadyMappedToAnotherAccount
Given biotoken is already mapped to anotherAccount.
User can use another biotoken with this account.
error BiotokenAlreadyMappedToAnotherAccount(address anotherAccount);
MockBiomapperLog
Inherits: IBiomapperLogRead, IMockBiomapperLogWrite
Mock contract implementing BiomapperLog contract interfaces.
It is constructed as part of the MockBiomapper, but it is also
possible to construct and use the MockBiomapperLog independently.
When used in conjunction with MockBiomapper, the interactions with
the corresponding MockBiomapper will drive the MockBiomapperLog state
accordingly, so there is no need to separately control
the MockBiomapperLog state.
When deployed independently, use the IMockBiomapperLogWrite
interface to drive the state.
State Variables
generationsHead
uint256 public generationsHead;
generationsTail
uint256 public generationsTail;
generationsList
mapping(uint256 => Generation) public generationsList;
biomappingsHeads
mapping(address => uint256) public biomappingsHeads;
biomappingsTails
mapping(address => uint256) public biomappingsTails;
biomappingsLists
mapping(address => mapping(uint256 => Biomapping)) public biomappingsLists;
generationBiomappings
mapping(address => mapping(uint256 => uint256)) public generationBiomappings;
Functions
biomappingsHead
Returns the most recent biomapping pointer for a given account address.
function biomappingsHead(address account) external view override returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the most recent biomap occurred, or 0 if the account was never biomapped. |
biomappingsTail
Returns the oldest biomapping pointer for a given account address.
function biomappingsTail(address account) external view override returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest biomap occurred, or 0 if the account was never biomapped. |
biomappingsListItem
Returns the {Biomapping} struct for a given biomapping pointer and account address.
function biomappingsListItem(address account, uint256 ptr) external view override returns (Biomapping memory);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
ptr | uint256 | The biomapping pointer of the requested biomapping. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | Biomapping | The {Biomapping} structure. |
generationsListItem
Returns the generation struct for a given generation pointer.
function generationsListItem(uint256 ptr) external view override returns (Generation memory);
Parameters
| Name | Type | Description |
|---|---|---|
ptr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | Generation | The {Generation} structure. |
generationBiomapping
Returns the biomapping pointer for a given account address and generation pointer.
function generationBiomapping(address account, uint256 generationPtr) external view override returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
generationPtr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the requested user was biomapped in the requested generation, or 0 if there was no biomapping. |
initGeneration
Initializes a new generation.
function initGeneration(bytes32 generation) external;
Parameters
| Name | Type | Description |
|---|---|---|
generation | bytes32 | Arbitrarty bytes to represent the generation. |
biomap
Creates a new biomapping for the specified account.
function biomap(address account) external;
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the account to biomap. |
MockBridgedBiomapper
Inherits: IBridgedBiomapperRead, IBridgeBiomappingEvents, IMockBridgedBiomapperControl
State Variables
generationsHead
uint256 public generationsHead;
generationsTail
uint256 public generationsTail;
generationsList
mapping(uint256 => Generation) public generationsList;
generationsBridgingTxPointsHead
uint256 public generationsBridgingTxPointsHead;
generationsBridgingTxPointsTail
uint256 public generationsBridgingTxPointsTail;
generationBridgingTxPointsList
mapping(uint256 => GenerationBridgingTxPoint) public generationBridgingTxPointsList;
_biomappingsHeads
mapping(address => uint256) private _biomappingsHeads;
_biomappingsTails
mapping(address => uint256) private _biomappingsTails;
_biomappingsList
mapping(address => mapping(uint256 => Biomapping)) private _biomappingsList;
_biomappingPtrs
mapping(address => mapping(uint256 => uint256)) private _biomappingPtrs;
_biomappingBridgingTxPointsHeads
mapping(address => uint256) private _biomappingBridgingTxPointsHeads;
_biomappingBridgingTxPointsTails
mapping(address => uint256) private _biomappingBridgingTxPointsTails;
_biomappingBridgingTxPointsList
mapping(address => mapping(uint256 => BiomappingBridgingTxPoint)) private _biomappingBridgingTxPointsList;
_biomappingBridgedTxPointPtrs
mapping(address => mapping(uint256 => uint256)) private _biomappingBridgedTxPointPtrs;
testCaseNumber
uint8 public testCaseNumber;
Functions
addTestData
A quick and easy way to add test data to the mock contract, as well as an example of how to add new data.
This function can be executed up to 4 times in different blocks to add test data.
function addTestData() external;
generationsListItem
Returns the generation struct for a given generation pointer.
function generationsListItem(uint256 ptr) external view returns (Generation memory);
Parameters
| Name | Type | Description |
|---|---|---|
ptr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | Generation | The {Generation} structure. |
generationsBridgingTxPointsListItem
Returns the generation bridging tx point struct for a given pointer.
function generationsBridgingTxPointsListItem(uint256 ptr) external view returns (GenerationBridgingTxPoint memory);
Parameters
| Name | Type | Description |
|---|---|---|
ptr | uint256 | The pointer of the requested bridging tx point. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | GenerationBridgingTxPoint | The {GenerationBridgingTxPoint} structure. |
biomappingsHead
Returns the most recent biomapping pointer for a given account address.
function biomappingsHead(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the most recent biomap occurred, or 0 if the account was never bridged. |
biomappingsTail
Returns the oldest biomapping pointer for a given account address.
function biomappingsTail(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest biomap occurred, or 0 if the account was never bridged. |
biomappingsListItem
Returns the {Biomapping} struct for a given biomapping pointer and account address.
function biomappingsListItem(address account, uint256 ptr) external view returns (Biomapping memory);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
ptr | uint256 | The biomapping pointer of the requested biomapping. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | Biomapping | The {Biomapping} structure. |
biomappingsBridgingTxPointsHead
Returns the most recent biomapping bridging tx point for a given account address.
function biomappingsBridgingTxPointsHead(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the most recent biomap was bridged, or 0 if the account was never bridged. |
biomappingsBridgingTxPointsTail
Returns the oldest biomapping bridging tx point for a given account address.
function biomappingsBridgingTxPointsTail(address account) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the oldest biomap was bridged, or 0 if the account was never bridged. |
biomappingsBridgingTxPointsListItem
Returns the {BiomappingBridgingTxPoint} struct for a given pointer and account address.
function biomappingsBridgingTxPointsListItem(address account, uint256 ptr)
external
view
returns (BiomappingBridgingTxPoint memory);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
ptr | uint256 | The pointer of the requested bridging tx point. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | BiomappingBridgingTxPoint | The {BiomappingBridgingTxPoint} structure. |
lookupBiomappingPtr
Returns the biomapping pointer for a given account address and generation pointer.
Returns non-zero if the account is known to be biomapped in a given generation.
function lookupBiomappingPtr(address account, uint256 generationPtr) external view override returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
generationPtr | uint256 | The pointer of the requested generation. |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the requested user was biomapped in the requested generation, or 0 if there was no biomapping. Note: can return zero if biomapped at Humanode chain but the information about it is not bridged yet. |
lookupBiomappingBridgedTxPointPtr
Returns the {BiomappingBridgingTxPoint} ptr for a given account address and generation bridged tx point.
Returns non-zero if the account biomapping was bridged in a given generation.
function lookupBiomappingBridgedTxPointPtr(address account, uint256 generationPtr)
external
view
override
returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The address of the requested account. |
generationPtr | uint256 |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | The block number in which the requested user was biomapped in the requested generation, or 0 if there was no biomapping. Note: there is a possibility that the biomapping was bridged as part of a bridge tx where the generation it belonged to is a historical generation, in which case the {Biomapping} will exist, but the BiomappingBridgedTxPoint will be absent. |
updateBiomappings
Bridge the generations and biomappings.
function updateBiomappings(BiomappingData[] memory biomappingsData, address account) public;
Parameters
| Name | Type | Description |
|---|---|---|
biomappingsData | BiomappingData[] | The info about biomapping events. |
account | address | The address of the requested account. |
BiomapperLogExamples
Here are the usage examples for the BiomapperLog contract.
BiomapperLog exposes historical state of biomapping and generation
changes.
Note
If you are viewing this though the documentation, you should instead open the full source code of this file to see the contents of the functions.
Usage examples for the BiomapperLog contract.
State Variables
BIOMAPPER_LOG_CONTRACT_ADDRESS
Assume this is the address of the BiomapperLog contract.
You can find the actual address in the documentation.
address public immutable BIOMAPPER_LOG_CONTRACT_ADDRESS;
Functions
example1
A loop through all generations.
Go to the source code if you are viewing this though the documentation.
function example1() external view;
example2
Generations could also be searched from oldest to current.
Go to the source code if you are viewing this though the documentation.
function example2() external view;