Skip to main content

Identity

Overview​

Identity is at the core of Polymesh.

To submit a transaction on-chain, the signing key of that transaction must be associated with an identity or authorising an action on behalf of an identity.

Polymesh implements a federated root of trust via permissioned Customer Due Diligence service providers. Every transaction in Polymesh is associated with an identity.

Identities in Polymesh are controlled via keys - each identity must have a single primary key and can optionally have additional secondary keys.

Identities are a collection of claims and assets and controlled via keys.

A user can have multiple identities, which allows them a degree of privacy with respect to their total asset holdings.

Each identity is referenced via a decentralised identifier - its DID. A DID is a pseudo-anonymous identifier such as 0xfc0d2fc058d02c0a89c2cc2ff11726971dd39886a0b80ecfaa80fa3f196d65ce.

Identity Diagram​

Identity Diagram

Assets​

Assets held by a user are associated with one of their identities. For example the identity with DID 0xalice might have a balance of 50 ACME tokens and 30 FOO tokens.

Assets held by an identity can be organised into portfolios beneath that identity.

Claims​

An identity can add a claim to another identity, and in turn holds claims that have been added to it by other identities.

To enforce compliance on their assets, asset issuers nominate trusted claim issuers to manage their investors claims related to their assets compliance rules.

Authentication and Keys​

Identities are created for users by CDD service providers.

Unlike most blockchains, in Polymesh all on-chain actions are associated both with a signing key (the key used to sign the transaction) and an on-chain identity.

To facilitate this connection between identities and signing keys, each on-chain identity is associated with keys which are allowed to sign on its behalf. A given key can only be associated with at most one identity at any one time.

These keys are known either as primary keys or secondary keys.

POLYX, the native token of Polymesh, is held at the key level. Staking and governance, both of which utilise POLYX, is also associated with keys. In both cases, although balances are held at the key level, any transaction involving POLYX must be associated with an identity that has a valid CDD claim.

Primary and Secondary Keys​

An identity is associated with a primary key on creation by the CDD service provider. This key is typically the public half of a public / private key pair held by the user owning the identity.

The primary key of an identity has full permissions to that identity and can add and remove additional secondary keys.

A secondary key can also sign transactions on behalf of its identity, but can have its permissions limited to only certain actions, portfolios or assets. It can also be removed by the primary key of its identity at any time.

For more information on our public / private key cryptography please see: https://docs.substrate.io/learn/cryptography/

Key Types​

There are three types of keys that can be used in Polymesh:

  • Public / Private key pairs
  • Multisigs
  • Smart Contracts

Polymesh is generally agnostic as to the type of key being used, and treats each key type consistently (e.g. for permissioning).

Public / Private Key Pairs​

Polymesh uses public-key cryptography based on the Ed25519 curve, and allows keys that use either the Ed25519, SR25519 or ECDSA constructions.

These types of keys can be held on hardware wallets, or can be generated off-line and stored as paper wallets.

Multisigs​

In addition to public / private key pairs a key can also be a multisig account.

A multisig is a single key which is controlled by one or more people. A n of m multisig requires n of its m members to agree on an action, before that action can be signed by that multisig.

  • MultiSig Signers: the keys attached to the MultiSig as signers

  • Creator Identity: the identity that created the MultiSig - this is fixed and can't be modified

  • Acting Identity: the identity that the MultiSig acts through, by virtue of being attached as a Primary / Secondary Key.

  • MultiSig Signers => MultiSig is mapped through KeyToMultiSig

  • MultiSig => Creator Identity is mapped through MultiSigToIdentity

  • MultiSig => Acting Identity and assigned permissions (if applicable) are mapped through KeyRecords (None if MultiSig is not a Primary / Secondary Key)

This has the consequence that MultiSig Signers can not send / receive POLYX (since they are not directly associated with an identity).

MultiSigs can hold funds, once they have been attached as a Primary / Secondary Key to an identity. If they are removed from the identity they can continue to hold funds, as per normal external key behaviour, but these funds are locked until the key is reattached to a CDD'ed identity.

All transactions have a single payer, which is established when the transaction is first submitted. For a transaction executed via a MultiSig this will be the Creator Identity derived from the external MultiSig Signer account that submits the extrinsic.

When Signers are approving / proposing a MultiSig transaction, we have:

  • CDD check done on Creator Identity

  • Payment made by Creator Identity

When a MultiSig executes a proposal, we have:

  • CDD check done on Creator Identity

  • CDD check done on Acting Identity (on dispatch)

  • Payment made by Creator Identity

Smart Contracts​

While not conventionally considered key types, Smart Contracts are represented by a public address on Polymesh, akin to other key types, making them a unique type of key. Like other key types, smart contracts must be joined to an identity as either a primary or a secondary key to be able to transact on chain.

Smart Contracts allow developers to define custom logic, rules, records, and functions. They are vital tools for automating intricate processes, including the facilitation of decentralized applications, and expanding the network's capabilities. Smart contracts, like other keys, can hold POLYX tokens but require external key interaction to initiate actions. These contracts seamlessly interact with Polymesh through chain extensions, granting access to blockchain data and functionalities, thereby supporting diverse decentralized applications and use cases.

Permissions​

Permissions in Polymesh have three levels of granularity, that can be combined:

  • assets

  • extrinsics

  • portfolios

The assets granularity allows a key to be limited to interacting with only specific assets held in any portfolio under the identity.

The extrinsics granularity allows a key to be permissioned to specific on-chain actions, such as submitting documentation for an asset, or signalling in governance.

The portfolios granularity allows a key to be limited to interacting with only those assets in specific portfolios under that identity.

The access of a particular key is the intersection of each of these categories. It is possible to permission a key with full access to any of these categories.

Not all on-chain actions are associated with either an asset, or a portfolio (for example staking). For such actions, these permission types are not checked.

Child Identities​

An identity as described above is always created by a CDD service provider.

This process involves two steps for CDD providers:

  • creating an on-chain identity for the user, referenced via the returned DID
  • issuing a CDD claim to the new on-chain identity

When a user submits a transaction to the network, we:

  • determine the associated identity by looking at what identity the key that signs the transaction is linked to (this can be at most one identity)
  • check that this associated identity has a valid (issued by a current CDD provider, not expired) CDD claim

However for some use-cases it may be helpful for existing identities created via CDD providers to be able to create additional child identities unilaterally (i.e. without the involvement of a CDD provider).

Child Identity Diagram

Some possible use-cases:

  • Isolate a smart contract from the deployer's identity to protect user funds held or controlled by the smart contract.

  • Extra layer of protection, with the child identities being "hot wallets" and the parent identity being "cold wallets". Since assets are held at the identity-level, it can be useful to have hot / cold identities.

  • Organizational structure (one child identity for each department/sub-company).

Polymesh allows any "parent" identity (an identity created via a CDD provider) to create additional child identities - these are normal identities except that they inherit their CDD claim from their parent, rather than via an explicit CDD claim issued by a CDD provider attached to the child DID.

To create a new child identity, there is an extrinsic identity::create_child_identity and corresponding SDK / RESTful API methods.

Once a child identity is created, it is assigned its own unique DID, and can hold claims and assets like any other identity. A child identity cannot create additional child identities underneath it - i.e. we do not allow recursion when creating child identities. A child identity only inherits its CDD status from its parent identity - any other claims related to compliance must be held directly by the child identity.

If desired, a child identity can be unlinked from its parent. This means that it will no longer inherit its CDD status from its parents CDD claim, but instead must get its own CDD claim from a permissioned CDD provider.