Skip to main content

Identity

Overview​

Identity is central to Polymesh. Network participants must have an on-chain identity to interact with asset and identity related transactions on the blockchain.

Each identity:

  • Is created through DID onboarding and registration (self-registration or registrar-assisted)
  • Is referenced by a pseudo-anonymous decentralized identifier (DID), e.g., 0xfc0d2fc058d02c0a89c2cc2ff11726971dd39886a0b80ecfaa80fa3f196d65ce
  • Can hold asset balances via portfolios or Account IDs connected to the identity.
  • Can be associated with claims and have permissioned roles
  • Is controlled by a primary key and optional secondary keys

Identity Requirement on Polymesh​

An identity is required for:

  • All identity-related transactions (such as key management, adding or removing keys, and permissioned roles)
  • All asset-related transactions (such as holding, minting, and distributing assets)
  • Node operators
  • Permissioned roles (such as committee or council members)

An identity is not required for:

  • POLYX token operations, such as transfers between accounts
  • Staking operations for nominators with stash and controller accounts (such as bonding, nominating, and unbonding)

Key Concepts​

Identity Creation & Verification​

Identities are created through DID registration. Users can self-register using identity::self_register_did, or a permissioned DID registrar can register a DID for a target key using identity::register_did.

Asset Management​

Native assets (excluding POLYX) held by users are associated with their on-chain identity, via portfolios or directly on a signing key's account, provided that key is associated with an identity as either a primary key or secondary key. Each identity can hold multiple assets and manage them through different portfolios. Identities may also be granted agent permissions to perform specific operations on behalf of asset issuers.

Claims & Compliance​

Identities can receive claims from other identities, which are used to enforce on-chain compliance rules for assets. Claims have specific scopes and can be used to represent various attributes, such as KYC status or accreditation.

Key Management​

Each identity has:

Keys can also enter into a subsidized relationship with another key, allowing the subsidizer to pay transaction fees on its behalf.

Access Control​

Polymesh provides robust authorization and permission frameworks to manage access between identities and their keys.

Identity Diagrams​

The following diagrams help visualize and clarify the relationships between key aspects of on-chain identities in Polymesh. Each diagram focuses on a specific concept, such as DID onboarding, primary and secondary keys, portfolios, custody, claims and compliance, agent permissions, subsidized accounts, and secondary key permissions. For more details, see the linked documentation pages for each topic.

Identity Onboarding​

This diagram shows DID onboarding through self-registration or a permissioned DID registrar.

Keys & Accounts​

This diagram shows how an identity (DID) is controlled by signing keys. Both the primary key and any number of optional secondary keys are grouped in a "Signing Keys" subgraph. Each key can be a standard signing key (SR25519, ED25519, or ECDSA), a multisig, or a smart contract.

Secondary Key Permissions​

Secondary keys can be granted fine-grained permissions, allowing them to perform only specific actions or access certain resources. Permissions can be scoped to:

  • Transactions: Restrict which blockchain functions the key can call (e.g., transfers, settlements, etc.).
  • Portfolios: Restrict which portfolios the key can access or manage — this is what governs the key's ability to move and transfer assets not directly held by their key.
  • Assets: Restrict which assets the key can administer as an external agent (issuance, compliance, and other agent actions). Asset permissions do not restrict ordinary transfers of an asset out of a portfolio — that is governed by portfolio permissions. See Asset permissions do not restrict transfers.

The diagram below illustrates how secondary key permissions can be configured:

Portfolios & Asset Management​

This diagram demonstrates how an identity can have multiple portfolios (default, user, custodial) to organize and manage assets, including both fungible and non-fungible tokens.

Custody & Portfolio Control​

This diagram shows how portfolio control/custody can be assigned to another identity (the custodian), who then controls the portfolio's assets.

Claims & Compliance​

This diagram illustrates how claims (such as KYC or accreditation) are issued to an identity by claim issuers, and how they are used for compliance purposes. Multiple claims from different issuers can be attached to a single identity and may be scoped to specific assets, identities or custom identifiers.

Agent Permissions​

This diagram shows how an identity can grant agent permissions to another identity, allowing the agent to act on behalf of the original identity for specific assets or operations. The asset issuer is an agent for its own asset by default.

Relayer & Subsidized Keys​

This diagram shows how a relayer can subsidize transaction fees for a signing key (not directly for an identity), allowing another key (owned by a relayer identity) to pay fees on behalf of a key. The relayer's key may be under a different identity than the subsidized key.