Nutella Peanut-Butter Marshmallow

    TypeScript icon, indicating that this package has built-in type declarations

    0.0.9 • Public • Published

    Hypernet Protocol Contracts package


    • contracts: Subdirectory containing all Hypernet Protocol smart contract impelementations.
    • deployments: Subdirectory containing deployment artifacts for all chains in which the Hypernet Protocol has been deployed to.
    • scripts: Hardhat scripts for deploying the contract stack.
    • src: Typscript definitions for UI elements.
    • tasks: Hardhat task definitions for use with Hypernet Protocol contract deployments.
    • test: Hardhat unit tests for the Hypernet Protocol smart contracts.
    • hardhat.config.js: Configuration file for the Hardhat smart contract development framework.


    This package contains the Hypernet Protocol solidity contracts for the token, governance, and identity registries. The token is EIP20 compliant and is limited to a total supploy of 100,000,000 with 18 decimal places of precision. The governance contracts are based on OpenZeppelin's Governor library which is itself based on a reference implementation by Compound Finance. Given below is a sequence diagram for the proposal lifecycle.

    alt text

    This particular governance architecture has been adopted by a number of highly successful projects including Uniswap and has proven quite successful in practice at adopting beneficial proposals to protocol upgrades while preventing adversarial attacks.

    alt text

    The Hypernet Governance application is used for proposing and vetting (by the token holder community) new Non-Fungible Registries (NFRs), which are deployed through the registry factory contract, and updating various parameters in the protocol itself. The factory contract implements an upgradable beacon pattern for deploying new NFRs in a gas-efficient manner (~80% reduction in gas fees over naive implementation). Each new NFR stores its state in a proxy layer and function calls to that proxy layer are delegated to an implementation contract shared by all copies of the original beacon implementation. Since the reference implementation deployments are not intented to be used directly, the initializer pattern is used for setting parameters upon the creation of a new NFR.

    Non-Fungible Registries are an extension of the EIP721 non-fungible token standard and have several customizable functionalities. An NFR is can be deployed with or without the enumeration property and every entry is an ownable token that has a corresponding label (seperate from the tokenURI or tokenId) that is unique within that specific NFR. That is, two entries can have the same tokenURI, but they cannot have the same label. Labels fascilitate lookups more easily for applications in which the registry is used for identity or authenticity verification in which the tokenId may not be known a priori but the label is (for instance when label is a URL). Entries in an NFR are referred to, within the protocol, as Non-Fungible Identities (NFIs).

    Each NFR has a REGISTRAR_ROLE, which can register new identities, a REGISTRAR_ROLE_ADMIN which can add and remove addresses from the REGISTRAR_ROLE as well as update NFR parameters, and a DEFAULT_ADMIN_ROLE which can make modifications to which addresses have the REGISTRAR_ROLE and REGISTRAR_ROLE_ADMIN. Both of these roles are set up through the NFR constructor. Additionally, the REGISTRAR_ROLE and the owner of an NFI have the option to update the information stored in the tokenURI after registration unless allowStorageUpdate is set to false (which it is by default and can be updated by the REGISTRAR_ROLE). The same applies for the token label through the allowLabelChange flag (which is false by default). In some cases, it can be useful to dissallow the transfer of ownership of NFIs. This can be done if REGISTRAR_ROLE sets allowTransfers to false. In this case, the REGISTRAR_ROLE can still transfer an NFI on the owners behalf if the NFI owner gives approval to the REGISTRAR_ROLE through the approve function.

    Each NFR can augment its registration logic (as well as add novel functionality) through the use of external modules. A module is a stateless external contract which can be given the REGISTRAR_ROLE and thus extend an NFR's capability in an algorithmic fashion. For example, the a LazyMintModule.sol contract offers a means to add lazy minting functionality to an NFR, while the MerkleModule.sol contract implements a mechanism to fascilitate airdrop functionality. The REGISTRAR_ROLE_ADMIN can add and remove these modules from their NFR as needed.

    Lastly, the Hypernet NFR implements a native mechanism for registration by staking and ERC20-compatible token. By default, this feature is disabled, but the REGISTRAR_ROLE can set registrationToken to an address of an EIP20-compatible token which will enable the feature. The default registration fee is 1e18 (1 token assuming 18 decimal places) which can also be updated by the REGISTRAR_ROLE. In order to use this feature, a participant will approve the NFR to spend registrationFee amount of registrationToken from their account. The NFR will record the registration token address used and fee amount and associate this staking fee with the NFI tokenId. Upon burning of the NFI, any non-zero registration fee associated with the burned tokenId will be transfered to the account who burned the token, not the owner of the token at the time of burning.


    Deployment Addresses


    Install dependencies

    git clone
    cd hypernet-protocol/packages/contracts
    npm install

    Running contract tests

    npx hardhat test --logs

    Compiling contracts to generate artifacts

    npx hardhat compile

    Environment Variables

    If can set the following environment variable in order to customize your hardhat environment for testing or deployment purposes.

    ETH_PROVIDER_URL: URL that hardhat will use for its RPC provider, if blank then localhost is assumed.

    export ETH_PROVIDER_URL=

    MNEMONIC: Mnemonic phrase that hardhat will use to generate accounts for use in scripts and tasks. If blank the default is test test test test test test test test test test test junk.

    export MNEMONIC="candy maple cake sugar pudding cream honey rich smooth crumble sweet treat"

    Hardhat network - full contract deployment

    First, start a hardhat node (edit hardhat.config.js to customize the Hardhat network settings):

    npx hardhat node

    You can run the node on a custom port by adding the --port flag:

    npx hardhat node --port 8569

    Once the node is running, deploy the full Solidity contract stack to the Hardhat network (be sure to set the target network):

    npx hardhat run scripts/hardhat-full-stack.js --network dev




    npm i @hypernetlabs/contracts

    DownloadsWeekly Downloads






    Unpacked Size

    108 kB

    Total Files


    Last publish


    • barhantas
    • onurkenis
    • muhammed0101