Digital Identity
Hypernet Protocol Digital Identity
Summary
One of the key aspects of the Hypernet Protocol is digital identity, both human and non-human. The primary identity data structure of the Hypernet Protocol is the Non-Fungible Registry (NFR); instances of which are deployed through the registry factory contract. 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 intended to be used directly, the initializer pattern is used for setting parameters upon the creation of a new NFR.
Functionality
Non-Fungible Registries are a multi-purpose extension of the EIP721 non-fungible token (NFT) standard and therefor has all methods specified by the base standard specification. Additionally, the NFR has several customizable attributes. They 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).
Authenticity
The identity component of the Hypernet Protocol allows for a simple yet effective method for verifying the authenticity of NFRs. The address of the resulting NFR proxy contract created via the Hypernet Protocol NFR factory is stored in either the registries
or enumerableRegistries
public array variable (depending on if the NFR is deployed with or without the enumeration property). Additionally, a mapping from the human-readable name of the NFR (retrieved by calling the name()
function on any Hypernet NFR) to its proxy contract address is stored in the public nameToAddress
mapping variable. This has the additional effect of enforcing that every NFR within the Hypernet Protocol has a unique name. Thus, any external user wishing to ensure that they are interacting with an authentic Hypernet Protocol NFR need only query the contract factory with the name of the target NFR in order to obtain the address of the true registry.
Royalty support
Hypernet Protocol NFRs support the EIP-2981 interface for reporting royalty fees and recipients. The royalty recipient address is denoted by the burnAddress
(see the section of Token-Based Registration) and the the royalty fee is calculated via the burnFee
setting which has units of basis-points. Both variables are set by an account with the REGISTRAR_ROLE
permission setting. The burnFee
, which acts as the royalty percentage, is applied equivalently to all NFIs in an NFR.
Roles and minting
Enumerable roles
Every NFR defines the following enumerated roles:
DEFAULT_ADMIN_ROLE
: super-user style account than can add and remove addresses from any other role (the Hypernet DAO is the admin of every NFR)REGISTRAR_ROLE_ADMIN
: can add and remove addresses from theREGISTRAR_ROLE
REGISTRAR_ROLE
: can register new identities as well as update NFR parameters via thesetRegistryParameters
function
All roles are set up through the NFR constructor/initializer which is called by the registry factory. 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 owner's behalf if the NFI owner gives approval to the REGISTRAR_ROLE
through the approve
function.
Extending registry functionality
Each NFR can augment its registration logic (as well as add novel functionality) via external logic 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.
Token-based registration
Lastly, the Hypernet NFR implements a native mechanism for registration by sending an EIP20-compatible token to the registry. 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
. Utilization of this feature requires that a participant must 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.
Official Hypernet Protocol Non-Fungible Registries
The Hypernet Protocol instantiates several NFRs at protocol launch that are necessary for the secure functioning of payments, goverance, and identity functionality. All NFRs in this list are managed by the Hypernet Protocol DAO. That is, all roles are occupied by the Hypernet DAO contract.
The Hypernet Profile NFR is the primary registry of the Hypernet Protocol ecosystem. For an account to receive a NFI in any other NFR, that account must first create an NFI profile token in this registry. This is done by locking Hypertoken in the registry itself by approving the registry to pull registrationFee
amound of Hypertoken from the transaction initiator's account and then calling the registryByToken
function. The label
that is claimed in this action becomes the unique username of the entity within the Hypernet Protocol ecosystem (this username can be traded with other users or burned to reclaim some of the Hypertoken that was staked in its creation).
This NFR tracks official payment processing gateway providers. An NFI must be claimed in this registry for a payment processor, implemented on top of the Hypernet Protocol, to function within the Hypernet Protocol network. The label
of an NFI in this registry denotes the publicly accessible URL which hosts the payment processor's iframe for interacting with the payment processor. Then tokenURI
consists of the follow json attributes:
address
: address of the signing wallet used for code authenticity verification of the gateway provider's iframesignature
: the digital signature of the iframe code blob that is ingested by the Hypernet core package for payment processing
The owning wallet of a Gateways NFI can be different than that of the signing wallet denoted in the tokenURI
.
The Liquidity Providers registry provides a public list for discovering layer 2 liquidity providers and what Gateway providers they are officially doing business with. The label
of each NFI contains the routing identifier for the underlying Vector payment channel protocol. The tokenURI
has the following json structure:
supportedTokens
: array token addresses and chain id's of EIP20 compatible tokens supported by the liquidity providerallowedGateways
: array of URLs denoting Gateways the liquidity provider is willing to process transfers for. These URLs are the same as the labels used in the Gateways registry.
Not all EIP20 compatible token contracts expose the necessary metadata fields for safe interaction with the Hypernet Payment protocol. For example, the Wrapped Bitcoin contract on the Ethereum mainnet does not expose the decimals field; token decimals must the included as an offchain configuration which can inadvertenly lead to transaction sizes that are off by orders of magnitude. The label
field in this registry takes the form <chainid>:<token name>
. The tokenURI
is a json blob with the following structure:
name
: Name to be displayed in Hypernet Protocol component library impelementationssymbol
: Token symbol to be displayed in Hypernet Protocol component library impelementationschainId
: id of the network the token contract is deployed toaddress
: contract address where the token can be found given the chainid in thelabel
nativeToken
: a special boolean field for indicating if the token is the native token of the chain denoted by the chainiderc20
: special boolean flag for indicating if all necessary functions are present for ERC20 compatibility (native tokens may or may not be ERC20 compliant)decimals
: the number of decimal places to be applied to transactions with this tokenlogoUrl
: URL to pull logo asset for display purposes in Hypernet Protocal UI library components
All NFIs in this regsitry are owned by the Hypernet Protocol DAO.
Hypernet Protocol NFRs can modify their functionality by adding external contracts to the REGISTRAR_ROLE
. This can be a potentially dangerous modification, so the Registry Modules registry lists official contracts that are safe to use for modifying the functionality of a NFR deployment. The label
field is the human-readable name of the module contract and the tokenURI
is the address of the module contract. All NFIs in this registry are owned by the Hypernet Protocol DAO.
Last updated