§ Verifiable Public Registry v3 Specification

Specification Status: Preview

Latest Draft: verana-labs/verifiable-trust-vpr-spec

Editors:

Fabrice Rochette (The Verana Foundation)

Contributors:

Ariel Gentile

Mathieu Gauthron

Pratik Kumar

Participate:

GitHub repo

File a bug

Commit history

§ Abstract

The internet is broken. Existing communication channels are insecure and outdated. Because they rely on public identifiers - like email addresses, usernames, or phone numbers - anyone who knows your identifier can reach you, whether you invited them or not.

Worse, there’s no reliable way to verify the identity of either service providers or users. This leaves the door wide open to spam, phishing, fraud, and identity theft.

On the service side, each provider imposes its own fragmented registration process, often with complex password requirements or forced reliance on federated login systems, effectively handing control over to large third-party platforms.

Although the World Wide Web was originally built for openness and interoperability, dominant players have reshaped it into a closed, centralized system that most people and organizations now depend on. Privacy has become an afterthought, and personal data is routinely harvested, exploited, or leaked.

To rebuild a trustworthy internet, we need new communication channels - channels that are secure by design, based on mutual verification, and governed by decentralized trust.

Connecting to a service, proving who you are, or creating an account should be as simple and safe as presenting a verifiable credential.

A universal, open trust layer is essential for this vision to succeed.

That’s the purpose of Verifiable Trust. The concept of Verifiable Trust is specified in the Verifiable Trust spec.

This specification deals with the Verifiable Public Registry (VPR), a decentralized registry of registries, part of the Verifiable Trust concept.

§ About this Document

In order to fully understand the concepts developed in this document, you should have some basic knowledge of DID, DIDComm, VS, trust registry, ledger-based applications, and more generally, all terms present in the Terminology section.

§ Introduction

§ What is a Trust Registry?

This section is non-normative.

A trust registry is an approved list of recognized ecosystem participants, such as trust registry operators, credential issuers and verifiers that are authorized to onboard ecosystem participants, and or issue/verify certain credentials in an ecosystem.

A trust registry typically expose APIs that are consumed by services that would like to query its database, and take decisions based on the returned result:

• can participant #1 issue credential for schema ABC of ecosystem E1?
• can participant #2 request credential presentation of credential issued by issuer DEF from schema GHI of ecosystem E2, for jurisdiction France in context CONTEXT?

§ What is a Verifiable Public Registry?

This section is non-normative.

A Verifiable Public Registry (VPR) is a “registry of registries”, a public service that provides foundational infrastructure for decentralized trust ecosystems. It offers:

• trust registry management:
  ecosystems can create and manage their own trust registries, each with:

  • defined credential schemas
  • assigned roles for issuers, verifiers, and grantors (trust registry operators)
  • custom business models and permission policies

• query API for trust resolution:
  A standardized API used by verifiable services (VSs) and verifiable user agents (VUAs) to perform trust resolution, enabling them to query registry data and validate roles and permissions in real time.

Additionally, a VPR provides a DID directory, a simple repository of service identifiers (DIDs).

Any account registered in the VPR can add a DID to the DID directory.

This directory is intended to be crawled by indexers, which resolve the listed DIDs, identify associated verifiable services, and index them.

Indexers may expose this data through APIs for querying the indexed services or use it to build a search engine for querying the database of indexed verifiable services.

§ Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

§ Terminology

account:

A verifiable public registry account.

applicant:

A account that starts a validation process.

controller:

An account which is the controller of a specific resource in an VPR.

credential schema:

An VPR resource which represents a verifiable credential definition and the associated permissions and business rules for issuing, verifying or holding a credential linked to this credential schema.

credential schema permission:

A permission, linked to a credential schema, that represent, in a given ecosystem, a grant for being issuer, verifier, issuer grantor, or verifier grantor of a credential schema.

decentralized identifier:

A decentralized identifier, as specified in [DID-CORE].

decentralized identifier communication:

DIDComm uses DIDs to establish confidential, ongoing connections.

decentralized identifier document:

A DID Document, as specified in [DID-CORE].

decentralized web nodes:

Decentralized web nodes, see DIF spec

denom:

Native token of a VPR, example: VNA.

DID Directory:

A repository of DIDs in a VPR.

ecosystem: a network of interacting entities, both technical and human, that work together to establish and maintain digital trust. It encompasses applications, credentials, governance frameworks, and the underlying technical infrastructure, all designed to facilitate trustworthy interactions.

ecosystem governance framework:

The governance framework (GF) of an ecosystem].

ecosystem governance authority:

The governance authority (GA) of an ecosystem.

entity:

An account controller.

estimated transaction fees:

Estimated fees required, in denom, that is passed when execute a transaction in an VPR. Usually, a estimated transaction fees are always slightly greater than transaction fees, to make sure the execution of the transaction will not be aborted for an out-of-gas situation. Unused gas is refunded to account.

governance framework:

The governance framework (GF) of a VPR.

governance authority:

The governance authority (GA) of a VPR.

grantor:

A role an entity is granted by an ecosystem for operating its trust registry.

holder:

A role an entity might perform by possessing one or more verifiable credentials and generating verifiable presentations from them. A holder is often, but not always, a subject of the verifiable credentials they are holding. Holders store their credentials in credential repositories. Example holders include organizations, persons, things.

issuer:

A role an entity is granted by an ecosystem or an issuer grantor for issuing credentials of a given credential schema to holders.

issuer grantor:

A trust registry operator role an entity is granted by an ecosystem for a given credential schema for adding or revoking issuers.

json schema

a Json Schema, as specified in https://json-schema.org/specification.

keeper:

A storage map(key, value) in the ledger of an VPR.

linked-vp:

A presentation of a verifiable credential as specified in LINKED-VP.

participant:

An entity that is recognized by one or several ecosystem(s) in a VPR.

query:

A read-only action that perform some reading in an VPR and returns value.

subject:

A thing about which claims are made. Example subjects include human beings, animals, things, and organization, a DID…

transaction:

An action that modifies the ledger of an VPR and which execution requires transaction fees.

transaction fees:

Fees required, in denom, to execute a transaction in an VPR.

trust deposit:

A financial deposit that is used as a trust guarantee. For a given controller, its trust deposit is increased when running validation process (either as an applicant or as a validator), or when registering DID in the DID directory.

trust fee:

Fees paid by a participant that are distributed to other participants.

network fee:

Fees paid by a participant that are distributed to network validators and trust deposit holders.

trust unit:

Price, in denom, of one unit of trust.

trust registry

An approved list of issuers and verifiers that are authorized to issue/verify certain credentials in an ecosystem.

URI

An Universal Resource Identifier, as specified in rfc3986.

valid permission:

For a given country code, a credential schema permission of a given type, which (country attribute is null or equals to the given country code), and effective_from timestamp is lower than current timestamp, and (effective_until timestamp is null or greater than current timestamp), and revoked is null and slashed is null.

validation process:

A process run by applicants that want to, for a specific credential schema, be a issuer, be a verifier, or simply hold a verifiable credential linked to the credential schema.

validator:

A role an entity performs by participating in validation processes with applicants in order to register them as issuer, or verifier of a credential schema, or to deliver a verifiable credential to them.

verifiable public registry:

a public, normally decentralized, ledger-based network, which provides: trust registry features, that can be used by all its participants: create trust registries, for each trust registry, define its credential schemas, who can issue, verify credential of a specific credential schema,… and a tokenized business model for charging/rewarding participants.

verifiable service:

A service, identified by a resolvable DID that can be deployed anywhere by its owner, and that is conforming to this spec and has a resolvable Proof-of-Trust. See VT Spec.

verifiable user agent:

A user agent for accessing and using VSs. To be considered a VUA, a user agent must conform and enforce this spec, such as presenting a proof of trust to end user before accepting connecting to VS compliant services, and refuse connecting to not compliant services. See VT Spec.

Verifiable Trust Specification:

see VT Spec.

verifier:

A role an entity is granted by an ecosystem or a verifier grantor for verifying credentials of a given credential schema.

verifier grantor:

A trust registry operator role an entity is granted by an ecosystem for a given credential schema for adding or revoking verifiers.

verifiable credential:

A verifiable credential as defined in [VC-DATA-MODEL].

§ Naming Conventions

§ In this spec

• For clarity, Camel Case is used for naming Modules, Entities, Objects, etc.

§ In Implementations

• All APIs MUST return valid JSON.
• All JSON content MUST use Snake Case for object, attribute… names.
• Object attributes and Json Content in general can be returned in any order.

§ Features of a Verifiable Public Registry (VPR)

§ Trust Registry Management

This section is non-normative.

In an VPR, any account can create (and become the controller of) a TrustRegistry entry that represents a trust registry of an ecosystem. Each TrustRegistry entry must provide, at a minimum:

• an ecosystem controlled resolvable DID;
• one or more ecosystem governance framework document(s);
• zero or more credential schemas.

The Verifiable Public Registry (VPR) is agnostic to the specific DID methods used. Trust resolution is performed externally, outside the VPR, allowing flexibility and interoperability across ecosystems.

§ Credential Schemas and Permissions

This section is non-normative.

Credential schemas are created and managed by trust registry controller (ecosystems). Each Credential schema includes, at a minimum:

• A JSON Schema that defines the structure of the corresponding verifiable credential
• A PermissionManagementMode for issuance policy, which determines how ISSUER permissions are granted. Modes include:
  • OPEN: ISSUER permissions can be created by anyone.
  • ECOSYSTEM: ISSUER permissions are granted directly by the ecosystem, the trust registry controller
  • GRANTOR: ISSUER permissions are granted by one or several issuer grantor(s) (trust registry operator(s) responsible for selecting issuers for the credential schema of this ecosystem), selected by the ecosystem.
• A PermissionManagementMode for verification policy, which determines how VERIFIER permissions are granted. Modes include:
  • OPEN: VERIFIER permissions can be created by anyone.
  • ECOSYSTEM: VERIFIER permissions are granted directly by the ecosystem, the Trust Registry controller
  • GRANTOR: VERIFIER permissions are granted by one or several verifier grantor(s) (trust registry operator(s) responsible for selecting verifiers for the credential schema of this ecosystem), selected by the ecosystem.
• A Permission tree that defines the roles and relationships involved in managing the schema’s lifecycle. Each created permission in the tree can define business rules, see below Business Models.

Participant roles are defined in the table below:

Example of a Json Schema credential schema:

{
  "$id": "vpr:verana:mainnet/cs/v1/js/VPR_CREDENTIAL_SCHEMA_ID",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ExampleCredential",
  "description": "ExampleCredential using JsonSchema",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "firstName": {
          "type": "string",
          "minLength": 0,
          "maxLength": 256
        },
        "lastName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "expirationDate": {
          "type": "string",
          "format": "date"
        },
        "countryOfResidence": {
          "type": "string",
          "minLength": 2,
          "maxLength": 2
        }
      },
      "required": [
        "id",
        "lastName",
        "birthDate",
        "expirationDate",
        "countryOfResidence"
      ]
    }
  }
}

To participate in an ecosystem and assume a role associated with a specific credential schema:

• if schema is OPEN for issuance and/or verification: an entity must have an account in the VPR and self-create its permission.

• if schema is not OPEN for issuance and/or verification: an entity must have an account in the VPR and complete a validation process to obtain the required permission.

The validation process involves two parties:

• The applicant — the entity requesting permission for a credential schema within the ecosystem.
• The validator — an entity that already holds permission for the same credential schema and has been delegated authority to validate applicants and issue permissions.

Running a validation process typically involves the payment of trust fees. Trust fee amount to be paid by the applicant is defined in the permission of the validator involved in the validation process:

§ DID Directory Management

This section is non-normative.

The DID directory is a public database of services that can be used by crawlers to index the metadata associated with verifiable services.

Search engines can iterate over the DID directory and index VSs by resolving the service identifier (at the moment a DID, that could be extended in the future), verify if service is a verifiable service, and in such a case extracting their verifiable metadata, such as linked-vp presented credentials.

The DID directory is particularly important for verifiable user agents, such as social browsers, CDN enabled browsers… However, it can also be leveraged by traditional, form-based search engines, which may return simple links for accessing VSs.

Any participant can register a DID in the DID directory by executing a transaction involving network fees and requiring trust deposit.

§ Business models

§ Trust Deposit

This section is non-normative.

In a VPR, each account is associated with a trust deposit.

This trust deposit is automatically funded through transactions involving trust operations, such as:

• Creating trust-related objects int the VPR (e.g., ecosystem trust registries, credential schemas, DIDs in the DID directory)
• Paying trust fees between participants when enforcing ecosystem governance rules for services, credential issuance, or presentation…

The trust deposit is fundamental to the “Proof-of-Trust” (PoT) mechanism of the Verifiable Trust Specification, and it operates as follows:

• The more you use the VPR, the more your trust deposit grows.
• Trust deposits generate yield: block execution fees are distributed not only to network validators, but also to trust deposit holders.
• network-level penalties: If a participant violates the governance framework of the VPR or engages in fraudulent activity, their trust deposit may be partially or fully slashed by the VPR's governance authority.
• ecosystem-level penalties: If a participant operates within an ecosystem (e.g., as a grantor, issuer, verifier, or holder,…) and fails to comply with that ecosystem’s governance framework (EGF), their ecosystem-specific trust deposit can be slashed by the corresponding ecosystem governance authority.
• A slashed deposit must be refilled to continue using the services that triggered the penalty.
• When a participant withdraws from an ecosystem, the associated accumulated trust deposit may be released.
• Released deposits can be reused in other services or withdrawn, however, withdrawals incur penalties, and a portion of the withdrawn amount is burned.
• Holding a large trust deposit does not grant governance rights in the VPR: participants who generate high transaction volume cannot gain control over the governance of the VPR solely through usage or deposit size.

This system ensures that participation in the trust ecosystem is backed by economic accountability, reinforcing the integrity, governability and verifiability of the VPR.

§ Object creation

This section is non-normative.

Creating the following objects requires both a contribution to the trust deposit and the payment of applicable network fees:

• Trust Registries: requires trust_registry_trust_deposit trust units, plus associated network fees
• Credential Schemas: requires credential_schema_trust_deposit trust units, plus associated network fees
• DID Directory entries: requires did_directory_trust_deposit trust units, plus associated network fees

The following operations only require payment of network fees (no trust deposit is involved):

• Updating the governance framework documents of an ecosystem trust registry
• Removing a DID from the DID Directory

§ Validation process trust fees

This section is non-normative.

We’ve explained in the Credential Schemas and Permissions section above what is a validation process.

The table below summarizes the possible combinations of applicants and validators:

• (1): if issuer mode is set to GRANTOR.
• (2): if verifier mode is set to GRANTOR.
• (3): if issuer mode is set to ECOSYSTEM.
• (4): if verifier mode is set to ECOSYSTEM.

Validation process is started by the applicant.

Example of a candidate issuer (applicant) that would like to be granted an ISSUER permission for a credential schema of an ecosystem, by a validator that has a ISSUER_GRANTOR permission:

The total fees paid by the applicant consists of:

• The validation trust fees defined in the permission of the validator participating in the validation process, plus
• An additional amount equal to the trust_deposit_rate of that validation trust fees, which is allocated to the applicant’s trust deposit when the validation process begins.
• network fees (not part of the escrowed amount).

Example, using 20% for trust_deposit_rate:

Upon completion of the validation process, escrowed trust fees are distributed to the validator as follows:

• A portion defined by trust_deposit_rate is allocated to the validator’s trust deposit.
• The remaining amount is transferred directly to the validator’s wallet.

§ “Pay-Per” trust fees

This section is non-normative.

Pay-per-issuance and pay-per-verification trust fees are defined at the permission level for each role within the ecosystem.

Entities acting as issuers or verifiers for a given credential schema may be required to pay trust fees based on the schema’s configuration and permission tree.

If trust fee payment is required, the entity must execute a transaction in the VPR to pay the appropriate trust fees before issuing or verifying a credential.

Key Points for “Pay-Per” Business Models

• For a given credential schema, ecosystem and their participants may define pay-per-issuance (or pay-per-verification) trust fees in their respective permissions.

• In such cases, a participant ISSUER (or VERIFIER) must pay:

  • The corresponding issuance (or verification) trust fees for each involved permission;
  • An additional amount equal to the trust_deposit_rate of the calculated trust fees, allocated to the applicant’s trust deposit;
  • An amount equal to wallet_user_agent_reward_rate of the calculated trust fees, used to reward the Wallet User Agent;
  • An amount equal to user_agent_reward_rate of the calculated trust fees, used to reward the User Agent.

Fee Distribution Model

Trust fees are consistently distributed across participants:

• A portion defined by trust_deposit_rate is allocated to the participant’s trust deposit.
• The remaining portion is transferred directly to the participant’s wallet.

Distribution example for the issuance by ISSUER #C of a credential, using the permission tree above, 20% for trust_deposit_rate, 10% for wallet_user_agent_reward_rate and user_agent_reward_rate.

Distribution example for the verification by VERIFIER #E of a credential issued by ISSUER #C, using the permission tree above, 20% for trust_deposit_rate, 10% for wallet_user_agent_reward_rate and user_agent_reward_rate.

§ Governance of a VPR

This section is non-normative.

A governance framework must define the governance rules that apply to a VPR.

A designated governance authority is responsible for enforcing these rules and, when necessary, applying financial sanctions to participants who violate the rules.

§ Data model

For simplicity, the data model is presented using an object-relational structure. However, this representation may not be optimal for all implementation scenarios.

Implementors are responsible for adapting the data model to suit their chosen architecture.
For example, a key-value store may be more appropriate for a ledger-based implementation than a relational model.

§ TrustRegistry

TrustRegistry:

• id (uint64) (mandatory): the id of the trust registry.
• did (string) (mandatory): the did of the ecosystem.
• controller (account) (mandatory): account that controls this entry.
• created (timestamp) (mandatory): timestamp this TrustRegistry has been created.
• modified (timestamp) (mandatory): timestamp this TrustRegistry has been modified.
• archived (timestamp) (mandatory): timestamp this TrustRegistry has been archived.
• deposit (number) (mandatory): trust deposit (in denom)
• aka (string) (optional): optional additional URI of this trust registry.
• language (string(2)) (mandatory): primary language alpha-2 code (ISO 3166) of this trust registry.
• active_version (int): (mandatory) active governance framework version.

§ GovernanceFrameworkVersion

GovernanceFrameworkVersion:

• id (uint64) (mandatory): the id of the schema.
• tr_id (uint64) (mandatory): the id of the trust registry that controls this GovernanceFrameworkVersion entry.
• created (timestamp) (mandatory): timestamp this GovernanceFrameworkVersion has been created.
• version (int) (mandatory): version of this GF. MUST Starts with 1.

§ GovernanceFrameworkDocument

GovernanceFrameworkDocument

• id (uint64) (mandatory): the id of the schema.
• gfv_id (uint64) (mandatory): the id of the GovernanceFrameworkVersion entry.
• created (timestamp) (mandatory): timestamp this GovernanceFrameworkDocument has been created.
• language (string(2)) (mandatory): primary language alpha-2 code (ISO 3166) of this trust registry.
• url (string) (mandatory): URL where the document is published.
• digest_sri (string) (mandatory): digest_sri of the document.

§ CredentialSchema

CredentialSchema:

General Info:

• id (uint64) (mandatory): the id of the schema.
• tr_id (uint64) (mandatory): the id of the trust registry that controls this CredentialSchema entry.
• created (timestamp) (mandatory): timestamp this CredentialSchema has been created.
• modified (timestamp) (mandatory): timestamp this CredentialSchema has been modified.
• archived (timestamp) (mandatory): timestamp this CredentialSchema has been archived.
• deposit (number) (mandatory): trust deposit (in denom)
• json_schema (string) (mandatory): Json Schema used for issuing credentials based on this schema.
• issuer_grantor_validation_validity_period (number) (mandatory): number of days after which an issuer grantor validation process expires and must be renewed.
• verifier_grantor_validation_validity_period (number) (mandatory): number of days after which a verifier grantor validation process expires and must be renewed.
• issuer_validation_validity_period (number) (mandatory): number of days after which an issuer validation process expires and must be renewed.
• verifier_validation_validity_period (number) (mandatory): number of days after which a verifier validation process expires and must be renewed.
• holder_validation_validity_period (number) (mandatory): number of days after which an holder validation process expires and must be renewed.
• issuer_perm_management_mode (PermissionManagementMode) (mandatory): defines how permissions are managed for issuers of this CredentialSchema. OPEN means anyone can issue credential of this schema; GRANTOR means a validation process MUST be run between a candidate ISSUER and an ISSUER_GRANTOR in order to create an ISSUER permission; ECOSYSTEM means a validation process MUST be run between a candidate ISSUER and the trust registry owner (ecosystem) of the CredentialSchema entry in order to create an ISSUER permission;
• verifier_perm_management_mode (PermissionManagementMode) (mandatory): defines how permissions are managed for verifiers of this CredentialSchema. OPEN means anyone can verify credentials of this schema (does not implies that a payment is not necessary); GRANTOR means a validation process MUST be run between a candidate VERIFIER and a VERIFIER_GRANTOR in order to create a VERIFIER permission; ECOSYSTEM means a validation process MUST be run between a candidate VERIFIER and the trust registry owner (ecosystem) of the CredentialSchema entry in order to create a VERIFIER permission;

§ Permission

Permission:

• id (uint64) (mandatory): the id of the perm.
• schema_id (uint64) (mandatory): the id of the related CredentialSchema entry.
• type (PermissionType): ISSUER, VERIFIER, ISSUER_GRANTOR, VERIFIER_GRANTOR, ECOSYSTEM, HOLDER
• did (string) (optional): DID this permission refers to. MUST conform to [RFC3986].
• grantee (account) (mandatory): account this permission refers to (account granted to act as type for schema schema_id).
• created (timestamp) (mandatory): timestamp this Permission has been created.
• created_by (account) (mandatory): account that created this permission.
• extended (timestamp) (mandatory): timestamp this Permission has been extended.
• extended_by (account) (mandatory): account that extended this permission.
• slashed (timestamp) (mandatory): timestamp this Permission has been slashed.
• slashed_by (account) (mandatory): account that slashed this permission.
• repaid (timestamp) (mandatory): timestamp this Permission has been repaid.
• repaid_by (account) (mandatory): account that repaid this permission.
• effective_from (timestamp) (optional): timestamp from which (inclusive) this Permission is effective.
• effective_until (timestamp) (optional): timestamp until when (exclusive) this Permission is effective, null if no time limit has been set for this permission.
• modified (timestamp) (mandatory): timestamp this Permission has been modified.
• validation_fees (number) (mandatory): price to pay by an applicant to a validator (grantee of this perm) for running a validation process for a given validation period, in trust unit. Default to 0.
• issuance_fees (number) (mandatory): fees requested by grantee of this perm when a credential is issued, in trust unit. Default to 0.
• verification_fees (number) (mandatory): fees requested by grantee of this perm when a credential is verified, in trust unit. Default to 0.
• deposit (number) (mandatory): accumulated grantee deposit in the context of the use of this permission (including the validation process), in denom. Usually, it is incremented when for example, for a ISSUER type Permission perm, issuer issues credentials that require paying issuance fees: an additional % of the fees is charged to issuer and sent to its deposit, corresponding deposit amount increases this perm.deposit value as well. If perm is, let’s say revoked, then corresponding perm.deposit value is freed from perm.grantee Trust Deposit.
• slashed_deposit (number) (mandatory): part of the deposit that has been slashed.
• repaid_deposit (number) (mandatory): part of the slashed deposit that has been repaid.
• revoked (timestamp) (optional): manual revocation timestamp of this Perm.
• revoked_by (account) (mandatory): account that revoked this permission.
• country (string) (optional): country, as an alpha-2 code (ISO 3166), this permission refers to. If null, it means permission is not linked to a specific country.
• validator_perm_id (uint64) (optional): permission of the validator assigned to the validation process of this permission, ie parent node in the Permission tree.
• vp_state (enum) (mandatory): one of PENDING, VALIDATED, TERMINATED, TERMINATION_REQUESTED.
• vp_exp (timestamp) (optional): validation expiration timestamp. This expiration timestamp is for the validation process itself, not for the issued credential or Permission expiration timestamp.
• vp_last_state_change (timestamp) (mandatory)
• vp_validator_deposit: number (optional): accumulated validator trust deposit, in denom.
• vp_current_fees (number) (mandatory): current action escrowed fees that will be paid to validator upon validation process completion, in denom.
• vp_current_deposit (number) (mandatory): current action trust deposit, in denom.
• vp_summary_digest_sri (digest_sri) (optional): an optional digest_sri, set by validator, of a summary of the information, proofs… provided by the applicant.
• vp_term_requested (timestamp) (optional): set when controller requests the termination of this entry.

§ PermissionSession

PermissionSession:

• id (uuid) (mandatory): session uuid.
• controller (account) (mandatory): account that controls the entry.
• agent_perm_id (uint64) (mandatory): permission id of the agent.
• modified (timestamp) (mandatory): timestamp this PermissionSession has been modified.
• created (timestamp) (mandatory): timestamp this PermissionSession has been created.
• authz (uint64 (Permission id), uint64 (Permission id), uint64 (Permission id))[] (mandatory): permission(s) linked to this session (issuer, verifier, wallet_agent).

§ DIDDirectory

DidDirectory:

• did (string) (mandatory) (key): the DID. MUST conform to [RFC3986].
• controller (account) (mandatory): account that created the DID.
• created (timestamp) (mandatory): timestamp this DID has been added.
• modified (timestamp) (mandatory): timestamp this DID has been modified.
• exp (timestamp) (mandatory): expiration timestamp.
• deposit (number) (mandatory): effective trust deposit for this DID (in denom)

§ TrustDeposit

TrustDeposit:

• share (number) (mandatory): share of the module total deposit.
• account (account) (mandatory) (key): the account
• amount (number) (mandatory): amount of deposit in denom.
• claimable (number) (mandatory): amount of claimable deposit in denom.
• slashed_deposit (number) (optional): amount of slashed deposit in denom.
• repaid_deposit (number) (optional): amount of slashed deposit in denom.
• last_slashed (timestamp) (optional): last time this trust deposit has been slashed.
• last_repaid (timestamp) (optional): last time this trust deposit has been slashed.
• slash_count (number) (optional): number of times this account has been slashed.
• last_repaid_by (account) (optional): account that repaid the last slash.

§ GlobalVariables

GlobalVariables:

Trust Unit:

• trust_unit_price (number) (mandatory): trust unit price, in denom.

Credential Schema:

• credential_schema_trust_deposit (number) (mandatory): default trust deposit value for creating a credential schema, in trust units.
• credential_schema_schema_max_size (number) (mandatory): maximum size of the schema string attribute for a CredentialSchema.
• credential_schema_issuer_grantor_validation_validity_period_max_days (number) (mandatory): maximum number of days an issuer grantor validation can be valid for.
• credential_schema_verifier_grantor_validation_validity_period_max_days (number) (mandatory): maximum number of days an verifier grantor validation can be valid for.
• credential_schema_issuer_validation_validity_period_max_days (number) (mandatory): maximum number of days an issuer validation can be valid for.
• credential_schema_verifier_validation_validity_period_max_days (number) (mandatory): maximum number of days an verifier validation can be valid for.
• credential_schema_holder_validation_validity_period_max_days (number) (mandatory): maximum number of days an holder validation can be valid for.

Validation:

• validation_term_requested_timeout_days (number) (mandatory): after this number of days, validation applicant can confirm termination of a validation if validator didn’t do it.

Trust Registry:

• trust_registry_trust_deposit (number) (mandatory): default trust deposit value for creating a trust registry, in trust units.

DID Directory:

• did_directory_trust_deposit (number) (mandatory): default trust deposit value, in trust units.
• did_directory_grace_period_days (number) (mandatory): default grace period, in days.

Trust Deposit:

• trust_deposit_reclaim_burn_rate (number) (mandatory): percentage of burnt deposit when an account execute a reclaim of capital amount.
• trust_deposit_share_value(number) (mandatory): Value of one share of trust deposit, in denom. Default an initial value: 1. Increase over time, when yield is produced.
• trust_deposit_rate(number) (mandatory): Rate used for dynamically calculating trust deposits from trust fees. Default value: 20% (0.20)
• trust_deposit_max_yield_rate(number) (mandatory): Maximum yearly yield, in percent, that a trust deposit holder can obtain by receiving block rewards.
• trust_deposit_block_reward_share(number) (mandatory): Percentage of block reward that must be distributed to trust deposit holders. Default value: 20% (0.20)
• wallet_user_agent_reward_rate(number) (mandatory): Rate used for dynamically calculating wallet user agent rewards from trust fees. Default value: 20% (0.20)
• user_agent_reward_rate(number) (mandatory): Rate used for dynamically calculating user agent rewards from trust fees. Default value: 20% (0.20)

§ Module Requirements

All VPR modules MUST, at least, provide:

• A keeper(s), used to access the module’s store(s) and update the state.
• A Msg service, used to process messages when they are routed to the module by BaseApp and trigger state-transitions.
• A query service, used to process user queries.
• Interfaces, for end users to query the subset of the state defined by the module and create messages of the custom types defined in the module.

Note about Query REST API:

• all query methods MUST return valid JSON.
• objects MUST be nested when needed, such as when returning a trust registry.
• JSON formatting MUST obey to data model regarding attribute names. A method that returns a TrustRegistry entry MUST return an entry called “trust_registry”. A method that returns a list of Trust Registries MUST return an entry called “trustRegistries” that contain a list of TrustRegistry entries.

Examples:

Get a TrustRegistry

"trust_registry": {
  {
    "active_version": 0,
    "aka": "string",
    "controller": "string",
    "created": "2025-01-14T19:40:37.967Z",
    "deposit": "string",
    "did": "string",
    "id": "string",
    "language": "string",
    "modified": "2025-01-14T19:40:37.967Z",
    "versions": [
      {
        "active_since": "2025-01-14T19:40:37.967Z",
        "created": "2025-01-14T19:40:37.967Z",
        "id": "string",
        "tr_id": "string",
        "version": 0,
        "documents": [
          {
            "created": "2025-01-14T19:40:37.967Z",
            "gfv_id": "string",
            "digest_sri": "string",
            "id": "string",
            "language": "string",
            "url": "string"
          }
        ]
      }
    ]  
  }

"trustRegistries": [ {
  {
    "active_version": 0,
    "aka": "string",
    "controller": "string",
    "created": "2025-01-14T19:40:37.967Z",
    "deposit": "string",
    "did": "string",
    "id": "string",
    "language": "string",
    "modified": "2025-01-14T19:40:37.967Z",
    "versions": [
      {
        "active_since": "2025-01-14T19:40:37.967Z",
        "created": "2025-01-14T19:40:37.967Z",
        "id": "string",
        "tr_id": "string",
        "version": 0,
        "documents": [
          {
            "created": "2025-01-14T19:40:37.967Z",
            "gfv_id": "string",
            "digest_sri": "string",
            "id": "string",
            "language": "string",
            "url": "string"
          }
        ]
      }
    ]  
  }, {
    "active_version": 0,
    "aka": "string",
    "controller": "string",
    "created": "2025-01-14T19:40:37.967Z",
    "deposit": "string",
    "did": "string",
    "id": "string",
    "language": "string",
    "modified": "2025-01-14T19:40:37.967Z",
    "versions": [
      {
        "active_since": "2025-01-14T19:40:37.967Z",
        "created": "2025-01-14T19:40:37.967Z",
        "id": "string",
        "tr_id": "string",
        "version": 0,
        "documents": [
          {
            "created": "2025-01-14T19:40:37.967Z",
            "gfv_id": "string",
            "digest_sri": "string",
            "id": "string",
            "language": "string",
            "url": "string"
          }
        ],
      }
    ]  
  }
]

A VPR implementation MUST implement all the following requirements.

§ Trust Registry Module

§ [MOD-TR-MSG-1] Create New Trust Registry

Any account CAN execute this method.

§ [MOD-TR-MSG-1-1] Create New Trust Registry parameters

An account that would like to create a trust registry MUST call this method by specifying:

• did (string) (mandatory): the did of the ecosystem that is creating the trust registry.
• aka (string) (optional): optional additional URI of this trust registry.
• language (string(17)) (mandatory): primary language tag (rfc1766) of this trust registry.
• doc_url (string) (mandatory): URL where the document is published.
• doc_digest_sri (string) (mandatory): digest_sri of the document.

Provided document must be of the same language that the primary language of the trust registry.

§ [MOD-TR-MSG-1-2] Create New Trust Registry precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-TR-MSG-1-2-1] Create New Trust Registry basic checks

• if a mandatory parameter is not present, method MUST abort.

• did (string) (mandatory): MUST conform to the DID Syntax, as specified [DID-CORE].

• aka (string) (optional): optional additional URI of this trust registry. MUST be an URI.

• language (string(17)) (mandatory): MUST be a language tag (rfc1766).

• doc_url (string) (mandatory): MUST be a valid URL .

• doc_digest_sri (string) (mandatory): MUST be a valid digest_sri as specified in integrity of related resources spec. Example: sha384-MzNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26.

§ [MOD-TR-MSG-1-2-2] Create New Trust Registry fee checks

Applicant MUST have an available balance in its account, to cover the following:

• the required estimated transaction fees in its account.
• the required trust_deposit_in_denom: GlobalVariables.trust_registry_trust_deposit * GlobalVariables.trust_unit_price.

§ [MOD-TR-MSG-1-3] Create New Trust Registry execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• use [MOD-TD-MSG-1] to increase by trust_deposit_in_denom: GlobalVariables.trust_registry_trust_deposit * GlobalVariables.trust_unit_price the trust deposit of account running the method and transfer the corresponding amount to TrustDeposit module.

• create and persist a new TrustRegistry entry tr:

• tr.id : auto-incremented uint64

• tr.did: did

• tr.controller: account running the method

• tr.created: current timestamp

• tr.modified: tr.created

• tr.aka: aka

• tr.language: language

• tr.active_version: 1

• tr.deposit: trust_deposit_in_denom

• create and persist a new GovernanceFrameworkVersion entry gfv:

• gfv.id: auto-incremented uint64

• gfv.tr_id: tr.id

• gfv.created: current timestamp

• gfv.version: 1

• gfv.active_since: current timestamp

• create and persist a new GovernanceFrameworkDocument entry gfd:

• gfd.id: auto-incremented uint64

• gfd.gfv_id: gfv.id

• gfd.created: current timestamp

• gfd.language: language

• gfd.url: doc_url

• gfd.digest_sri: doc_digest_sri

§ [MOD-TR-MSG-2] Add Governance Framework Document

Any account CAN execute this method.

§ [MOD-TR-MSG-2-1] Add Governance Framework Document parameters

An account that would like to add a governance framework document MUST call this method by specifying:

• tr_id (uint64) (mandatory): the id of the trust registry.
• doc_language (string(2)) (mandatory): language tag (rfc1766) of the EGF document, provided by the EGA.
• doc_url (string) (mandatory): URL where the document is published.
• doc_digest_sri (string) (mandatory): digest_sri of the document.
• version (int) (mandatory): targeted version.

If for a given language, a document already exists, the execution of this transaction would replace the corresponding entry. Else, a new entry is created.

§ [MOD-TR-MSG-2-2] Add Governance Framework Document precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-TR-MSG-2-2-1] Add Governance Framework Document basic checks

• if a mandatory parameter is not present, method MUST abort.

• id (uint64) (mandatory): a TrustRegistry entry with this id MUST exist and account executing the method MUST be the controller of the TrustRegistry entry.

• version: there MUST exist a GovernanceFrameworkVersion entry gfv where gfv.tr_id is equal to id and gfv.version = version, or version MUST be exactly equal to the biggest found gfv.version + 1 of all GovernanceFrameworkVersion entries found for this gfv.tr_id equal to id. version MUST be greater than the tr.active_version.

• doc_language (string(2)) (mandatory): MUST be a language tag (rfc1766).

• doc_url (string) (mandatory): MUST be a valid URL.

• doc_digest_sri (string) (mandatory): MUST be a valid digest_sri as specified in integrity of related resources spec. Example: sha384-MzNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26.

§ [MOD-TR-MSG-2-2-2] Add Governance Framework Document fee checks

Account MUST have the required estimated transaction fees in its account.

§ [MOD-TR-MSG-2-3] Add Governance Framework Document execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

load GovernanceFrameworkVersion entry gfv for the requested version, or create a new GovernanceFrameworkVersion gfv if required:

• gfv.id: auto-incremented uint64

• gfv.tr_id: id

• gfv.created: current timestamp

• gfv.version: 1

• gfv.active_since: null

• create and persist or (replace if already exist) a GovernanceFrameworkDocument entry gfd:

• gfd.id: auto-incremented uint64

• gfd.gfv_id: gfv.id

• gfd.created: current timestamp

• gfd.language: doc_language

• gfd.url: doc_url

• gfd.digest_sri: doc_digest_sri

§ [MOD-TR-MSG-3] Increase Active Governance Framework Version

Any account CAN execute this method.

§ [MOD-TR-MSG-3-1] Increase Active Governance Framework Version parameters

An account that would like to add a governance framework document MUST call this method by specifying:

• id (uint64) (mandatory): the id of the trust registry.

§ [MOD-TR-MSG-3-2] Increase Active Governance Framework Version precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-TR-MSG-3-2-1] Increase Active Governance Framework Version basic checks

• if a mandatory parameter is not present, method MUST abort.

• id (uint64) (mandatory): a TrustRegistry entry with this id MUST exist and account executing the method MUST be the controller of the TrustRegistry entry.

• load TrustRegistry entry tr from its id. Find a GovernanceFrameworkVersion entry gfv where version is equal to tr.active_version + 1. If none is found, transaction MUST abort.

• find GovernanceFrameworkDocument gfd for gfd.gfv_id = gfv.id and gfd.language = tr.language. If no document is found (and thus no document exist for the default language of this version for this trust registry), transaction MUST abort.

§ [MOD-TR-MSG-3-2-2] Increase Active Governance Framework Version fee checks

Account MUST have the required estimated transaction fees in its account.

§ [MOD-TR-MSG-3-3] Increase Active Governance Framework Version execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• load TrustRegistry entry tr from its id. Find a GovernanceFrameworkVersion entry gfv where version is equal to tr.active_version + 1. If none is found, transaction MUST abort. Else, update tr.active_version to tr.active_version + 1. Set tr.modified to current timestamp, and set gfv.active_since to current timestamp and persist changes.

§ [MOD-TR-MSG-4] Update Trust Registry

Any account CAN execute this method.

§ [MOD-TR-MSG-4-1] Update Trust Registry parameters

An account that would like to update a trust registry MUST call this method by specifying:

• id (uint64) (mandatory): the id of the trust registry.
• did (string) (mandatory): the did of the trust registry.
• aka (string) (optional): optional additional URI of this trust registry. If null, it means replace existing value with null.

§ [MOD-TR-MSG-4-2] Update Trust Registry precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-TR-MSG-4-2-1] Update Trust Registry basic checks

• if a mandatory parameter is not present, method MUST abort.

• id (uint64) (mandatory): a TrustRegistry entry tr with id id MUST exist and account executing the method MUST be the controller of the TrustRegistry entry tr.

• did (string) (mandatory): MUST conform to the DID Syntax, as specified [DID-CORE].

• aka (string) (optional): optional additional URI of this trust registry. MUST be an URI or null.

§ [MOD-TR-MSG-4-2-2] Update Trust Registry fee checks

Applicant MUST have an available balance in its account, to cover the required transaction fees.

§ [MOD-TR-MSG-4-3] Update Trust Registry execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• load TrustRegistry entry tr from id and set:

• tr.did: did

• tr.aka: aka

• tr.modified: current timestamp

§ [MOD-TR-MSG-5] Archive Trust Registry

Any account CAN execute this method.

§ [MOD-TR-MSG-5-1] Archive Trust Registry parameters

An account that would like to archive or unarchive a trust registry MUST call this method by specifying:

• id (uint64) (mandatory) id of the trust registry (mandatory);
• archive (boolean) (mandatory), true means archive, false means unarchive.

§ [MOD-TR-MSG-5-2] Archive Trust Registry precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-TR-MSG-5-2-1] Archive Trust Registry basic checks

• if a mandatory parameter is not present, method MUST abort.

• load TrustRegistry tr from id. tr.controller MUST be the account executing the method, else MUST abort.

• archive (boolean) (mandatory) MUST be a boolean.

  • If archive is true and tr.archived is not null, MUST abort as TrustRegistry is already archived.
  • If archive is false and tr.archived is null, MUST abort as TrustRegistry is already not archived.

§ [MOD-TR-MSG-5-2-2] Archive Trust Registry fee checks

Account MUST have an available balance in its account to cover the required transaction fees.

§ [MOD-TR-MSG-5-3] Archive Trust Registry execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• update TrustRegistry entry tr with tr.id equal to id:
• if archived is true: set cs.archived to current timestamp.
• if archived is false: set cs.archived to null.
• tr.modified: current timestamp

§ [MOD-TR-MSG-6] Update Module Parameters

Update Module Parameters.

Can only be executed through a governance proposal.

§ [MOD-TR-MSG-6-1] Update Module Parameters parameters

• params (KeySet<String, String>): the parameters to update and their values.

§ [MOD-TR-MSG-6-2] Update Module Parameters precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-TR-MSG-6-2-1] Update Module Parameters basic checks

• params: size of params MUST be greater than 0. For each param <key, value> key MUST exist, else abort.

§ [MOD-TR-MSG-6-2-2] Update Module Parameters fee checks

provided transaction fees MUST be sufficient for execution

§ [MOD-TR-MSG-6-3] Update Module Parameters execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

for each parameter param <key, value> in parameters:

• update parameter set value = value where key = key.

§ [MOD-TR-QRY-1] Get Trust Registry

Anyone CAN execute this method.

§ [MOD-TR-QRY-1-1] Get Trust Registry parameters

• id (uint64) (mandatory): id of the trust registry.
• active_gf_only (boolean) (optional): if true, include only current governance framework data. If false or null, returns everything.
• preferred_language (string) (optional): if set, return only one document per version, with language=preferred_language when possible, else if no document exist with this language, return language. If not set, return all documents of all languages.

§ [MOD-TR-QRY-1-2] Get Trust Registry checks

§ [MOD-TR-QRY-1-3] Get Trust Registry execution

return found TrustRegistry entry (if any), as well as all its nested GovernanceFrameworkVersion and GovernanceFrameworkDocument entries. If latest_gf_only is true, return only nested GovernanceFrameworkVersion and GovernanceFrameworkDocument entries for the active version.

§ [MOD-TR-QRY-2] List Trust Registries

This method is used to query the DID Directory keeper. Returned result MUST be ordered by TrustRegistry.modified asc.

§ [MOD-TR-QRY-2-1] List Trust Registries query parameters

The following parameters are optional:

• controller (account) (optional): if specified, filter by controller.
• modified_after (timestamp) (optional): if specified, returns only TrustRegistry entries with TrustRegistry.modified greater than modified.
• active_gf_only (boolean) (optional): if true, include only current governance framework data. If false or null, returns everything.
• preferred_language (string) (optional): if set, return only one document per version, with language=preferred_language when possible, else if no document exist with this language, return language. If not set, return all documents of all languages.
• response_max_size (small number) (optional): default to 64. Max 1,024.

§ [MOD-TR-QRY-2-2] List Trust Registries query checks

If any of these checks fail, query MUST fail.

• response_max_size must be between 1 and 1,024. Default to 64 if unspecified.

§ [MOD-TR-QRY-2-3] List Trust Registries execution of the query

If all precondition checks passed, query is executed and result (may be empty) returned. If modified_after is specified, order by modified_after desc.

§ [MOD-TR-QRY-3] List Module Parameters

Anyone CAN run this query.

§ [MOD-TR-QRY-3-2] List Module Parameters parameters

§ [MOD-TR-QRY-3-2] List Module Parameters query checks

§ [MOD-TR-QRY-3-3] List Module Parameters execution of the query

Return the list of the existing parameters and their values.

§ [MOD-TR-QRY-3-4] List Module Parameters API result example

{
  "params": {
    "key1": "value1",
    "key2": "value2",
    ...
    ...
  }
}

§ Credential Schema Module

§ [MOD-CS-MSG-1] Create New Credential Schema

Any account CAN execute this method.

§ [MOD-CS-MSG-1-1] Create New Credential Schema parameters

An account that would like to create a credential schema MUST call this method by specifying:

• tr_id id of the trust registry (mandatory);
• json_schema the Json Schema of the credential (mandatory).
• issuer_grantor_validation_validity_period (mandatory), default to 0 (days).
• verifier_grantor_validation_validity_period (mandatory), default to 0 (days).
• issuer_validation_validity_period (mandatory), default to 0 (days).
• verifier_validation_validity_period (mandatory), default to 0 (days).
• holder_validation_validity_period (mandatory), default to 0 (days).
• issuer_perm_management_mode (PermissionManagementMode) (mandatory).
• verifier_perm_management_mode (PermissionManagementMode) (mandatory).

§ [MOD-CS-MSG-1-2] Create New Credential Schema precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-CS-MSG-1-2-1] Create New Credential Schema basic checks

• if a mandatory parameter is not present, method MUST abort.
• tr_id MUST represent an existing TrustRegistry entry tr and tr.controller MUST be the account executing the method.
• json_schema MUST be a valid Json Schema, and size must not be greater than GlobalVariables.credential_schema_schema_max_size. $id of the Json Schema must be a valid https URL that terminates with string /cs/v1/js/VPR_CREDENTIAL_SCHEMA_ID as specified in [MOD-CS-QRY-3]. VPR_CREDENTIAL_SCHEMA_ID will be replaced during execution by the auto-generated id of this CredentialSchema.
• issuer_grantor_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_issuer_grantor_validation_validity_period_max_days days.
• verifier_grantor_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_verifier_grantor_validation_validity_period_max_days days.
• issuer_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_issuer_validation_validity_period_max_days days.
• verifier_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_verifier_validation_validity_period_max_days days.
• holder_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_holder_validation_validity_period_max_days days.
• issuer_perm_management_mode (PermissionManagementMode) (mandatory) MUST be a valid PermissionManagementMode.
• verifier_perm_management_mode (PermissionManagementMode) (mandatory) MUST be a valid PermissionManagementMode.

§ [MOD-CS-MSG-1-2-2] Create New Credential Schema fee checks

Applicant MUST have an available balance in its account, to cover the following fees:

• the required estimated transaction fees in its account.
• the required trust_deposit_in_denom: GlobalVariables.credential_schema_trust_deposit * GlobalVariables.trust_unit_price.

§ [MOD-CS-MSG-1-3] Create New Credential Schema execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• use [MOD-TD-MSG-1] to increase by trust_deposit_in_denom: GlobalVariables.trust_registry_trust_deposit * GlobalVariables.trust_unit_price the trust deposit of account running the method and transfer the corresponding amount to TrustDeposit module.

• create and persist a new CredentialSchema entry cs:

  • cs.id: auto-incremented uint64.
  • cs.tr_id: id of the TrustRegistry entry that will be the owner of cs.
  • cs.json_schema: json_schema, with VPR_CREDENTIAL_SCHEMA_ID string replaced by generated cs.id.
  • cs.issuer_grantor_validation_validity_period: issuer_grantor_validation_validity_period
  • cs.verifier_grantor_validation_validity_period: verifier_grantor_validation_validity_period
  • cs.issuer_validation_validity_period: issuer_validation_validity_period
  • cs.verifier_validation_validity_period: verifier_validation_validity_period
  • cs.holder_validation_validity_period: holder_validation_validity_period
  • cs.issuer_perm_management_mode: issuer_perm_management_mode
  • cs.verifier_perm_management_mode: verifier_perm_management_mode
  • cs.created: current timestamp
  • cs.modified: cs.created.

§ [MOD-CS-MSG-2] Update Credential Schema

Any account CAN execute this method.

§ [MOD-CS-MSG-2-1] Update Credential Schema parameters

An account that would like to update a credential schema MUST call this method by specifying:

• id id of the credential schema (mandatory);
• issuer_grantor_validation_validity_period (mandatory), default to 0 (days).
• verifier_grantor_validation_validity_period (mandatory), default to 0 (days).
• issuer_validation_validity_period (mandatory), default to 0 (days).
• verifier_validation_validity_period (mandatory), default to 0 (days).
• holder_validation_validity_period (mandatory), default to 0 (days).

other attributes are immutables and cannot be updated.

§ [MOD-CS-MSG-2-2] Update Credential Schema precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-CS-MSG-2-2-1] Update Credential Schema basic checks

• if a mandatory parameter is not present, method MUST abort.

• id MUST represent an existing CredentialSchema entry cs.

• load TrustRegistry tr from cs.tr_id. tr.controller MUST be the account executing the method, else MUST abort.

• issuer_grantor_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_issuer_grantor_validation_validity_period_max_days days.

• verifier_grantor_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_verifier_grantor_validation_validity_period_max_days days.

• issuer_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_issuer_validation_validity_period_max_days days.

• verifier_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_verifier_validation_validity_period_max_days days.

• holder_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_holder_validation_validity_period_max_days days.

§ [MOD-CS-MSG-2-2-2] Update Credential Schema fee checks

Account MUST have an available balance in its account to cover the required transaction fees.

§ [MOD-CS-MSG-2-3] Update Credential Schema execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• update CredentialSchema entry cs with cs.id equal to id:

  • cs.issuer_grantor_validation_validity_period: issuer_grantor_validation_validity_period
  • cs.verifier_grantor_validation_validity_period: verifier_grantor_validation_validity_period
  • cs.issuer_validation_validity_period: issuer_validation_validity_period
  • cs.verifier_validation_validity_period: verifier_validation_validity_period
  • cs.holder_validation_validity_period: holder_validation_validity_period
  • cs.updated: current timestamp.

§ [MOD-CS-MSG-3] Archive Credential Schema

Any account CAN execute this method.

§ [MOD-CS-MSG-3-1] Archive Credential Schema parameters

An account that would like to archive or unarchive a credential schema MUST call this method by specifying:

• id (uint64) (mandatory) id of the credential schema (mandatory);
• archive (boolean) (mandatory), true means archive, false means unarchive.

§ [MOD-CS-MSG-3-2] Archive Credential Schema precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-CS-MSG-3-2-1] Archive Credential Schema basic checks

• if a mandatory parameter is not present, method MUST abort.

• id MUST represent an existing CredentialSchema entry cs.

• load TrustRegistry tr from cs.tr_id. tr.controller MUST be the account executing the method, else MUST abort.

• archive (boolean) (mandatory) MUST be a boolean.

  • If archive is true and cs.archived is not null, MUST abort as Credential Schema is already archived.
  • If archive is false and cs.archived is null, MUST abort as Credential Schema is already not archived.

§ [MOD-CS-MSG-3-2-2] Archive Credential Schema fee checks

Account MUST have an available balance in its account to cover the required transaction fees.

§ [MOD-CS-MSG-3-3] Archive Credential Schema execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• update CredentialSchema entry cs with cs.id equal to id:

• if archived is true: set cs.archived to current timestamp.

• if archived is false: set cs.archived to null.

• set cs.modified to current timestamp.

§ [MOD-CS-MSG-4] Update Module Parameters

Update Module Parameters.

Can only be executed through a governance proposal.

§ [MOD-CS-MSG-4-1] Update Module Parameters parameters

• params (KeySet<String, String>): the parameters to update and their values.

§ [MOD-CS-MSG-4-2] Update Module Parameters precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-CS-MSG-4-2-1] Update Module Parameters basic checks

• params: size of params MUST be greater than 0. For each param <key, value> key MUST exist, else abort.

§ [MOD-CS-MSG-4-2-2] Update Module Parameters fee checks

provided transaction fees MUST be sufficient for execution

§ [MOD-CS-MSG-4-3] Update Module Parameters execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

for each parameter param <key, value> in parameters:

• update parameter set value = value where key = key.

§ [MOD-CS-QRY-1] List Credential Schemas

Anyone CAN execute this method. Returned result MUST be ordered by CredentialSchema.created asc.

§ [MOD-CS-QRY-1-1] List Credential Schemas parameters

• tr_id (string) (optional): to filter by trust registry id.
• modified_after (timestamp) (optional): show schemas modified after this timestamp.
• response_max_size (small number) (optional): default to 64. Max 1,024.
• only_active (boolean): if set to true, returns only not archived entries.
• issuer_perm_management_mode (PermissionManagementMode): if set, filter by issuer_perm_management_mode.
• verifier_perm_management_mode (PermissionManagementMode): if set, filter by verifier_perm_management_mode.

§ [MOD-CS-QRY-1-2] List Credential Schemas checks

• modified_after must be a timestamp.
• response_max_size must be between 1 and 1,024.

§ [MOD-CS-QRY-1-3] List Credential Schemas execution

return a list of found entry, or an empty list if nothing found. Results MUST be ordered by modified ASC.

§ [MOD-CS-QRY-2] Get Credential Schema

Anyone CAN execute this method.

§ [MOD-CS-QRY-2-1] Get Credential Schema parameters

• id of the credential schema (mandatory);

§ [MOD-CS-QRY-2-2] Get Credential Schema checks

• id must be a uint64.

§ [MOD-CS-QRY-2-3] Get Credential Schema execution

return found entry (if any).

§ [MOD-CS-QRY-3] Render Json Schema

Anyone CAN execute this method.

§ [MOD-CS-QRY-3-1] Render Json Schema parameters

• id of the credential schema (mandatory);

§ [MOD-CS-QRY-3-2] Render Json Schema checks

• id must be a uint64.

§ [MOD-CS-QRY-3-3] Render Json Schema execution

Render found entry (if any). In case value is returned by a REST API, content type MUST be set to “application/schema+json”.

§ [MOD-CS-QRY-4] List Module Parameters

Anyone CAN run this query.

§ [MOD-CS-QRY-4-2] List Module Parameters parameters

§ [MOD-CS-QRY-4-2] List Module Parameters query checks

§ [MOD-CS-QRY-4-3] List Module Parameters execution of the query

Return the list of the existing parameters and their values.

§ [MOD-CS-QRY-4-4] List Module Parameters API result example

{
  "params": {
    "key1": "value1",
    "key2": "value2",
    ...
    ...
  }
}

§ Permission Module

§ Permission Module Overview

This section is non-normative.

Permission are linked to a Credential Schema and representable as a tree.

The ECOSYSTEM type permissions are created by the Credential Schema owner. All other permissions are created by running a Validation Process (or by any account: - for ISSUER permissions if issuer_perm_management_mode is equal to OPEN, - for VERIFIER permissions if verifier_perm_management_mode is equal to OPEN).

A Validation Process (VP) is a process which involves an applicant (which is the controller of validation entry stored in a validation keeper), a validator permission, and optional fees plus transaction fees.

Validation is used by applicants that want to:

• be an issuer of a specific credential schema;
• be a verifier of a specific credential schema;
• be an issuer grantor of a specific credential schema;
• be a verifier grantor of a specific credential schema;
• get issued a credential of a specific credential schema;
• optionally get created a HOLDER permission (HOLDER permission may be used in combination with credentials, example for User Agent credentials).

In all cases, the process is very similar. Example execution of a validation process:

1. Applicant starts a validation process by running the [start new validation] transaction. Validation process may be subject to paying validation fees, as defined by validator.
2. Validation process usually requires that applicant connects to a validation VS identified by its DID, and execute a some validation steps, required for the validation process to conclude.
3. If applicant qualifies, validator updates the validation entry by running the [set to validated] transaction, and applicant is granted new permissions, and/or gets issued a credential.

Validation is valid for a specific period, for example 365 days, as configured in the credential schema for credential schema related validations, or set by trust registry for user-agent validation.

If validation is set to expire, applicant that wishes to extend the expiration timestamp must renew its validation.

At any time, applicant can cancel the validation process.

Some special unexpected situation may arise and must be mitigated. Examples:

• if selected validator permission is revoked while applicant’s validation is in PENDING state: Applicant CAN cancel the validation process [MOD-PERM-MSG-6].
• if selected validator permission is revoked while applicant is in VALIDATED state: Applicant CAN renew the validation process by choosing a new validator [MOD-PERM-MSG-2].
• if selected validator permission is revoked while applicant is in TERMINATION_REQUESTED state and validator action is required: applicant MUST be able to set the validation state to TERMINATED.

§ [MOD-PERM-MSG-1] Start Permission VP

Any account CAN execute this method.

§ [MOD-PERM-MSG-1-1] Start Permission VP parameters

An Applicant that would like to start a permission validation process MUST execute this method by specifying:

• type (PermissionType) (mandatory): (ISSUER_GRANTOR, VERIFIER_GRANTOR, ISSUER, VERIFIER, HOLDER): the permission that the applicant would like to get;
• validator_perm_id (uint64) (mandatory): the validator permission (parent permission in the tree), chosen by the applicant.
• country (string) (mandatory): a country of residence, alpha-2 code (ISO 3166), where applicant is located.

Available compatible perms can be found by using an indexer and presented in a front-end so applicant can choose its validator.

§ [MOD-PERM-MSG-1-2] Start Permission VP precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-1-2-1] Start Permission VP basic checks

if a mandatory parameter is not present, transaction MUST abort.

• type (PermissionType) (mandatory) MUST be a valid PermissionType: ISSUER_GRANTOR, VERIFIER_GRANTOR, ISSUER, VERIFIER, HOLDER.
• validator_perm_id (uint64) (mandatory): see MOD-PERM-MSG-1-2-2.
• country (string) (mandatory) MUST be a valid alpha-2 code (ISO 3166).
• did, if specified, MUST conform to the DID Syntax, as specified [DID-CORE].

§ [MOD-PERM-MSG-1-2-2] Start Permission VP permission checks

• Load Permission entry validator_perm from validator_perm_id. It MUST be a valid permission AND (validator_perm.country MUST be equal to country, or validator_perm.country MUST be null), else transaction MUST abort.

• Load CredentialSchema entry cs from validator_perm.schema_id. It MUST exist.

• if type (PermissionType) is equal to ISSUER:

  • if cs.issuer_perm_management_mode is equal to GRANTOR: validator_perm.type MUST be ISSUER_GRANTOR, else MUST abort.

  • else if cs.issuer_perm_management_mode is equal to ECOSYSTEM: validator_perm.type MUST be ECOSYSTEM, else MUST abort.

  • else MUST abort.

• else if type (PermissionType) is equal to ISSUER_GRANTOR:

  • if cs.issuer_perm_management_mode is equal to GRANTOR: validator_perm.type MUST be ECOSYSTEM, else MUST abort.

  • else abort.

• else if type (PermissionType) is equal to VERIFIER:

  • if cs.verifier_perm_management_mode is equal to GRANTOR: validator_perm.type MUST be VERIFIER_GRANTOR, else MUST abort.

  • else if cs.verifier_perm_management_mode is equal to ECOSYSTEM: validator_perm.type MUST be ECOSYSTEM, else MUST abort.

  • else abort.

• else if type (PermissionType) is equal to VERIFIER_GRANTOR:

  • if cs.verifier_perm_management_mode is equal to GRANTOR: validator_perm.type MUST be ECOSYSTEM, else MUST abort.

  • else abort.

• else if type (PermissionType) is equal to HOLDER:

  • if cs.verifier_perm_management_mode is equal to GRANTOR or ECOSYSTEM: validator_perm.type MUST be ISSUER, else MUST abort.

  • else abort.

At the end, if a valid permission validator_perm is not found, transaction MUST abort.

§ [MOD-PERM-MSG-1-2-3] Start Permission VP fee checks

Load Permission entry validator_perm of the selected validator.

Applicant MUST have an available balance in its account, to cover the following fees:

• the required estimated transaction fees;
• the required validation_fees_in_denom: validator_perm.validation_fees * GlobalVariables.trust_unit_price.
• the required validation_trust_deposit_in_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate.

§ [MOD-PERM-MSG-1-3] Start Permission VP execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• Load Permission entry validator_perm of the selected validator.

• calculate validation_fees_in_denom: validator_perm.validation_fees * GlobalVariables.trust_unit_price.

• calculate validation_trust_deposit_in_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate.

• use [MOD-TD-MSG-1] to increase by validation_trust_deposit_in_denom the trust deposit of account running the method and transfer the corresponding amount to TrustDeposit module.

• send validation_fees_in_denom to validation escrow account, if greater than 0.

• define now: current timestamp.

• create an persist a new permission entry applicant_perm:

  • applicant_perm.id: auto-incremented uint64.
  • applicant_perm.grantee: applicant's account.
  • applicant_perm.type: type.
  • applicant_perm.created: now
  • applicant_perm.modified: now
  • applicant_perm.deposit: validation_trust_deposit_in_denom.
  • applicant_perm.validation_fees: 0.
  • applicant_perm.issuance_fees: 0.
  • applicant_perm.verification_fees: 0.
  • applicant_perm.validator_perm_id: validator_perm_id.
  • applicant_perm.vp_last_state_change: now
  • applicant_perm.vp_state: PENDING.
  • applicant_perm.vp_current_fees (number): validation_fees_in_denom.
  • applicant_perm.vp_current_deposit (number): validation_trust_deposit_in_denom.
  • applicant_perm.vp_summary_digest_sri: null.
  • applicant_perm.vp_term_requested: null.
  • applicant_perm.vp_validator_deposit: 0.

§ Connecting to the VS of the Validator

This section is non-normative, and provided for understanding only.

This action must be initiated by the applicant.

During a validation process, if the associated validator_perm includes a specific did, the applicant should establish a secure connection with the validator’s VS (Verifiable Service) using a secure communication protocol such as DIDComm or DWN.

Upon connecting to the VS, the applicant should be required by the validator to complete one or more of the following tasks:

1. Prove control over the controller account that initiated the validation process (e.g., via blind signature or cryptographic challenge).
2. Provide requested information, such as filling out forms, submitting documents, or other forms of disclosure as required by the validation VS.
3. If the requested permission includes a VS DID, the applicant should prove control over the corresponding DID to the validator’s VS.

Once the validator determines that the process is complete, they may terminate the validation process and create the permission accordingly. This permission configuration usually include:

• validation_fees
• issuance_fees
• verification_fees
• country (jurisdictional scope)
• permission expiration

The validator may compile a summary file of the validation process, documenting exchanged data, proofs, and decisions, and share it with the applicant via the VS connection or another secure channel.

For audit or governance purposes, the validator should register a digest (e.g., hash or SRI) of this summary in applicant_perm.vp_summary_digest_sri.

§ [MOD-PERM-MSG-2] Renew Permission VP

This section is non-normative.

• Requesting a renewal has no effect on permission expiration or issued credentials.
• Renewal is only possible with the same validator.
• If validator permission is not valid anymore, applicant MUST perform a new validation process with another validator.
• Renewal does not allow changing the perm.country, perm.validation_fees, perm.issuance_fees, perm.verification_fees. To change these values, applicant MUST start a new validation process.

§ [MOD-PERM-MSG-2-1] Renew Permission VP parameters

An account controller of a permission entry that would like to renew a validation process for this permission MUST execute this method by specifying:

• id (uint64) (mandatory): id of the permission for which applicant would like to renew the validation process;

§ [MOD-PERM-MSG-2-2] Renew Permission VP precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-2-2-1] Renew Permission VP basic checks

if a mandatory parameter is not present, transaction MUST abort.

• id MUST be a valid uint64 and a permission entry with the same id MUST exist.

§ [MOD-PERM-MSG-2-2-2] Renew Permission VP permission checks

• Load Permission entry applicant_perm. account running the operation MUST be applicant_perm.grantee, else MUST abort. applicant_perm MUST be a valid permission.
• Load Permission entry validator_perm from applicant_perm.validator_perm_id. It MUST exist, and be a valid permission, else MUST abort.

§ [MOD-PERM-MSG-2-2-3] Renew Permission VP fee checks

• Load Permission entry validator_perm from applicant_perm.validator_perm_id.

Applicant MUST have an available balance in its account, to cover the following fees:

• the required estimated transaction fees;
• the required validation_fees_in_denom: validator_perm.validation_fees * GlobalVariables.trust_unit_price.
• the required validation_trust_deposit_in_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate.

§ [MOD-PERM-MSG-2-3] Renew Permission VP execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• Load Permission entry applicant_perm.

• Load Permission entry validator_perm from applicant_perm.validator_perm_id.

• calculate validation_fees_in_denom: validator_perm.validation_fees * GlobalVariables.trust_unit_price.

• calculate validation_trust_deposit_in_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate.

• use [MOD-TD-MSG-1] to increase by validation_trust_deposit_in_denom the trust deposit of account running the method and transfer the corresponding amount to TrustDeposit module.

• send validation_fees_in_denom to validation escrow account, if greater than 0.

• define now: current timestamp.

• update permission entry:

  • applicant_perm.vp_state: PENDING.
  • applicant_perm.vp_last_state_change: current timestamp.
  • applicant_perm.deposit: applicant_perm.applicant_deposit + validation_trust_deposit_in_denom.
  • applicant_perm.vp_current_fees (number): validation_fees_in_denom.
  • applicant_perm.vp_current_deposit (number): validation_trust_deposit_in_denom.
  • applicant_perm.modified: now

§ [MOD-PERM-MSG-3] Set Permission VP to Validated

Any account CAN execute this method.

§ [MOD-PERM-MSG-3-1] Set Permission VP to Validated parameters

An account that would like to set a validation entry to VALIDATED MUST execute this method by specifying:

• id (uint64) (mandatory): id of the validation process;
• effective_until (timestamp) (optional): timestamp until when (exclusive) this Permission is effective, null if no time limit should been set for this permission or if we want it to be aligned with the validation process expiration timestamp calculated by this method.
• validation_fees (number) (optional): Agreed validation_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals).
• issuance_fees (number) (optional): Agreed issuance_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals).
• verification_fees (number) (optional): Agreed verification_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals).
• country (string) (optional): country, as an alpha-2 code (ISO 3166), this permission refers to. If null, it means permission is not linked to a specific country. Can be set only the first time this method is called (cannot be set for renewals).
• vp_summary_digest_sri (digest_sri) (optional): an optional digest_sri, set by validator, of a summary of the information, proofs… provided by the applicant.

§ [MOD-PERM-MSG-3-2] Set Permission VP to Validated precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-3-2-1] Set Permission VP to Validated basic checks

if a mandatory parameter is not present, transaction MUST abort.

• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.
• applicant_perm.vp_state MUST be equal to PENDING, else abort.
• validation_fees (number) (optional): If specified, MUST be zero or a positive number. If applicant_perm.effective_from is not null (we are in renewal) validation_fees MUST be equal to applicant_perm.validation_fees, else abort.
• issuance_fees (number) (optional): If specified, MUST be zero or a positive number. If applicant_perm.effective_from is not null (we are in renewal) issuance_fees MUST be equal to applicant_perm.issuance_fees or, else abort.
• verification_fees (number) (optional): If specified, MUST be zero or a positive number. If applicant_perm.effective_from is not null (we are in renewal) verification_fees MUST be equal to applicant_perm.verification_fees, else abort.
• country (string) (optional): MUST be a valid alpha-2 code (ISO 3166), or null. If applicant_perm.effective_from is not null (we are in renewal) country MUST be equal to applicant_perm.country, else abort.
• vp_summary_digest_sri (digest_sri) (optional): MUST be null if validation.type is set to HOLDER (for HOLDER, proofs can be stored in credentials). Else, MUST be a valid digest_sri as specified in integrity of related resources spec. Example: sha384-MzNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26.

Calculation of vp_exp, the validation process expiration timestamp, required to verify provided effective_until:

• Load CredentialSchema cs from applicant_perm.schema_id.

• let’s define validity_period = cs.issuer_grantor_validation_validity_period (if applicant_perm.type is ISSUER_GRANTOR), cs.verifier_grantor_validation_validity_period (if applicant_perm.type is VERIFIER_GRANTOR), cs.issuer_validation_validity_period (if applicant_perm.type is ISSUER), cs.verifier_validation_validity_period (if applicant_perm.type is VERIFIER), or cs.holder_validation_validity_period (if applicant_perm.type is HOLDER).

• if validity_period is NULL: vp_exp = NULL.

• else if applicant_perm.vp_exp is null, vp_exp = timestamp of now() plus validity_period.

• else vp_exp = applicant_perm.vp_exp plus validity_period

Now, let’s verify effective_until:

• if effective_until is NULL, no issue.
• else if applicant_perm.effective_until is NULL, effective_until MUST be greater than current current timestamp AND, if vp_exp is not null, lower or equal to vp_exp.
• else effective_until MUST be greater than applicant_perm.effective_until AND, if vp_exp is not null, lower or equal to vp_exp.

§ [MOD-PERM-MSG-3-2-2] Set Permission VP to Validated validator perms

• load validator_perm from applicant_perm.validator_perm_id. validator_perm MUST be a valid permission.
• account running the method MUST be validator_perm.grantee.

This section is non-normative.

If validator_perm is not a valid permission (expired, revoked, slashed…) then applicant should start a new validation process.

§ [MOD-PERM-MSG-3-2-3] Set Permission VP to Validated fee checks

Validator MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-PERM-MSG-3-3] Set Permission VP to Validated execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• Load Permission entry applicant_perm from id.
• Load Permission entry validator_perm from applicant_perm.validator_perm_id.
• define now timestamp of now().

Calculate vp_exp:

• Load CredentialSchema cs from applicant_perm.schema_id.

• let’s define validity_period = cs.issuer_grantor_validation_validity_period (if applicant_perm.type is ISSUER_GRANTOR), cs.verifier_grantor_validation_validity_period (if applicant_perm.type is VERIFIER_GRANTOR), cs.issuer_validation_validity_period (if applicant_perm.type is ISSUER), cs.verifier_validation_validity_period (if applicant_perm.type is VERIFIER), or cs.holder_validation_validity_period (if applicant_perm.type is HOLDER).

• if validity_period is NULL: vp_exp = NULL.

• else if applicant_perm.vp_exp is null, vp_exp = timestamp of now() plus validity_period.

• else vp_exp = applicant_perm.vp_exp plus validity_period.

Change value of provided effective_until if needed, and abort if needed:

• if provided effective_until is NULL:

  • change value of provided effective_until to vp_exp.

• else if applicant_perm.effective_until is NULL:

  • verify that provided effective_until is greater than now else MUST abort
  • if vp_exp is not null, verify that provided effective_until is lower or equal to vp_exp else MUST abort

• else:

  • effective_until MUST be greater than applicant_perm.effective_until else MUST abort
  • if vp_exp is not null, verify that provided effective_until is lower or equal to vp_exp else MUST abort.

Update Permission applicant_perm:

• set applicant_perm.modified to now.
• set applicant_perm.vp_state to VALIDATED.
• set applicant_perm.vp_last_state_change to now.
• set applicant_perm.vp_current_fees to 0;
• set applicant_perm.vp_current_deposit to 0;
• set applicant_perm.vp_summary_digest_sri to vp_summary_digest_sri.
• set applicant_perm.vp_exp to vp_exp.
• set applicant_perm.effective_until to effective_until.
• if applicant_perm.effective_from IS NULL (first time method is called for this perm, and thus we are not in a renewal):
  • set applicant_perm.validation_fees to validation_fees;
  • set applicant_perm.issuance_fees to issuance_fees;
  • set applicant_perm.verification_fees to verification_fees;
  • set applicant_perm.country to country;
  • set applicant_perm.effective_from to now.

Fees and Trust Deposits:

• transfer the full amount applicant_perm.vp_current_fees from escrow account to validator account validator_perm.grantee;
• Calculate validator_trust_deposit = applicant_perm.vp_current_fees * GlobalVariables.trust_deposit_rate;
• Increase validator perm trust deposit: use [MOD-TD-MSG-1] to increase by validator_trust_deposit the trust deposit of account running the method and transfer the corresponding amount to TrustDeposit module. Set applicant_perm.vp_validator_deposit to applicant_perm.vp_validator_deposit + validator_trust_deposit.

§ [MOD-PERM-MSG-4] Void

§ [MOD-PERM-MSG-5] Void

§ [MOD-PERM-MSG-6] Cancel Permission VP Last Request

At any time, applicant of a permission validation process may request cancellation of the process, provided state is PENDING. Upon method execution, the pending validation is cancelled and paid trust fees are refunded. If vp_exp is not null, vp_state is set back to VALIDATED, else vp_state is set to TERMINATED.

§ [MOD-PERM-MSG-6-1] Cancel Permission VP Last Request parameters

An account that would like to set cancel a validation entry MUST execute this method by specifying:

• id (uint64) (mandatory): id of the Permission entry;

§ [MOD-PERM-MSG-6-2] Cancel Permission VP Last Request precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-6-2-1] Cancel Permission VP Last Request basic checks

if a mandatory parameter is not present, transaction MUST abort.

• id MUST be a valid uint64.
• Load Permission entry applicant_perm with this id. It MUST exist.
• account running the transaction MUST be applicant_perm.grantee.
• applicant_perm.vp_state MUST be PENDING.

§ [MOD-PERM-MSG-6-2-2] Cancel Permission VP Last Request fee checks

Account executing the method MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-PERM-MSG-6-3] Cancel Permission VP Last Request execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• Load Permission entry applicant_perm with id. It MUST exist.

• define now: current timestamp.

• set applicant_perm.modified to now.

• if applicant_perm.vp_exp is null (validation never completed), set applicant_perm.vp_state to TERMINATED, else set applicant_perm.vp_state to VALIDATED.

• set applicant_perm.vp_last_state_change to now.

• if applicant_perm.vp_current_fees > 0:

  • transfer applicant_perm.vp_current_fees back from escrow account to applicant account, applicant_perm.grantee.
  • set applicant_perm.vp_current_fees to 0;

• if applicant_perm.vp_current_deposit > 0:

  • call [MOD-TD-MSG-1] to reduce trust deposit of applicant_perm.grantee by applicant_perm.vp_current_deposit
  • set applicant_perm.vp_current_deposit to 0.

§ [MOD-PERM-MSG-7] Create Root Permission

This method is used by controllers of Trust Registries. When they create a Credential Schema, they need to create (a) permission(s) of type ECOSYSTEM so that other participants can run validation processes (if schema mode is ECOSYSTEM) or self create their permissions (schema mode set to OPEN).

§ [MOD-PERM-MSG-7-1] Create Root Permission parameters

An account that would like to create a Permission entry MUST call this method by specifying:

• schema_id (uint64) (mandatory)
• did (string) (mandatory): DID of the VS grantee service.
• country (optional).
• effective_from (timestamp) (optional): timestamp from when (exclusive) this Perm is effective. MUST be in the future.
• effective_until (timestamp) (optional): timestamp until when (exclusive) this Perm is effective, null if it doesn’t expire. If not null, MUST be greater than effective_from.
• validation_fees (number) (mandatory): price to pay by applicant to validator for running a validation process that uses this perm as validator, for a given validation period, in trust unit. Default to 0. Note that setting validation fees for OPEN schemas has no effect and does not mean a validation process must take place. For enabling validation processes, at least one of the two issuer, verifier mode must be different than OPEN.
• issuance_fees (number) (mandatory): price to pay by the issuer of a credential of this schema to the grantee of this perm when a credential is issued, in trust unit. Default to 0.
• verification_fees (number) (mandatory): price to pay by the verifier of a credential of this schema to the grantee of this perm when a credential is verified, in trust unit. Default to 0.

§ [MOD-PERM-MSG-7-2] Create Root Permission precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-7-2-1] Create Root Permission basic checks

if a mandatory parameter is not present, transaction MUST abort.

• schema_id MUST be a valid uint64 and a credential schema entry with this id MUST exist.
• did, if specified, MUST conform to the DID Syntax, as specified [DID-CORE].
• effective_from must be in the future.
• effective_until, if not null, must be greater than effective_from
• country if not null, MUST be a valid alpha-2 code (ISO 3166).
• validation_fees (number) (mandatory): MUST be >= 0.
• issuance_fees (number) (mandatory): MUST be >= 0.
• verification_fees (number) (mandatory): MUST be >= 0.

§ [MOD-PERM-MSG-7-2-2] Create Root Permission permission checks

To execute this method, account MUST match at least one these rules, else transaction MUST abort.

• The related CredentialSchema entry is loaded with schema_id, and will be named cs in this section.
• The related TrustRegistry entry tr is loaded from cs.tr_id.
• account executing the method MUST be the controller of tr.
• else MUST abort.

§ [MOD-PERM-MSG-7-2-3] Create Root Permission fee checks

Account MUST have the required estimated transaction fees available.

§ [MOD-PERM-MSG-7-3] Create Root Permission execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.

A new entry Permission perm MUST be created:

• perm.id: auto-incremented uint64.
• perm.schema_id: schema_id.
• perm.modified to now.
• perm.type: ECOSYSTEM.
• perm.did: did.
• perm.grantee: account executing the method.
• perm.created: now
• perm.created_by: account executing the method.
• perm.effective_from: effective_from
• perm.effective_until: effective_until
• perm.country: country
• perm.validation_fees: validation_fees
• perm.issuance_fees: issuance_fees
• perm.verification_fees: verification_fees
• perm.deposit: 0

§ [MOD-PERM-MSG-8] Extend Permission

This method can be called:

• by the grantee (the trust registry controller), if permission is of type ECOSYSTEM.
• by the grantee, if it is a self-created permission (schema configuration is open)
• by a validator (if permission is managed by a VP).

§ [MOD-PERM-MSG-8-1] Extend Permission parameters

An account that would like to extend the effective_until timestamp of a permission MUST call this method by specifying:

• id (uint64) (mandatory): id of the permission;
• effective_until (timestamp) (mandatory): timestamp until when (exclusive) this Permission is effective.

§ [MOD-PERM-MSG-8-2] Extend Permission precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-8-2-1] Extend Permission basic checks

if a mandatory parameter is not present, transaction MUST abort.

• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.
• applicant_perm MUST be a valid permission
• effective_until MUST be greater than applicant_perm.effective_until else MUST abort.

§ [MOD-PERM-MSG-8-2-2] Extend Permission advanced checks

1. ECOSYSTEM permissions

• if applicant_perm.validator_perm_id is null and applicant_perm.type is ECOSYSTEM, account running the method MUST be `applicant_perm.grantee’.

2. Self-created permissions

• load validator_perm from applicant_perm.validator_perm_id. validator_perm MUST be a valid permission of type ECOSYSTEM. account running the method MUST be applicant_perm.grantee.

3. VP managed permissions

• effective_until MUST be lower or equal to applicant_perm.vp_exp else MUST abort.
• load validator_perm from applicant_perm.validator_perm_id. validator_perm MUST be a valid permission. account running the method MUST be validator_perm.grantee.

§ [MOD-PERM-MSG-8-2-3] Extend Permission fee checks

Account executing the method MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-PERM-MSG-8-3] Extend Permission execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.

• Load Permission entry applicant_perm from id.

• set applicant_perm.effective_until to effective_until

• set applicant_perm.extended to now

• set applicant_perm.modified to now

• set applicant_perm.extended_by to account executing the method.

§ [MOD-PERM-MSG-9] Revoke Permission

This method can only be called:

• by an ancestor (a validator in the permission branch until the root permission (GRANTOR, ECOSYSTEM, OPEN schema mode)).
• by the grantee (OPEN, GRANTOR, ECOSYSTEM schema mode).
• by the TrustRegistry controller (owner of the credential schema).

§ [MOD-PERM-MSG-9-1] Revoke Permission parameters

An account that would like to extend the effective_until timestamp of a permission MUST call this method by specifying:

• id (uint64) (mandatory): id of the permission;

§ [MOD-PERM-MSG-9-2] Revoke Permission precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-9-2-1] Revoke Permission basic checks

if a mandatory parameter is not present, transaction MUST abort.

• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.
• applicant_perm MUST be a valid permission

§ [MOD-PERM-MSG-9-2-2] Revoke Permission advanced checks

Either Option #1, #2 or #3 MUST return true, else abort.

Option #1: executed by a validator ancestor

if applicant_perm.validator_perm_id is defined:

• set validator_perm = applicant_perm
• while validator_perm.validator_perm_id is defined,
  • load validator_perm from validator_perm.validator_perm_id.
  • if validator_perm is a valid permission and validator_perm.grantee is who is running the method, => return true.
• end
• return false.

Option #2: executed by TrustRegistry controller

• load CredentialSchema cs from applicant_perm.schema_id
• load TrustRegistry tr from cs.tr_id
• if account running the method is tr.controller, return true.
• else return false.

Option #3: executed by applicant_perm.grantee: return true.

Example:

In the following permission tree, “Verifier E” permission can be revoked:

• by “Verifier E”, if the corresponding permission is a valid permission;
• by “Verifier Grantor D”, if the corresponding permission is a valid permission;
• by “Ecosystem A”, if the corresponding root permission is a valid permission;
• by the TrustRegistry object controller, obtained by resolving perm => credential schema => trust registry.

§ [MOD-PERM-MSG-9-2-3] Revoke Permission fee checks

Account running the method MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-PERM-MSG-9-3] Revoke Permission execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.

• Load Permission entry applicant_perm from id.

• set applicant_perm.revoked to now

• set applicant_perm.modified to now

• set applicant_perm.revoked_by to account executing the method.

§ [MOD-PERM-MSG-10] Create or Update Permission Session

Any credential exchange that requires issuer or verifier to pay fees implies the creation of a PermissionSession.

If the peer wants to issue a credential, the agent, the Verifiable User Agent or Verifiable Service that receive the request MUST send to peer:

• a uuid for session identification;
• the wallet_agent_perm_id permission id of the agent wallet that will store the credential.

If the peer wants to verify a credential, agent must send to peer:

• a uuid for session identification;
• a map of compatible found credentials in available wallets for the requested schema_id: Map<uint64: wallet_agent_perm_id, string[] issuer_dids>

payer MUST create a Permission Session using the above information, then, agent MUST check session has been created and is valid before accepting the action (receive and store issued credential, or accept a presentation request).

See VT spec.

§ [MOD-PERM-MSG-10-1] Create or Update Permission Session parameters

An account that would like to create or update a PermissionSession entry MUST send a Msg by specifying:

• id (uuid) (mandatory): id of the PermissionSession.
• issuer_perm_id (uint64) (optional): the id of the perm od the issuer, if we are dealing with the issuance of a credential.
• verifier_perm_id (uint64) (optional): the id of the perm of the issuer, if we are dealing with the verification of a credential.
• agent_perm_id (uint64) (mandatory): the agent that received the request (credential offer for issuance, presentation request for verification).
• wallet_agent_perm_id (uint64) (mandatory): the wallet agent where the credential will be or is stored, if different than agent.

§ [MOD-PERM-MSG-10-2] Create or Update Permission Session precondition checks

If any of these precondition checks fail, transaction MUST abort.

if issuer_perm_id is null AND verifier_perm_id is null, MUST abort.

• define issuer_perm as null.
• define verifier_perm as null.

if issuer_perm_id is no null:

• Load issuer_perm from issuer_perm_id.
• if issuer_perm.type is not ISSUER, abort.
• if issuer_perm is not a valid permission, abort.

if verifier_perm_id is no null:

• Load verifier_perm from verifier_perm_id.
• if verifier_perm.type is not VERIFIER, abort.
• if verifier_perm is not a valid permission, abort.

agent:

• Load agent_perm from agent_perm_id.
• if agent_perm.type is not ISSUER, abort.
• if agent_perm is not a valid permission, abort.

wallet_agent:

• Load wallet_agent_perm from wallet_agent_perm_id.
• if wallet_agent_perm.type is not ISSUER, abort.
• if wallet_agent_perm is not a valid permission, abort.

§ [MOD-PERM-MSG-10-3] Create or Update Permission Session fee checks

Account MUST have sufficient available balance for:

• the required estimated transaction fees;
• the required beneficiary fees and its corresponding trust deposit trust_fees as explained below:

To calculate the required beneficiary fees, use “Find Beneficiaries” query method below to get the set of beneficiary permission found_perm_set. Now that we have the set with all ancestors, we can calculate the required fees:

• define beneficiary_fees = 0
• if verifier_perm is null: iterate over permissions perm of found_perm_set and set beneficiary_fees = beneficiary_fees + perm.issuance_fees.
• if verifier_perm is NOT null: iterate over permissions perm of found_perm_set and set beneficiary_fees = beneficiary_fees + perm.verification_fees.

Total required trust_fees to be paid by account executing the method, including Trust Deposit: (beneficiary_fees + percent fees for agents) * trust deposit percent * trust unit price:

trust_fees = beneficiary_fees * (1 + (GlobalVariables.user_agent_reward_rate + GlobalVariables.wallet_user_agent_reward_rate)) * (1 + GlobalVariables.trust_deposit_rate) * GlobalVariables.trust_unit_price

See Pay per trust fees above.

§ [MOD-PERM-MSG-10-4] Create or Update Permission Session execution

If all precondition checks passed, method is executed.

• Load all permissions as in basic checks.

• define now: current timestamp.

• use “Find Beneficiaries” above to build found_perm_set.

• if verifier_perm is null:

  • for each Permission perm from found_perm_set, if perm.issuance_fees > 0:
    • transfer perm.issuance_fees * GlobalVariables.trust_unit_price * (1 - GlobalVariables.trust_deposit_rate) to perm.grantee.
    • use [MOD-TD-MSG-1] to increase by perm.issuance_fees * GlobalVariables.trust_unit_price * GlobalVariables.trust_deposit_rate the trust deposit of perm.grantee. Increase perm.deposit by the same value.
    • use [MOD-TD-MSG-1] to increase by perm.issuance_fees * GlobalVariables.trust_unit_price * GlobalVariables.trust_deposit_rate the trust deposit of account executing the method. Add the same amount to issuer_perm.deposit.

• else :

  • for each Permission perm from found_perm_set, if perm.verification_fees > 0:
    • transfer perm.verification_fees * GlobalVariables.trust_unit_price * (1 - GlobalVariables.trust_deposit_rate) to perm.grantee.
    • use [MOD-TD-MSG-1] to increase by perm.verification_fees * GlobalVariables.trust_unit_price * GlobalVariables.trust_deposit_rate the trust deposit of perm.grantee. Increase perm.deposit by the same value.
    • use [MOD-TD-MSG-1] to increase by perm.verification_fees * GlobalVariables.trust_unit_price * GlobalVariables.trust_deposit_rate the trust deposit of account executing the method. Add the same amount to verifier_perm.deposit.

If new, create entry PermissionSession session:

• session.id: id
• session.controller: account running the method
• session.agent_perm_id: agent_perm_id
• session.authz[]: create and put (issuer_perm_id, verifier_perm_id, wallet_agent_perm_id).
• session.modified: : now
• session.created: : now

Else update:

• add (issuer_perm_id, verifier_perm_id, wallet_agent_perm_id) to session.authz[]
• session.modified: : now

§ [MOD-PERM-MSG-11] Update Permission Module Parameters

Update Permission Module Parameters.

Can only be executed through a governance proposal.

§ [MOD-PERM-MSG-11-1] Update Permission Module Parameters parameters

• params (KeySet<String, String>): the parameters to update and their values.

§ [MOD-PERM-MSG-11-2] Update Permission Module Parameters precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-11-2-1] Update Permission Module Parameters basic checks

• params: size of params MUST be greater than 0. For each param <key, value> key MUST exist, else abort.

§ [MOD-PERM-MSG-11-2-2] Update Permission Module Parameters fee checks

provided transaction fees MUST be sufficient for execution

§ [MOD-PERM-MSG-11-3] Update Permission Module Parameters execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

for each parameter param <key, value> in parameters:

• update parameter set value = value where key = key.

§ [MOD-PERM-MSG-12] Slash Permission Trust Deposit

This method can only be called by either:

• an ancestor validator of this permission;
• the controller of the TrustRegistry object, owner of the corresponding credential schema.

§ [MOD-PERM-MSG-12-1] Slash Permission Trust Deposit parameters

An account that would like to slash a permission trust deposit MUST call this method by specifying:

• id (uint64) (mandatory): id of the permission;
• amount (number) (mandatory): the amount to slash

§ [MOD-PERM-MSG-12-2] Slash Permission Trust Deposit precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-12-2-1] Slash Permission Trust Deposit basic checks

if a mandatory parameter is not present, transaction MUST abort.

• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.
• amount MUST be lower or equal to applicant_perm.deposit else MUST abort.

§ [MOD-PERM-MSG-12-2-2] Slash Permission Trust Deposit validator perms

Either Option #1, or #2 MUST return true, else abort.

Option #1: executed by a validator ancestor

if applicant_perm.validator_perm_id is defined:

• set validator_perm = applicant_perm
• while validator_perm.validator_perm_id is defined,
  • load validator_perm from validator_perm.validator_perm_id.
  • if validator_perm is a valid permission and validator_perm.grantee is who is running the method, => return true.
• end
• return false.

Option #2: executed by TrustRegistry controller

• load CredentialSchema cs from applicant_perm.schema_id
• load TrustRegistry tr from cs.tr_id
• if account running the method is tr.controller, return true.
• else return false.

§ [MOD-PERM-MSG-12-2-3] Slash Permission Trust Deposit fee checks

Account executing the method MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-PERM-MSG-12-3] Slash Permission Trust Deposit execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.

• Load Permission entry applicant_perm from id.

• Load Permission entry validator_perm from applicant_perm.validator_perm_id.

• set applicant_perm.slashed to now

• set applicant_perm.modified to now

• set applicant_perm.slashed_deposit to applicant_perm.slashed_deposit + amount

• set applicant_perm.slashed_by to account executing the method.

use MOD-TD-MSG-7 to burn the slashed amount from the trust deposit of applicant_perm.grantee.

§ [MOD-PERM-MSG-13] Repay Permission Slashed Trust Deposit

This method can only be called by anyone that want to repay the deposit of a slashed perm. This won’t make the perm re-usable: it will be needed for the grantee to request a new permission, as slashed permissions cannot be revived (same happen for revoked, etc…).

Nevertheless, to get a new permission for a given ecosystem, it is needed, using this method, to repay the deposit of a slashed permission first.

§ [MOD-PERM-MSG-13-1] Repay Permission Slashed Trust Deposit parameters

An account that would like to repay a permission trust deposit MUST call this method by specifying:

• id (uint64) (mandatory): id of the permission

§ [MOD-PERM-MSG-13-2] Repay Permission Slashed Trust Deposit precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-13-2-1] Repay Permission Slashed Trust Deposit basic checks

if a mandatory parameter is not present, transaction MUST abort.

• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.

§ [MOD-PERM-MSG-13-2-2] Repay Permission Slashed Trust Deposit validator perms

Any account can execute this method.

§ [MOD-PERM-MSG-13-2-3] Repay Permission Slashed Trust Deposit fee checks

Account executing the method MUST have the required estimated transaction fees in its account, plus applicant_perm.slashed_deposit, else transaction MUST abort.

§ [MOD-PERM-MSG-13-3] Repay Permission Slashed Trust Deposit execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.

• Load Permission entry applicant_perm from id.

• set applicant_perm.repaid to now

• set applicant_perm.modified to now

• set applicant_perm.repaid_deposit to amount.

• set applicant_perm.repaid_by to account executing the method.

use Adjust Trust Deposit to transfer amount to trust deposit of applicant_perm.grantee.

§ [MOD-PERM-MSG-14] Create Permission

This simple permission creation method can be used to self-create an ISSUER (resp. VERIFIER) permission if issuance mode (resp. verification mode) is set to OPEN for a given schema. As permissions are the anchor of ecosystem trust deposit operations, it is required for an issuer/verifier candidate to self-create a permission for being issuer or verifier of a given schema.

§ [MOD-PERM-MSG-14-1] Create Permission parameters

An account that would like to create a Permission entry MUST call this method by specifying:

• schema_id (uint64) (mandatory)
• type (PermissionType) (mandatory): ISSUER or VERIFIER.
• did (string) (mandatory): DID of the VS grantee service.
• country (optional).
• effective_from (timestamp) (optional): timestamp from when (exclusive) this Perm is effective. MUST be in the future.
• effective_until (timestamp) (optional): timestamp until when (exclusive) this Perm is effective, null if it doesn’t expire. If not null, MUST be greater than effective_from.
• verification_fees (number) (optional): price to pay by the verifier of a credential of this schema to the grantee of this ISSUER perm when a credential is verified, in trust unit. Default to 0.
• validation_fees (number) (optional): price to pay by the holder of a credential of this schema to the issuer when executing a validation process to obtain a credential, in trust unit. Default to 0.

§ [MOD-PERM-MSG-14-2] Create Permission precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-14-2-1] Create Permission basic checks

if a mandatory parameter is not present, transaction MUST abort.

• schema_id MUST be a valid uint64 and a credential schema entry with this id MUST exist.
• type (PermissionType) (mandatory): MUST be ISSUER or VERIFIER, else abort.
• did, if specified, MUST conform to the DID Syntax, as specified [DID-CORE].
• effective_from must be in the future.
• effective_until, if not null, must be greater than effective_from
• country if not null, MUST be a valid alpha-2 code (ISO 3166).
• verification_fees (number) (optional): If specified, MUST be >= 0 and MUST be a ISSUER permission.
• validation_fees (number) (optional): If specified, MUST be >= 0 and MUST be a ISSUER permission.

§ [MOD-PERM-MSG-14-2-2] Create Permission permission checks

To execute this method, account MUST match at least one these rules, else transaction MUST abort.

• The related CredentialSchema entry is loaded with schema_id, and will be named cs in this section.
• if type is equal to ISSUER: if cs.issuer_perm_management_mode is not equal to OPEN, MUST abort.
• if type is equal to VERIFIER: if cs.verifier_perm_management_mode is not equal to OPEN, MUST abort.
• if type is equal to VERIFIER and validation_fees is specified and different than 0, MUST abort.
• if type is equal to VERIFIER and verification_fees is specified and different than 0, MUST abort.

§ [MOD-PERM-MSG-14-2-3] Create Permission fee checks

Account MUST have the required estimated transaction fees available.

§ [MOD-PERM-MSG-14-3] Create Permission execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.
• load the root permission of the schema (the one of type ECOSYSTEM) to ecosystem_perm_id.

A new entry Permission perm MUST be created:

• perm.id: auto-incremented uint64.
• perm.schema_id: schema_id.
• perm.modified to now.
• perm.type: type.
• perm.did: did.
• perm.grantee: account executing the method.
• perm.created: now
• perm.created_by: account executing the method.
• perm.effective_from: effective_from
• perm.effective_until: effective_until
• perm.country: country
• perm.validation_fees: validation_fees if specified and type is ISSUER, else 0.
• perm.issuance_fees: 0
• perm.verification_fees: verification_fees if specified and type is ISSUER, else 0.
• perm.deposit: 0
• perm.validator_perm_id: ecosystem_perm_id

§ [MOD-PERM-QRY-1] List Permissions

Anyone CAN execute this method.

Generic query used for (at least):

• find all permissions (all or limit to active) of a given schema;
• for a given validator, get PENDING validation processes;
• find all permissions of a given grantee;
• find all permissions of a given did;
• find all ISSUER_GRANTOR active permission, so that I can apply to an ISSUER permission; …

§ [MOD-PERM-QRY-1-1] List Permissions parameters

• schema_id (number) (optional): the schema id.
• grantee (account) (optional): the grantee account.
• did (string) (optional): the did the permission refers to.
• perm_id (number) (optional): limit to permissions where the validator_perm_id is perm_id.
• type (PermissionType) (optional): if we want to limit to a specific permission type.
• only_valid (boolean) (optional): if set to true, only return valid permissions.
• only_slashed (boolean) (optional): if set to true, only return slashed permissions.
• only_repaid (boolean) (optional): if set to true, only return repaid slashed permissions.
• modified_after (timestamp) (optional): limit to permissions modified after (or equal to) modified_after.
• country (string) (optional): limit to country.
• vp_state (ValidationState) (optional): limit to permissions with a vp_state not null and equal to vp_state.
• response_max_size (small number) (optional): limit to response_max_size results. Must be min 1, max 1,024. Default to 64.
• when (timestamp) (optional): if set, query at when, else query at now(). Used to query the VPR state at a previous datetime.

§ [MOD-PERM-QRY-1-2] List Permissions checks

Basic type check arg SHOULD be applied.

If any of these checks fail, query MUST fail.

• response_max_size must be between 1 and 1,024. Default to 64 if unspecified.

§ [MOD-PERM-QRY-1-3] List Permissions execution

return a list of found entries, or an empty list if nothing found. Ordered by modified asc.

§ [MOD-PERM-QRY-2] Get Permission

Anyone CAN execute this method.

§ [MOD-PERM-QRY-2-1] Get Permission parameters

• id of the credential schema permission (mandatory);

§ [MOD-PERM-QRY-2-2] Get Permission checks

• id must be a uint64.

§ [MOD-PERM-QRY-2-3] Get Permission execution

return found entry (if any).

§ [MOD-PERM-QRY-3] Void

Obsoleted by [MOD-PERM-QRY-1].

§ [MOD-PERM-QRY-4] Find Beneficiaries

Anyone can execute this method.

To calculate the fees required for paying the beneficiaries, it is needed to recurse all involved perms until the root of the permission tree (which is the trust registry perm), starting from the 2 branches issuer_perm and verifier_perm. As both branches may have common ancestors, we can create a Set (unordered collection with no duplicates), and recurse over the 2 branches, adding found perms. If verifier_perm is null, issuer_perm is never added to the set. If verifier_perm is NOT null, issuer_perm is added to the set if it exists but verifier_perm is not added to the set.

Example 1: verifier_perm: is not set: it’s a credential offer, schema configured to have Issuer Grantors.

Example 2: verifier_perm: is not set: it’s a credential offer. Schema configured to NOT have Issuer Grantors.

Example 3: verifier_perm is set, it’s a presentation request. Schema configured to have Verifier and Issuer Grantors.

§ [MOD-PERM-QRY-4-1] Find Beneficiaries parameters

• issuer_perm_id (uint64) (optional): id of issuer permission.
• verifier_perm_id (uint64) (optional): id of verifier permission.

§ [MOD-PERM-QRY-4-2] Find Beneficiaries checks

• if issuer_perm_id and verifier_perm_id are unset then MUST abort.
• if issuer_perm_id is specified, load issuer_perm from issuer_perm_id, Permission MUST exist and MUST be a valid permission.
• if verifier_perm_id is specified, load verifier_perm from verifier_perm_id, Permission MUST exist and MUST be a valid permission.

§ [MOD-PERM-QRY-4-3] Find Beneficiaries execution

Example: Let’s build the set. Revoked and slashed permissions will not be added to the set. Expired permissions, if not revoked/slashed, will be considered.

• create Set found_perm_set.

• define permission current_perm as null.

• load perms issuer_perm and optional verifier_perm as specified in basic checks above.

if issuer_perm is not null:

• set current_perm = issuer_perm
• while current_perm.validator_perm_id is not null:
  • set current_perm to loaded permission from current_perm.validator_perm_id.
  • if current_perm.revoked AND current_perm.slashed is NULL, Add current_perm to found_perm_set.

Additionally, if verifier_perm is not null:

• if issuer_perm is not null, add issuer_perm to found_perm_set
• set current_perm = verifier_perm
• while verifier_perm.validator_perm_id is not null:
  • set current_perm to loaded permission from current_perm.validator_perm_id.
  • if current_perm.revoked AND current_perm.slashed is NULL, Add current_perm to found_perm_set.

return found_perms.

§ [MOD-PERM-QRY-5] Get PermissionSession

§ [MOD-PERM-QRY-5-1] Get PermissionSession parameters

• id (uuid) (mandatory): the id of the PermissionSession.

§ [MOD-PERM-QRY-5-2] Get PermissionSession checks

§ [MOD-PERM-QRY-5-3] Get PermissionSession execution

return PermissionSession entry if found, else return not found.

§ [MOD-PERM-QRY-6] List Permission Module Parameters

§ [MOD-PERM-QRY-6-2] List Permission Module Parameters parameters

§ [MOD-PERM-QRY-6-2] List Permission Module Parameters query checks

§ [MOD-PERM-QRY-6-3] List Permission Module Parameters execution of the query

Return the list of the existing parameters and their values.

§ [MOD-PERM-QRY-6-4] List Permission Module Parameters API result example

{
  "params": {
    "key1": "value1",
    "key2": "value2",
    ...
    ...
  }
}

§ [MOD-PERM-QRY-7] List Permission Sessions

Anyone CAN execute this method.

§ [MOD-PERM-QRY-7-1] List Permission Sessions parameters

• modified_after (timestamp) (optional): show permissions modified after this timestamp.
• response_max_size (small number) (optional): default to 64. Min 1, max 1,024.

§ [MOD-PERM-QRY-7-2] List Permission Sessions checks

• modified_after (timestamp) (mandatory): show permissions modified after this timestamp.
• response_max_size (small number) (optional): Must be min 1, max 1,024.

§ [MOD-PERM-QRY-7-3] List Permission Sessions execution

return a list of found entries, or an empty list if nothing found, ordered by modified asc.

§ Validation Examples

§ Getting a Credential from an Authorized Issuer

This section is non-normative.

Example of an Applicant that would like to get issued a credential (HOLDER):

§ Add a DID to the List of Granted Issuers of a Credential Schema

This section is non-normative.

§ DID Directory Module

The DID Directory is a keystore of DIDs.

§ DID Directory Module Overview

This section is non-normative.

Registering a DID in the DID Directory makes the DID, its associated credentials, and related services (such as VSs) publicly discoverable by crawlers and indexers.

⚠️ Registration is optional and not required for Trust Resolution.
However, it may be useful for certain use cases, for example, a Social Browser may rely on the DID Directory to crawl and index all DIDs that reference Social Channel VSs, enabling users to search and discover them directly through the app.

The DID Directory is open to anyone, meaning:

• There is no built-in verification at the VPR level to confirm that the registering account actually controls the DID.
• Since the VPR does not resolve DIDs, it cannot verify ownership or control.

This implies that a DID could be registered by someone who is not its legitimate controller, an inherent limitation of the model.
That said, the deterrent is economic: why would anyone pay registration fees for a DID they do not control?

To protect the intent of the actual DID controller, registration alone does not trigger indexing.
Indexers must respect optional crawler directives included in the DID Document (e.g., index, noindex), ensuring that control over indexation remains with the DID controller, regardless of who registered the DID in the directory.

§ [MOD-DD-MSG-1] Add a DID

Add a DID to the DID Directory, with expiration timestamp set to current timestamp + years years.

Any account CAN run this method.

§ [MOD-DD-MSG-1-1] Add a DID transaction parameters

• did (string) (mandatory): the DID.
• years (tiny number) (optional): the number of years we want the entry to be valid for, 1-31 years. Default to 1 year.

§ [MOD-DD-MSG-1-2] Add a DID precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-DD-MSG-1-2-1] Add a DID basic checks

• if a mandatory parameter is not present, transaction MUST abort.
• did: the specified DID format MUST conform to the DID Syntax, as specified [DID-CORE], and MUST NOT already exist in DID directory.
• years: can be null, but if specified, must be between 1 and 31 inclusive.

§ [MOD-DD-MSG-1-2-2] Add a DID fee checks

Applicant MUST have an available balance (not blocked by trust deposit nor staked) in its account, to cover the following fees:

• the required estimated transaction fees;
• the required trust_deposit_in_denom: GlobalVariables.trust_unit_price * did_directory_trust_deposit * years.

§ [MOD-DD-MSG-1-3] Add a DID execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• Recalculate trust_deposit_in_denom, as specified above.

• use [MOD-TD-MSG-1] to increase by trust_deposit_in_denom the trust deposit of account running the method and transfer the corresponding amount to TrustDeposit module.

• Create DidDirectory entry:

  • set entry.did to did;
  • set entry.controller to account;
  • set entry.created to timestamp of day;
  • set entry.modified to timestamp of day;
  • set entry.exp to timestamp of day + years years;
  • set entry.deposit to trust_deposit_in_denom

§ [MOD-DD-MSG-2] Renew a DID

Renew a DID, by adding years years to current expiration timestamp.

This method MUST be run by controller of the DID entry.

§ [MOD-DD-MSG-2-1] Renew a DID transaction parameters

• did (string) (mandatory): the DID.
• years (tiny number) (optional): the number of years we want to ad to the current expiration timestamp, 1-31 years. Default to 1 year.

§ [MOD-DD-MSG-2-2] Renew a DID precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-DD-MSG-2-2-1] Renew a DID basic checks

if any of the following conditions is not satisfied, transaction MUST abort.

• did: the specified DID format MUST conform to the DID Syntax, as specified [DID-CORE] and MUST exist in DID directory.
• years: can be null, but if specified, must be between 1 and 31 inclusive.
• account executing the transaction MUST be the controller of the DID.

§ [MOD-DD-MSG-2-2-2] Renew a DID fee checks

Applicant MUST have an available balance (not blocked by trust deposit nor staked) in its account, to cover the following fees:

• the required estimated transaction fees;
• the required trust_deposit_in_denom: GlobalVariables.trust_unit_price * did_directory_trust_deposit * years.

§ [MOD-DD-MSG-2-3] Renew a DID execution of the transaction

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• Recalculate trust_deposit_in_denom, as specified above.

• Recalculate removal_gas_fees, as specified above.

• use [MOD-TD-MSG-1] to increase by trust_deposit_in_denom the trust deposit of account running the method and transfer the corresponding amount to TrustDeposit module.

• Update DidDirectory entry:

  • set entry.modified to timestamp of day;
  • set entry.exp to entry.exp+years` years;
  • set entry.deposit to entry.deposit + trust_deposit_in_denom.

§ [MOD-DD-MSG-3] Remove a DID

Remove a DID and unlock the corresponding trust deposit.

§ [MOD-DD-MSG-3-1] Remove a DID transaction parameters

• did (string) (mandatory): the DID.

§ [MOD-DD-MSG-3-2] Remove a DID precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-DD-MSG-3-2-1] Remove a DID basic checks

if any of the following conditions is not satisfied, transaction MUST abort.

• did: the specified DID format MUST conform to the DID Syntax, as specified [DID-CORE], and MUST exist in DID directory.
• if now() < expireTs + GlobalVariables.did_directory_grace_period_days ; then account running the transaction MUST be equals to controller; else parameter account CAN be any account.

§ [MOD-DD-MSG-3-2-2] Remove a DID fee checks

Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-DD-MSG-3-3] Remove a DID execution of the transaction

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• load DidDirectory entry dd.

• use [MOD-TD-MSG-1] to decrease by dd.deposit the trust deposit of dd.controller account.

• remove entry from DidDirectory.

§ [MOD-DD-MSG-4] Touch a DID

This method is used to update the modified of a given entry so that crawlers will know DID should be immediately reindexed.

§ [MOD-DD-MSG-4-1] touch a DID transaction parameters

• did (string) (mandatory): the DID.

§ [MOD-DD-MSG-4-2] Touch a DID precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-DD-MSG-4-2-1] Touch a DID basic checks

• if a mandatory parameter is not present, transaction MUST abort.
• did: the specified DID format MUST conform to the DID Syntax, as specified [DID-CORE], and MUST exist in DID directory.

§ [MOD-DD-MSG-4-2-2] Touch a DID fee checks

Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-DD-MSG-4-3] Touch a DID execution of the transaction

If all precondition checks passed, transaction is executed.

Transaction execution MUST perform the following tasks, and rollback if any error occurs.

• update modified to timestamp of the day for the selected entry.

§ [MOD-DD-MSG-5] Update Module Parameters

Update Module Parameters.

Can only be executed through a governance proposal.

§ [MOD-DD-MSG-5-1] Update Module Parameters parameters

• params (KeySet<String, String>): the parameters to update and their values.

§ [MOD-DD-MSG-5-2] Update Module Parameters precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-DD-MSG-5-2-1] Update Module Parameters basic checks

• params: size of params MUST be greater than 0. For each param <key, value> key MUST exist, else abort.

§ [MOD-DD-MSG-5-2-2] Update Module Parameters fee checks

provided transaction fees MUST be sufficient for execution

§ [MOD-DD-MSG-5-3] Update Module Parameters execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

for each parameter param <key, value> in parameters:

• update parameter set value = value where key = key.

§ [MOD-DD-QRY-1] List DIDs

This method is used to query the DID Directory keeper. Returned data MUST be ordered by modified asc.

§ [MOD-DD-QRY-1-1] List DIDs query parameters

The following parameters are optional:

• account (account): if specified, returns only DIDs controlled by account.
• modified (timestamp): if specified, returns only DIDs changed after modified.
• expired (boolean): if specified, show expired services, in and over grace period.
• over_grace (boolean): if specified, show expired services, over grace period.
• response_max_size (small number): default to 64. Max 1,024.

§ [MOD-DD-QRY-1-2] List DIDs query checks

If any of these checks fail, query MUST fail.

• response_max_size must be between 1 and 1,024.

§ [MOD-DD-QRY-1-3] List DIDs execution of the query

If all precondition checks passed, query is executed and result (may be empty) returned.

§ [MOD-DD-QRY-2] Get a DID

This method is used to read a DID from the DID Directory keeper. As this method does not modify data, it does not require a transaction.

§ [MOD-DD-QRY-2-1] Get a DID query parameters

• did (string) (mandatory): the DID.

§ [MOD-DD-QRY-2-2] Get a DID query checks

did MUST conform to the DID Syntax, as specified [DID-CORE].

§ [MOD-DD-QRY-2-3] Get a DID execution of the query

If DID is found, return the corresponding entry, else empty result is returned.

§ [MOD-DD-QRY-3] List Module Parameters

Anyone CAN run this query.

§ [MOD-DD-QRY-3-2] List Module Parameters parameters

§ [MOD-DD-QRY-3-2] List Module Parameters query checks

§ [MOD-DD-QRY-3-3] List Module Parameters execution of the query

Return the list of the existing parameters and their values.

§ [MOD-DD-QRY-3-4] List Module Parameters API result example

{
  "params": {
    "key1": "value1",
    "key2": "value2",
    ...
    ...
  }
}

§ Trust deposit module

§ Trust deposit module overview

This section is non-normative.

Concept: the trust deposit is used to lock trust value as a stake. To process application messages that perform state changes, several modules methods are requiring a trust deposit to be sent, from the executing account, to the trust deposit module.

We will use a similar method than the one described here to manage trust deposit and yield calculation and easy way.

Example:

In our example, we suppose a VPR is just starting and no trust transaction have taken place yet. For this reason:

• TrustDeposit module has a balance of 0: TrustDeposit.deposit : 0.
• GlobalVariables.trust_deposit_share_value has a value of 1.

Operation #1:

an account account1 wants to create a transaction that requires:

• 10 denom to be sent to the account1 trust deposit;
• 5 denom for network fees.

First, the Trust Deposit: execution of the method will perform the following (we consider this account had no TrustDeposit entry yet):

• 10 denom are sent to the TrustDeposit module.

  • TrustDeposit.deposit = TrustDeposit.deposit + 10

• a TrustDeposit entry td1 is created for account1 running the service with:

  • td1.deposit = 10
  • td1.shares = 10 / GlobalVariables.trust_deposit_share_value = 10

Second, fee distribution: let’s suppose that trust_deposit_block_reward_share is set to 0.30 so that 70% of transaction fees are distributed to validators, and 30% of transaction fees are distributed to trust deposit holders. For this specific transaction:

• 30% * 5 = 1.5 denom will be sent to TrustDeposit module, which will increase the GlobalVariables.trust_deposit_share_value:

• TrustDeposit.deposit = 11.5

• GlobalVariables.trust_deposit_share_value = 1.15.

Now, account1 can (optionally) reclaim the difference between the GlobalVariables.trust_deposit_share_value * tt.share minus tt.denom, which represents the trust (yield) gains.

Operation #2:

Another account account2 wants to create a transaction that requires:

• 20 denom to be sent to the account2 trust deposit;
• 10 denom for network fees.

First, Trust Deposit:

• 20 denom are sent to the TrustDeposit module.

  • TrustDeposit.deposit = 31.5

• a TrustDeposit entry td2 is created for account2:

  • td2.deposit = 20
  • td2.shares = 20 / GlobalVariables.trust_deposit_share_value = 20 / 1.15 ~= 17.39...

Second, fee distribution: let’s suppose trust_deposit_block_reward_share is set to 0.30 so that 70% of transaction fees are distributed to validators, and 30% of transaction fees are distributed to trust deposit holders. For this specific transaction:

• 30% * 10 = 3 denom will be sent to TrustDeposit module, which will increase the GlobalVariables.trust_deposit_share_value:

• TrustDeposit.deposit = 34.5

• GlobalVariables.trust_deposit_share_value = 1.15 * 34.5 / 31.5 ~= 1.2595...

After the 2 operations:

• account1 real deposit (based on share) is account1.share * GlobalVariables.trust_deposit_share_value ~= 12.595..., available withdrawable yield is account1.share * GlobalVariables.trust_deposit_share_value - account1.deposit ~= 2.595...
• account2 real deposit (based on share) is account2.share * GlobalVariables.trust_deposit_share_value ~= 21.90..., available withdrawable yield is account2.share * GlobalVariables.trust_deposit_share_value - account2.deposit ~= 1.90...

§ Trust Deposit Yield

The following global parameters are used to tune the Trust Deposit yield generation, in case the VPR is implemented as a ledger:

• trust_deposit_max_yield_rate(number) (mandatory): Maximum yearly yield, in percent, that a trust deposit holder can obtain by receiving block rewards.
• trust_deposit_block_reward_share(number) (mandatory): Percentage of block reward that must be distributed to trust deposit holders. Default value: 20% (0.20)

Each time there is a block reward to be distributed, trust_deposit_block_reward_share percent MUST be directed to trust deposit holders, based on their trust deposit share.

Implementers MUST make sure, for each processed block reward, that the yearly effective yield is lower or equal than trust_deposit_max_yield_rate.

§ [MOD-TD-MSG-1] Adjust Trust Deposit

This method is used to increase or decrease the trust deposit of a specific account.

Only the modules that require trust deposit manipulation CAN call this method. If trust deposit has been slashed and not repaid, method execution MUST abort.

§ [MOD-TD-MSG-1-1] Adjust Trust Deposit method parameters

• account (account) (mandatory): account of the trust deposit we want to adjust.
• augend (number) (mandatory): value to add to the deposit, in denom.

§ [MOD-TD-MSG-1-2] Adjust Trust Deposit precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-TD-MSG-1-2-1] Adjust Trust Deposit basic checks

• if a mandatory parameter is not present, transaction MUST abort.

Value checks:

• augend (number) (mandatory): MUST be strictly positive or strictly negative.

• load TrustDeposit entry td for account running the method.

  • if td does not exist:
    • if augend is negative, transaction MUST abort.
  • else
    • if augend is negative and td.claimable - augend is greater than td.deposit transaction MUST abort.

§ [MOD-TD-MSG-1-2-2] Adjust Trust Deposit fee checks

• load TrustDeposit entry td for account running the method.
• if td exists:
  • if augend is positive, calculate needed_deposit = augend - td.claimable.
  • else needed_deposit = 0.
• else needed_deposit = augend.

Account running the transaction MUST have the required estimated transaction fees in its account plus needed_deposit, else transaction MUST abort.

§ [MOD-TD-MSG-1-3] Adjust Trust Deposit execution of the method

If all precondition checks passed, method is executed in a transaction.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• if a TrustDeposit entry td does not exist for this account, create entry td:

  • transfer augend from account to TrustDeposit account.
  • calculate augend_share = amount / GlobalVariables.trust_deposit_share_value.
  • set td.account to account;
  • set td.deposit to augend;
  • set td.share to augend_share;
  • set td.claimable to 0.
  • set td.slashed_deposit to 0.
  • set td.repaid_deposit to 0.
  • set td.slash_count to 0.

• else if slashed_deposit > 0 and slashed_deposit < repaid_deposit => deposit has been slashed and not repaid, so MUST abort.

• else if augend > 0:

  • if td.claimable > 0:

    • if td.claimable >= augend :
      • set td.claimable to td.claimable - augend
    • else
      • use bank? to transfer augend - td.claimable from account to TrustDeposit account.
      • set td.deposit to td.deposit + augend - td.claimable
      • set td.claimable to 0
      • calculate missing_augend_share from missing tokens : missing_augend_share = (augend - td.claimable) / GlobalVariables.trust_deposit_share_value.
      • set td.share to td.share + missing_augend_share

  • else

    • use bank? to transfer augend from account to TrustDeposit account.
    • calculate augend_share = augend / GlobalVariables.trust_deposit_share_value.
    • set td.deposit to td.deposit + augend
    • set td.share to td.share + augend_share

• else if augend < 0:

  • set td.claimable to td.claimable - augend

The last case, augend < 0, is to free trust deposit (ej when terminating a permission).

§ [MOD-TD-MSG-2] Reclaim Trust Deposit Yield

This method is used to reclaim yield. If trust deposit has been slashed and not repaid, method execution MUST abort.

Any account MAY call this method.

For a given TrustDeposit entry td, claimable yield is calculated like this:

claimable_yield = td.share * GlobalVariables.trust_deposit_share_value - td.deposit.

If claimable_yield is positive, it can be claimed.

§ [MOD-TD-MSG-2-1] Reclaim Trust Deposit Yield method parameters

N/A

§ [MOD-TD-MSG-2-2] Reclaim Trust Deposit Yield precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-TD-MSG-2-2-1] Reclaim Trust Deposit Yield basic checks

• Load TrustDeposit entry td from account running the method.
• if td.slashed_deposit > 0 and td.slashed_deposit < td.repaid_deposit => deposit has been slashed and not repaid, so MUST abort.
• calculate claimable_yield = td.share * GlobalVariables.trust_deposit_share_value - td.deposit.
• if claimable_yield <= 0, transaction MUST abort.

§ [MOD-TD-MSG-2-2-2] Reclaim Trust Deposit Yield fee checks

Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-TD-MSG-2-3] Reclaim Trust Deposit Yield Value execution of the method

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

For the TrustDeposit entry td linked to account:

• Load TrustDeposit entry td from account running the method.
• calculate claimable_yield = td.share * GlobalVariables.trust_deposit_share_value - td.deposit.
• update td.share = td.share - claimable_yield / GlobalVariables.trust_deposit_share_value
• transfer claimable_yield from TrustDeposit account to account.

§ [MOD-TD-MSG-3] Reclaim Trust Deposit

This method is used to reclaim claimable trust deposit value, td.claimable. If trust deposit has been slashed and not repaid, method execution MUST abort.

Any account MAY call this method.

In order to discourage user from using this method:

• execution of the method will reduce value of td.deposit by subtracting claimed and set td.claimable to td.claimable - claimed;
• GlobalVariables.trust_deposit_reclaim_burn_rate * claimed will be burned from account.

§ [MOD-TD-MSG-3-1] Reclaim Trust Deposit method parameters

• claimed (number) (mandatory): value to reclaim, in denom.

§ [MOD-TD-MSG-3-2] Reclaim Trust Deposit precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-TD-MSG-3-2-1] Reclaim Trust Deposit basic checks

if any of these conditions is not satisfied, transaction MUST abort.

• claimed must be > 0.
• if td.slashed_deposit > 0 and td.slashed_deposit < td.repaid_deposit => deposit has been slashed and not repaid, so MUST abort.
• TrustDeposit entry td MUST exist for this account, and td.claimable MUST be greater or equal to claimed.
• calculate required_minimum_deposit = td.share * GlobalVariables.trust_deposit_share_value. required_minimum_deposit MUST be greater or equal to td.deposit - claimed, else method MUST abort.

§ [MOD-TD-MSG-3-2-2] Reclaim Trust Deposit fee checks

Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-TD-MSG-3-3] Reclaim Trust Deposit execution of the method

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

For the TrustDeposit entry td linked to account:

• set td.claimable to td.claimable - claimed.
• set td.deposit to td.deposit - claimed.
• set td.share to td.share - claimed / GlobalVariables.trust_deposit_share_value
• calculate to_burn = GlobalVariables.trust_deposit_reclaim_burn_rate * claimed from account.
• calculate to_transfer = claimed - to_burn
• transfer to_transfer from TrustDeposit account to account.
• burn to_burn from TrustDeposit module.

§ [MOD-TD-MSG-4] Update Module Parameters

Update Module Parameters.

Can only be executed through a governance proposal.

§ [MOD-TD-MSG-4-1] Update Module Parameters parameters

• params (KeySet<String, String>): the parameters to update and their values.

§ [MOD-TD-MSG-4-2] Update Module Parameters precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-TD-MSG-4-2-1] Update Module Parameters basic checks

• params: size of params MUST be greater than 0. For each param <key, value> key MUST exist, else abort.

§ [MOD-TD-MSG-4-2-2] Update Module Parameters fee checks

provided transaction fees MUST be sufficient for execution

§ [MOD-TD-MSG-4-3] Update Module Parameters execution

If all precondition checks passed, transaction is executed.

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

for each parameter param <key, value> in parameters:

• update parameter set value = value where key = key.

§ [MOD-TD-MSG-5] Slash Trust Deposit

This method is used by the network governance authority to globally slash an account trust deposit.

This method can only be called by a governance proposal. A globally slashed account MUST repay the slashed deposit in order to continue to use the services provided by the VPR. When and account is slashed, and while slashed deposit has not been repaid, all account linked permissions MUST be considered non trustable.

This method is for network governance authority slash. For ecosystem slash, see Slash Permission Trust Deposit.

§ [MOD-TD-MSG-5-1] Slash Trust Deposit method parameters

• account (account) (mandatory): account of the trust deposit we want to slash.
• amount (number) (mandatory): value to slash, in denom.

§ [MOD-TD-MSG-5-2] Slash Trust Deposit precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-TD-MSG-5-2-1] Slash Trust Deposit basic checks

if any of these conditions is not satisfied, transaction MUST abort.

• amount must be > 0.
• TrustDeposit entry td MUST exist for this account, and td.deposit MUST be greater or equal to amount.

§ [MOD-TD-MSG-5-2-2] Slash Trust Deposit fee checks

Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-TD-MSG-5-3] Slash Trust Deposit execution of the method

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.

For the TrustDeposit entry td linked to account:

• set td.deposit to td.deposit - amount.
• set td.share to td.share - amount / GlobalVariables.trust_deposit_share_value
• burn amount from TrustDeposit account.
• set td.slashed_deposit to td.slashed_deposit + amount
• set td.last_slashed to now
• set td.repaid_by to undefined.
• if td.slash_count is undefined, set it to 1, else set it to td.slash_count + 1

§ [MOD-TD-MSG-6] Repay Slashed Trust Deposit

Repay a slashed trust deposit. Can be executed by any account.

§ [MOD-TD-MSG-6-1] Repay Slashed Trust Deposit method parameters

• account (account) (mandatory): account of the trust deposit we want to repay.
• amount (number) (mandatory): value to repay, in denom.

§ [MOD-TD-MSG-6-2] Repay Slashed Trust Deposit precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-TD-MSG-6-2-1] Repay Slashed Trust Deposit basic checks

if any of these conditions is not satisfied, transaction MUST abort.

• amount must be > 0.
• TrustDeposit entry td MUST exist for this account, and amount MUST be exactly equal to td.slashed_deposit - td.repaid_deposit.

§ [MOD-TD-MSG-6-2-2] Repay Slashed Trust Deposit fee checks

Account running the transaction MUST have the required estimated transaction fees in its account plus amount, else transaction MUST abort.

§ [MOD-TD-MSG-6-3] Repay Slashed Trust Deposit execution of the method

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.

For the TrustDeposit entry td linked to account:

• set td.deposit to td.deposit + amount.
• set td.share to td.share + amount / GlobalVariables.trust_deposit_share_value
• add amount to TrustDeposit account.
• set td.repaid_deposit to td.repaid_deposit + amount
• set td.last_repaid to now
• set td.last_repaid_by to account executing the transaction.

§ [MOD-TD-MSG-7] Burn Ecosystem Slashed Trust Deposit

Burn the portion of the trust deposit of a given account. This method can only be called by the permission module when performing an ecosystem-related slash.

§ [MOD-TD-MSG-7-1] Burn Ecosystem Slashed Trust Deposit method parameters

• account (account) (mandatory): account of the trust deposit we want to burn.
• amount (number) (mandatory): value to burn, in denom.

§ [MOD-TD-MSG-7-2] Burn Ecosystem Slashed Trust Deposit precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-TD-MSG-7-2-1] Burn Ecosystem Slashed Trust Deposit basic checks

if any of these conditions is not satisfied, transaction MUST abort.

• amount must be > 0.
• TrustDeposit entry td MUST exist for this account, and amount MUST be lower or equal than td.deposit.

§ [MOD-TD-MSG-7-2-2] Burn Ecosystem Slashed Trust Deposit fee checks

Account running the transaction MUST have the required estimated transaction fees in its account else transaction MUST abort.

§ [MOD-TD-MSG-7-3] Burn Ecosystem Slashed Trust Deposit execution of the method

Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.

• define now: current timestamp.

For the TrustDeposit entry td linked to account:

• set td.deposit to td.deposit - amount.
• set td.share to td.share - amount / GlobalVariables.trust_deposit_share_value
• burn amount from TrustDeposit account.

§ [MOD-TD-QRY-1] Get Trust Deposit

Any account CAN run this query. As this method does not modify data, it does not require a transaction.

§ [MOD-TD-QRY-1-1] Get Trust Deposit query parameters

• account (account) (mandatory): the account for which we want to get the trust deposit value.

§ [MOD-TD-QRY-1-2] Get Trust Deposit query checks

If any of these checks fail, query MUST fail.

• account must be a valid account.

§ [MOD-TD-QRY-1-3] Get Trust Deposit execution of the query

If found, returns trust deposit, else return not found.

§ [MOD-TD-QRY-2] List Module Parameters

Anyone CAN run this query.

§ [MOD-TD-QRY-2-2] List Module Parameters parameters

§ [MOD-TD-QRY-2-2] List Module Parameters query checks

§ [MOD-TD-QRY-2-3] List Module Parameters execution of the query

Return the list of the existing parameters and their values.

§ [MOD-TD-QRY-2-4] List Module Parameters API result example

{
  "params": {
    "key1": "value1",
    "key2": "value2",
    ...
    ...
  }
}

§ Mixed Queries

Queries that are not tied to a specific module.

§ [MIXED-QRY-1] Get Account Reputation

Get the reputation of an account (trust deposit size, slashs…).

Any account CAN run this query.

• If user specifies tr_id, method returns info of all credential schemas of this trust registry.
• If user specifies schema_id, method returns info of this credential schema, for the trust registry it belongs to.
• If nothing is specified, we’ll return info of all trust registries and their credential schemas.

§ [MIXED-QRY-1-1] Get Account Reputation query parameters

• account (account) (mandatory)
• tr_id (number) (optional): filter by trust registry id.
• schema_id (number) (optional): filter by schema_id.
• include_slash_details (boolean) (optional): if we include the detail of slashs/repayments.

§ [MIXED-QRY-1-2] Get Account Reputation query checks

Perform basic type checks.

§ [MIXED-QRY-1-3] Get Account Reputation execution of the query

If account exists, returns an object with the following content.

• the account address account;
• the account balance balance;
• the trust deposit of this account deposit;
• the slashed trust deposit amount of this account slashed;
• the repaid trust deposit amount of this account repaid;
• the number of slashs of this account slash_count;
• the datetime of the first interaction of this account with an ecosystem (trust registry) or the did directory first_interaction_ts;
• the total number of trust registries controlled by this account trust_registry_count;
• the total number of credential schemas controlled by this account credential_schema_count;

if include_slash_details is true:

• slashs (SlashData[]);
• repayments (RepaymentData[]);

SlashData:

• slashed_amount (number);
• slashed_ts: (timestamp);
• slashed_by: (account);

RepaymentData:

• repaid_amount (number);
• repaid_ts: (timestamp);
• repaid_by: (account);

Then what’s follow depends on filter.

• trust_registries (TrustRegistryData[]):

For each Trust Registry: (depends on filter), if account have had at least one interaction linked to one credential schema of this trust registry.

TrustRegistryData:

• tr_id (number);
• tr_did (did);
• credential_schemas (CredentialSchemaData);

CredentialSchemaData:

• deposit (number): the calculated permission-based trust deposit of this account in the context of the credential schema;

• slashed (number): the calculated permission-based slashed trust deposit amount of this account in the context of the credential schema;

• repaid (number): the calculated permission-based repaid trust deposit amount of this account in the context of the credential schema;

• slash_count (number): the calculated permission-based number of slashs of this account in the context of the credential schema;

• issued (number): the number of issued credentials (if available (sessions)) in the context of the credential schema;

• verified (number): the number of verified credentials (if available (sessions)) in the context of the credential schema;

• run_as_validator_vps (number): the number of validation processes run as a validator in the context of the credential schema;

• run_as_applicant_vps (number): the number of validation processes run as an applicant in the context of the credential schema;

• issuer_perm_count (number): the total number of ISSUER permissions in the context of the credential schema;

• verifier_perm_count (number): the total number of VERIFIER permissions in the context of the credential schema;

• issuer_grantor_perm_count (number): the total number of ISSUER_GRANTOR permissions in the context of the credential schema;

• issuer_grantor_perm_count (number): the total number of VERIFIER_GRANTOR permissions in the context of the credential schema;

• ecosystem_perm_count (number): the total number of ECOSYSTEM permissions in the context of the credential schema;

• active_issuer_perm_count (number): the number of active (not revoked, not expired) ISSUER permissions in the context of the credential schema;

• active_verifier_perm_count (number): the number of active (not revoked, not expired) VERIFIER permissions in the context of the credential schema;

• active_issuer_grantor_perm_count (number): the number of active (not revoked, not expired) ISSUER_GRANTOR permissions in the context of the credential schema;

• active_issuer_grantor_perm_count (number): the number of active (not revoked, not expired) VERIFIER_GRANTOR permissions in the context of the credential schema;

• active_ecosystem_perm_count (number): the number of active (not revoked, not expired) ECOSYSTEM permissions in the context of the credential schema;

if include_slash_details is true:

• slashs (PermissionSlashData[]):
• repayments (PermissionRepaymentData[]);

PermissionSlashData:

• perm_id
• schema_id
• tr_id
• slashed_ts
• slashed_by

PermissionRepaymentData:

• perm_id
• schema_id
• tr_id
• repaid_ts
• repaid_by

§ ToIP Trust Registry QueryProtocol version 2.0

This section is non-normative.

As no data is verifiable in ledger, implementation of a TRQP2.x endpoint should be provided by a trust resolver, independant from the VPR.

§ Initial Data Requirements

§ [GLO] Global Variables

Global variables CAN only be changed by the governance authority through proposals.

Default values MUST be set at VPR initialization (genesis). Below you’ll find some possible values. These values will have to be defined in the governance framework.

Trust Unit:

• trust_unit_price (number) (mandatory): 1.0 denom.

Credential Schema:

• credential_schema_trust_deposit (number) (mandatory): 10 trust units.
• credential_schema_schema_max_size (number) (mandatory): 8192.
• credential_schema_issuer_grantor_validation_validity_period_max_days (number) (mandatory): 3650.
• credential_schema_verifier_grantor_validation_validity_period_max_days (number) (mandatory): 3650.
• credential_schema_issuer_validation_validity_period_max_days (number) (mandatory): 3650.
• credential_schema_verifier_validation_validity_period_max_days (number) (mandatory): 3650.
• credential_schema_holder_validation_validity_period_max_days (number) (mandatory): 3650.

Validation:

• validation_term_requested_timeout_days (number) (mandatory): 7.

Trust Registry:

• trust_registry_trust_deposit (number) (mandatory): 10 trust units.

DID Directory:

• did_directory_trust_deposit (number) (mandatory): 5 trust units.
• did_directory_grace_period_days (number) (mandatory): 30.

Trust Deposit:

• trust_deposit_reclaim_burn_rate (number) (mandatory): 0.60.

• trust_deposit_share_value(number) (mandatory): 1.

• trust_deposit_rate(number) (mandatory): 0.20.

• trust_deposit_max_yield_rate(number) (mandatory): 0.20

• trust_deposit_block_reward_share(number) (mandatory): 0.20

• wallet_user_agent_reward_rate(number) (mandatory): 0.10.

• user_agent_reward_rate(number) (mandatory): 0.10.

§ References

§ Normative References

DID-CORE

Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.

RFC3986

Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter; 2005-01. Status: Internet Standard.

VC-DATA-MODEL

Verifiable Credentials Data Model v1.1. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog; 2022-03-03. Status: REC.