§ Verifiable Public Registry v4 Specification

Latest draft: spec v4-draft21

Latest stable: spec v3

Editors:

Fabrice Rochette (The Verana Foundation)

Contributors:

Ariel Gentile

Mathieu Gauthron

Pratik Kumar

Participate:

GitHub repo

File a bug

Commit history

§ Abstract

Decentralized trust ecosystems need shared infrastructure to answer a fundamental question: who is authorized to issue, verify, or govern credentials in a given context? Without a common registry layer, each ecosystem operates in isolation, trust decisions depend on ad hoc configurations, and there is no interoperable way for Verifiable Services and Verifiable User Agents to resolve the legitimacy of a credential or its issuer.

The Verifiable Public Registry (VPR) is a decentralized “registry of registries” that provides this foundational infrastructure. It allows ecosystems to create and manage their own ecosystems, define credential schemas with fine-grained permission policies, and assign roles — issuers, verifiers, grantors — through a transparent, on-chain governance model.

The VPR exposes a standardized query API that Verifiable Services and Verifiable User Agents use during trust resolution to confirm, in real time, whether a given participant is authorized to perform a specific action under a specific credential schema. This is what makes the trust in Verifiable Trust actually verifiable.

The VPR is DID-method-agnostic — it stores registrations, not validations — leaving trust decisions and cryptographic verification where they belong: with the relying parties. It supports flexible permission management modes (open, ecosystem-controlled, or grantor-delegated), enabling ecosystems to tailor governance to their specific requirements.

This specification defines the data model, API, and normative requirements for implementing and interacting with a Verifiable Public Registry.

§ About this Document

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

§ Introduction

§ What is an Ecosystem?

This section is non-normative.

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

An ecosystem 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 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:

• corporation lifecycle and directory:

  • corporation onboarding, with associated DID and corporation governance framework publication
  • multi-member governance via a Cosmos SDK group (members, voting policy, threshold)
  • a public corporation directory queryable by indexers, verifiable services, and verifiable user agents
  • corporations are the foundational actors of the VPR: they control participants and may themselves control ecosystems.

• ecosystem management:

  • governance framework publication and versionning
  • credential schemas publication
  • participant onboarding
  • custom business models and permission policies
  • and more.

• 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.

Participant 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 onboarding process.

corporation:

A legal/organizational entity that controls Participants in zero or more ecosystems and may itself be the controller of zero or more ecosystems. A Corporation extends a Cosmos SDK group with VPR-level attributes (DID, governance framework, lifecycle).

corporation governance framework:

The governance framework (GF) of a corporation.

corporation governance authority:

The governance authority (GA) of a corporation.

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 participant:

A Participant entry, linked to a credential schema, that represents, 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.

denom:

Token that has been configured and is recognized in a VPR, example: uvna, USDC.

native denom:

Native token of a VPR, example: uvna.

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 ecosystem.

group:

The underlying Cosmos SDK group primitive that a corporation extends. Members and policies are managed by the group module; VPR-level attributes (DID, governance framework, lifecycle) live on the corresponding corporation entry.

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:

An ecosystem 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 corporation, its trust deposit is increased when running onboarding process (either as an applicant or as a validator).

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:

A fake denom that is not usable as a token (cannot be transferred, or used for paying in transactions). Trust unit is used to define fees in Permissions. Fees defined in trust units are automatically converted to native denom when a transaction is executed, using an exchange rate TU/[[ref: native denom]]. Trust unit is used to compensate native denom fluctuation.

ecosystem

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

URI

An Universal Resource Identifier, as specified in rfc3986.

active participant:

A participant of a given role, which 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.

future participant:

A participant of a given role, which effective_from timestamp is higher than current timestamp, and (effective_until timestamp is null or greater than effective_from timestamp), and revoked is null and slashed is null.

onboarding 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 onboarding 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: ecosystem features, that can be used by all its participants: create ecosystems, for each ecosystem, 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:

An ecosystem 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)

§ Ecosystem Management

This section is non-normative.

In an VPR, any corporation can create an Ecosystem entry to represent an ecosystem it controls. Each Ecosystem 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 Participants

This section is non-normative.

Credential schemas are created and managed by ecosystems (i.e., by the corporation controlling each ecosystem). Each Credential schema includes, at a minimum:

• A Json Schema that defines the structure of the corresponding verifiable credential.
• An IssuerOnboardingMode for issuance policy, which determines how ISSUER Participant entries are created. Modes include:
  • OPEN: ISSUER Participants can be self-created by any corporation.
  • ECOSYSTEM_ONBOARDING_PROCESS: ISSUER Participants are created directly by the controlling ecosystem through an onboarding process.
  • GRANTOR_ONBOARDING_PROCESS: ISSUER Participants are created by one or several issuer grantor(s) — ecosystem operators responsible for onboarding issuers for the credential schema of this ecosystem — selected by the ecosystem through an onboarding process.
• A VerifierOnboardingMode for verification policy, which determines how VERIFIER Participant entries are created. Modes include:
  • OPEN: VERIFIER Participants can be self-created by any corporation.
  • ECOSYSTEM_ONBOARDING_PROCESS: VERIFIER Participants are created directly by the controlling ecosystem through an onboarding process.
  • GRANTOR_ONBOARDING_PROCESS: VERIFIER Participants are created by one or several verifier grantor(s) — ecosystem operators responsible for onboarding verifiers for the credential schema of this ecosystem — selected by the ecosystem through an onboarding process.
• A HolderOnboardingMode for holder policy, which determines how HOLDER Participant entries are created. Modes include:
  • ISSUER_ONBOARDING_PROCESS: HOLDER Participants are created directly by issuers for holders, through an onboarding process.
  • PERMISSIONLESS: a holder that wants to obtain credentials from an issuer does not require a Participant entry in the VPR.
• A Participant tree that defines the roles and relationships involved in managing the schema’s lifecycle. Each Participant entry in the tree can define business rules; see Business Models below.

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", // ignored, will be generated
  "$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 the schema is OPEN for issuance and/or verification: a corporation MUST have a registered Corporation entry in the VPR and self-create its Participant entry.

• if the schema is not OPEN for issuance and/or verification: a corporation MUST have a registered Corporation entry in the VPR and complete an onboarding process to obtain its Participant entry.

The onboarding process involves two parties:

• The applicant — the corporation requesting a Participant entry for a credential schema within the ecosystem.
• The validator — a corporation that already holds a Participant entry for the same credential schema and has been delegated authority to validate applicants and create new Participant entries.

Running an onboarding process typically involves the payment of trust fees. The trust fee amount to be paid by the applicant is defined in the validator's Participant entry:

§ Corporation Management

This section is non-normative.

A corporation is the VPR-level entity that represents an authority acting in the registry. It extends a Cosmos SDK group (whose members and policies are managed by the group module) with VPR-specific attributes: a DID, a corporation governance framework (CGF), and lifecycle metadata. A Corporation entry has no id of its own — it is keyed by its underlying group (1:1).

A corporation interacts with the VPR in two complementary ways:

• as the controller of zero or more ecosystems — i.e., the corporation owns the corresponding Ecosystem entries. The controlling corporation manages each ecosystem’s EGF, its credential schemas, and the root ECOSYSTEM Participant entries of those schemas.
• as the owner of zero or more Participant entries in zero or more ecosystems — i.e., the corporation acts as ISSUER, VERIFIER, ISSUER_GRANTOR, VERIFIER_GRANTOR, HOLDER, or root ECOSYSTEM for credential schemas of those ecosystems.

The two roles are independent: a corporation MAY control no ecosystem at all and only hold Participant entries in third-party ecosystems; or it MAY control several ecosystems and additionally hold Participant entries in others; or any combination of the two.

The same Corporation entry is the single entry point for the corporation’s governance (the CGF), authorization delegation (via OperatorAuthorization to one or more operator accounts), and trust-deposit accounting (TrustDeposit). See the Corporation Module for the methods that manage Corporation entries.

§ DID Indexing

This section is non-normative.

The Participant registry is the foundation for building searchable indexes of verifiable services and the verifiable metadata they expose. Crawlers iterate over Participant entries, resolve each service identifier (currently a DID, extensible in the future), verify that the service is a verifiable service, and extract its verifiable metadata — most notably the credentials presented through linked-vp — together with the ecosystem memberships, credential schema permissions, and trust deposit level associated with the controlling corporation.

Unlike a traditional web index, this index is trust-typed: every entry carries cryptographically verifiable claims about what the service is, who operates it, and under which governance frameworks it is accredited. This unlocks a class of discovery use cases that traditional search engines cannot serve.

§ AI agent discovery

AI agents are first-class consumers of the index. Before delegating a task or accepting a connection, an agent needs to find counterparts whose presented credentials match the capabilities required for the interaction. Querying the index, an AI agent can:

• find verifiable services qualified for a specific task — for example, a payment processor accredited in a given jurisdiction, a KYC issuer recognized by a target ecosystem, or an MCP-style service whose operator holds a recognized organization credential;
• discover other AI agents whose credentials prove the right scope, authority, or operator;
• restrict the search to a specific ecosystem or to services that comply with a chosen credential schema;
• rank candidates by trust deposit size, accreditations held, slashing history, or credential freshness, in order to bias selection toward parties with stronger economic accountability.

Because every indexed claim is anchored in the VPR, an AI agent can verify a counterpart end-to-end before initiating the interaction, avoiding spoofed services and unaccredited issuers.

§ Verifiable User Agent content discovery

Verifiable user agents (VUAs) — such as social browsers, agentic browsers, or CDN-aware clients — use the index to find content and services that are compatible with the user’s context: the credentials the user holds, the ecosystems the user trusts, the jurisdictions and languages that apply, and the schemas that the user’s wallet can satisfy.

Typical VUA queries include:

• “Show only services accredited under ecosystem X” — filter by ecosystem membership.
• “Show services that accept the credentials currently in my wallet” — match the holder’s credentials against each VS's expected presentations.
• “Show issuers of schema Y operating in jurisdiction Z” — combine credential schema permissions with corporation metadata.
• “Show services my user has previously interacted with successfully” — combine the index with the VUA’s local history.

The result is a feed of VSs for which a proof of trust can be displayed to the user before connection, in line with the VUA enforcement obligations defined in this spec and in the VT Spec.

§ Other consumers

The same index serves additional consumers:

• Trust-aware and traditional, form-based search engines, which can return ordinary links to VSs enriched with verifiable trust signals (issuer accreditations, ecosystem memberships, trust deposit level).
• Ecosystem operators and governance authorities, which use the index to monitor accredited issuers, verifiers, and grantors, observe schema adoption across ecosystems, and detect rogue or expired participants.
• Auditors, regulators, and compliance tools, which rely on the index to map the supply chain of trust behind a given service or credential, and to verify that participants are still in good standing.
• Analytics and reputation services, which combine indexed metadata with on-chain history (trust-deposit movements, slashing events, session volumes) to produce reputational signals at the corporation level.

§ Indexing pipeline

§ Business models

§ Trust Deposit

This section is non-normative.

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

This trust deposit is automatically funded through transactions involving trust operations, such as onboarding processes, 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 a corporation uses the VPR, the more its 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.

§ Onboarding Process Trust Fees

This section is non-normative.

We’ve explained in the Credential Schemas and Participants section above what is an onboarding process.

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

• (1): if issuer onboarding mode is set to GRANTOR_ONBOARDING_PROCESS.
• (2): if verifier onboarding mode is set to GRANTOR_ONBOARDING_PROCESS.
• (3): if issuer onboarding mode is set to ECOSYSTEM_ONBOARDING_PROCESS.
• (4): if verifier onboarding mode is set to ECOSYSTEM_ONBOARDING_PROCESS.
• (5): if holder onboarding mode is set to ISSUER_ONBOARDING_PROCESS.

Onboarding process is started by the applicant.

Example of a candidate issuer (applicant) that would like to obtain an ISSUER Participant entry for a credential schema of an ecosystem, validated by a validator that holds an ISSUER_GRANTOR Participant entry:

The total fees paid by the applicant consist of:

• The validation trust fees defined in the validator’s Participant entry (the one acting as the validator in the onboarding 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 onboarding process begins, plus
• network fees (not part of the escrowed amount).

Example, using 20% for trust_deposit_rate:

Upon completion of the onboarding 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 on each Participant entry for each role within the ecosystem.

Corporations acting as issuers or verifiers for a given credential schema may be required to pay trust fees based on the schema’s configuration and Participant 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, else HOLDER agent will not accept the operation.

Key Points for “Pay-Per” Business Models

• For a given credential schema, the ecosystem and its participants may define pay-per-issuance (or pay-per-verification) trust fees on their respective Participant entries.

• In such cases, an ISSUER (or VERIFIER) Participant must pay:

  • the corresponding issuance (or verification) trust fees for each involved Participant entry along the Participant tree;
  • an additional amount equal to the trust_deposit_rate of the calculated trust fees, allocated to the payer’s trust deposit;
  • (optional) an amount equal to wallet_user_agent_reward_rate of the calculated trust fees, used to reward the Wallet User Agent;
  • (optional) 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 Participant 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 Participant 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 (aka a council) 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.

§ Corporation

A Corporation is the VPR-level entity that extends a Cosmos SDK group with a DID, a governance framework, and lifecycle attributes. A Corporation may control participants in zero or more ecosystems and may itself be the controller of zero or more ecosystems.

Corporation:

• did (string) (mandatory): the DID of the Corporation. MUST be globally unique across all Corporation entries (per-Corporation did uniqueness invariant): at any block height, no two Corporation entries MAY share the same did value. Enforced at create time by [MOD-CO-MSG-1-2-1] and at rotation time by [MOD-CO-MSG-2-2-1].
• created (timestamp) (mandatory): timestamp this Corporation has been created.
• modified (timestamp) (mandatory): timestamp this Corporation has been modified.
• archived (timestamp) (optional): timestamp this Corporation has been archived.
• language (string) (mandatory): primary language tag (BCP 47) of this Corporation.
• active_version (int) (mandatory): active CGF version.

Note: a Corporation entry has no id of its own. Its primary key is the underlying Cosmos SDK group (1:1, see the group --- corp link in the diagram above): a Corporation entry is created, looked up, and referenced by the id of the group it extends. Members and policies of a Corporation are managed by the underlying Cosmos SDK group module; the Corporation entry adds VPR-level attributes only (DID, governance framework, lifecycle).

§ Ecosystem

Ecosystem:

• id (uint64) (mandatory): the id of the ecosystem.
• did (string) (mandatory): the did of the ecosystem. MAY be shared with other Ecosystem entries (a single DID MAY be the did of several ecosystems); per-Ecosystem DID uniqueness is NOT enforced because the Ecosystem identity is its id. However, per-Ecosystem (did, corporation) consistency IS enforced: at any block height, all Ecosystem entries with equal did MUST share the same corporation. Enforced at create time by [MOD-ES-MSG-1-2-1] and at rotation time by [MOD-ES-MSG-2-2-1].
• corporation (group) (mandatory): corporation that controls this entry. Constrained by the per-Ecosystem (did, corporation) consistency invariant above.
• created (timestamp) (mandatory): timestamp this Ecosystem has been created.
• modified (timestamp) (mandatory): timestamp this Ecosystem has been modified.
• archived (timestamp) (mandatory): timestamp this Ecosystem has been archived.
• language (string) (mandatory): primary language tag (BCP 47) of this ecosystem.
• active_version (int): (mandatory) active governance framework version.

§ GovernanceFrameworkVersion

A GovernanceFrameworkVersion represents a single version of either an EGF or a CGF. Its owning subject is identified by exactly one of ecosystem_id or corporation (XOR).

GovernanceFrameworkVersion:

• id (uint64) (mandatory): the id of the GFV.
• ecosystem_id (uint64) (conditional): the id of the ecosystem that controls this GovernanceFrameworkVersion entry. MUST be set if corporation is null.
• corporation (group) (conditional): the corporation that controls this GovernanceFrameworkVersion entry (i.e., the underlying Cosmos SDK group of the owning Corporation). MUST be set if ecosystem_id is null.
• created (timestamp) (mandatory): timestamp this GovernanceFrameworkVersion has been created.
• version (int) (mandatory): version of this GF. MUST Starts with 1.

Constraint: exactly one of ecosystem_id and corporation MUST be set.

§ GovernanceFrameworkDocument

GovernanceFrameworkDocument

• id (uint64) (mandatory): the id of the GFD.
• gfv_id (uint64) (mandatory): the id of the GovernanceFrameworkVersion entry.
• created (timestamp) (mandatory): timestamp this GovernanceFrameworkDocument has been created.
• language (string) (mandatory): primary language tag (BCP 47) of this governance framework document.
• 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.
• ecosystem_id (uint64) (mandatory): the id of the ecosystem 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.
• 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 onboarding process expires and must be renewed.
• verifier_grantor_validation_validity_period (number) (mandatory): number of days after which a verifier grantor onboarding process expires and must be renewed.
• issuer_validation_validity_period (number) (mandatory): number of days after which an issuer onboarding process expires and must be renewed.
• verifier_validation_validity_period (number) (mandatory): number of days after which a verifier onboarding process expires and must be renewed.
• holder_validation_validity_period (number) (mandatory): number of days after which an holder onboarding process expires and must be renewed.
• issuer_onboarding_mode (IssuerOnboardingMode) (mandatory): defines how permissions are managed for issuers of this CredentialSchema. OPEN means anyone can issue credential of this schema; GRANTOR_ONBOARDING_PROCESS means an onboarding process MUST be run between a candidate ISSUER and an ISSUER_GRANTOR in order to create an ISSUER permission; ECOSYSTEM_ONBOARDING_PROCESS means an onboarding process MUST be run between a candidate ISSUER and the ecosystem owner (ecosystem) of the CredentialSchema entry in order to create an ISSUER permission;
• verifier_onboarding_mode (VerifierOnboardingMode) (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_ONBOARDING_PROCESS means an onboarding process MUST be run between a candidate VERIFIER and a VERIFIER_GRANTOR in order to create a VERIFIER permission; ECOSYSTEM_ONBOARDING_PROCESS means an onboarding process MUST be run between a candidate VERIFIER and the ecosystem owner (ecosystem) of the CredentialSchema entry in order to create a VERIFIER permission;
• holder_onboarding_mode (HolderOnboardingMode) (mandatory): defines how permissions are managed for holders of this CredentialSchema. ISSUER_ONBOARDING_PROCESS means an onboarding process MUST be run between a candidate HOLDER and an ISSUER in order to create a HOLDER permission. HOLDER permission is used to check credential revocation status; PERMISSIONLESS means no onboarding is required to take place on the VPR (and thus an ISSUER cannot use the VPR to charge validation fees to candidate holders);
• pricing_asset_type (PricingAssetType) (mandatory): used asset for paying business fees. Can be TU (trust unit), COIN (a token available on the VPR chain), FIAT (means chain is used for settlement only and payment is done off-chain). Not that in all cases, trust deposits are always handled in denom.
• pricing_asset (string) (mandatory): "tu" if pricing_asset_type is set to TU, else examples: COIN: denom "uvna", "ufoo", "ibc/3A0F9C2E4E2A9B7D6F...", "factory/verana1.../ueurv", FIAT: "USD", "GBP",…
• digest_algorithm (string) (mandatory): algorithm used to compute the digestSRI for credentials issued under this schema. Valid values are defined in the Verifiable Trust spec.

§ SchemaAuthorizationPolicy

SchemaAuthorizationPolicy:

• id (uint64) (mandatory): unique identifier of this authorization policy.
• schema_id (uint64) (mandatory): id of the CredentialSchema this policy applies to.
• created (timestamp) (mandatory): timestamp when this policy entry was created.
• version (integer) (mandatory): version number of this policy for the given (schema_id, role).
• role (SchemaAuthorizationPolicyRole) (mandatory): role this policy applies to (ISSUER or VERIFIER).
• url (string) (mandatory): URL where the policy document is published.
• digest_sri (string) (mandatory): SRI hash of the policy document, used to guarantee integrity and immutability.
• effective_from (timestamp) (mandatory): timestamp from which this policy version is in force.
• effective_until (timestamp) (optional): timestamp until which this policy version is in force, if time-limited.
• revoked (boolean) (mandatory): indicates whether this policy version has been revoked and must no longer be used.

§ Participant

Participant:

• id (uint64) (mandatory): the id of the participant.
• schema_id (uint64) (mandatory): the id of the related CredentialSchema entry.
• role (ParticipantRole): ISSUER, VERIFIER, ISSUER_GRANTOR, VERIFIER_GRANTOR, ECOSYSTEM, HOLDER
• did (string) (optional): DID this permission refers to. MUST conform to [RFC3986]. MAY be shared with other Participant entries (a single DID MAY be the did of several participants); per-Participant DID uniqueness is NOT enforced because the Participant identity is its id. However, per-Participant (did, corporation) consistency IS enforced: at any block height, all Participant entries with non-null equal did MUST share the same corporation. Enforced by the create-time basic checks of [MOD-PP-MSG-1-2-1], [MOD-PP-MSG-7-2-1], and [MOD-PP-MSG-14-2-1]. Participant.did is set at create time and is not rotated thereafter.
• corporation (group) (mandatory): corporation that owns this permission. Constrained by the per-Participant (did, corporation) consistency invariant above (when did is non-null).
• vs_operator (account) (mandatory): verifiable service agent account. This is the account that will have the right to create or update permission sessions.
• created (timestamp) (mandatory): timestamp this Participant has been created.
• adjusted (timestamp) (mandatory): timestamp this Participant has been adjusted.
• slashed (timestamp) (mandatory): timestamp this Participant has been slashed.
• repaid (timestamp) (mandatory): timestamp this Participant has been repaid.
• effective_from (timestamp) (optional): timestamp from which (inclusive) this Participant is effective.
• effective_until (timestamp) (optional): timestamp until when (exclusive) this Participant is effective, null if no time limit has been set for this permission.
• modified (timestamp) (mandatory): timestamp this Participant has been modified.
• validation_fees (number) (mandatory): price to pay by an applicant to a validator (corporation grantee of this perm) for running an onboarding process for a given validation period. Must be an integer. Default to 0. Considered unit depends on pricing_asset_type and pricing_asset configuration of related schema.
• issuance_fees (number) (mandatory): fees requested by grantee corporation of this perm when a credential is issued. Must be an integer. Default to 0. Considered unit depends on pricing_asset_type and pricing_asset configuration of related schema.
• verification_fees (number) (mandatory): fees requested by grantee corporation of this perm when a credential is verified. Must be an integer. Default to 0. Considered unit depends on pricing_asset_type and pricing_asset configuration of related schema.
• deposit (number) (mandatory): accumulated grantee deposit in the context of the use of this permission (including the onboarding process), in native denom. Usually, it is incremented when for example, for a ISSUER type Participant 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 participant.deposit value as well. If perm is, let’s say revoked, then corresponding participant.deposit value is freed from participant.grantee Trust Deposit.
• slashed_deposit (number) (mandatory): part of the deposit in native denom that has been slashed.
• repaid_deposit (number) (mandatory): part of the slashed deposit in native denom that has been repaid.
• revoked (timestamp) (optional): manual revocation timestamp of this Perm.
• validator_participant_id (uint64) (optional): permission of the validator assigned to the onboarding process of this permission, ie parent node in the Participant tree.
• op_state (enum) (mandatory): one of PENDING, VALIDATED, TERMINATED.
• op_exp (timestamp) (optional): validation expiration timestamp. This expiration timestamp is for the onboarding process itself, not for the issued credential or Participant expiration timestamp.
• op_last_state_change (timestamp) (mandatory)
• op_validator_deposit: number (optional): accumulated validator trust deposit, in denom.
• op_current_fees (number) (mandatory): current action escrowed fees that will be paid to validator upon onboarding process completion, in denom.
• op_current_deposit (number) (mandatory): current action trust deposit, in denom.
• op_summary_digest (string) (optional): an optional digest SRI, set by validator, of a summary of the information, proofs… provided by the applicant.
• issuance_fee_discount: (number) (mandatory): default to 0 (no discount). Maximum 1 (100% discount). Can be set to an ISSUER_GRANTOR or ISSUER Participant entry (if GRANTOR_ONBOARDING_PROCESS mode) or to an ISSUER Participant entry (ECOSYSTEM_ONBOARDING_PROCESS mode) to reduce (or void) calculated issuance fees for the subtree of Participant entries. Note: this should generally not be used because it reduces or void commission of all related ecosystem participants.
• verification_fee_discount: (number) (mandatory): default to 0 (no discount). Maximum 1 (100% discount). Can be set to a VERIFIER_GRANTOR or VERIFIER Participant entry (if GRANTOR_ONBOARDING_PROCESS mode) and/or to a VERIFIER Participant entry (ECOSYSTEM_ONBOARDING_PROCESS mode) to reduce (or void) calculated fees for the subtree of Participant entries. Note: this should generally not be used because it reduces or void commission of all related ecosystem participants.

Note: VS operator authorization settings (spend limits, feegrant, expiration, authorized message types) are no longer stored on Participant. They live in ParticipantAuthorizationRecord entries inside VSOperatorAuthorization, keyed by Participant.id. See [MOD-DE-MSG-5] and [AUTHZ-CHECK-3].

§ ParticipantSession

ParticipantSession:

• id (uuid) (mandatory): session uuid.
• corporation (group) (mandatory): corporation that controls the entry.
• vs_operator (account) (mandatory): verifiable service agent account that controls the entry (agent crypto account).
• created (timestamp) (mandatory): timestamp this ParticipantSession has been created.
• modified (timestamp) (mandatory): timestamp this ParticipantSession has been modified.
• session_records (ParticipantSessionRecord[]) (mandatory): session records, for this session.

§ ParticipantSessionRecord

ParticipantSessionRecord:

• created (timestamp) (mandatory): timestamp this record has been created.
• issuer_participant_id (uint64) (optional): related issuer Participant id (if applicable).
• verifier_participant_id (uint64) (optional): related verifier Participant id (if applicable).
• wallet_agent_participant_id (uint64) (optional): related wallet agent Participant id (if applicable).
• agent_participant_id (uint64) (optional): permission id of the agent Participant id (if applicable).

§ TrustDeposit

TrustDeposit:

• share (number) (mandatory): share of the module total deposit.
• corporation (group) (mandatory) (key): the corporation
• deposit (number) (mandatory): amount of deposit in denom.
• refunded (number) (mandatory): amount of refunded trust deposit, in denom. Refunded trust deposit is reused as funding for the next trust deposit spending before drawing additional funds from the corporation account.
• slashed_deposit (number) (optional): amount of slashed deposit in denom.
• repaid_deposit (number) (optional): part of the slashed trust deposit, in denom, that has been repaid.
• last_slashed (timestamp) (optional): last time this trust deposit has been slashed.
• last_repaid (timestamp) (optional): last time this trust deposit has been repaid.
• slash_count (number) (optional): number of times this account has been slashed.

§ DenomAmount

• denom (string) (mandatory): token denomination, as explain in denom.
• amount (number) (mandatory): amount expressed in the given denomination.

§ Digest

• digest (string) (mandatory): digest to store.
• created (timestamp) (mandatory): block execution date of when it was persisted.

§ OperatorAuthorization

• corporation (group) (mandatory): the corporation granting the authorization.
• operator (account) (mandatory): the operator account receiving the authorization.
• msg_types (msg_type[]) (mandatory): list of module message types this authorization applies to.
• spend_limit (DenomAmount[]) (optional): maximum amount of funds that the grantee is allowed to spend as a direct consequence of executing authorized messages.
• remaining_spend (DenomAmount[]) (conditional): runtime balance for spend_limit. Present iff spend_limit is set. Initialized to spend_limit at create time. Decremented per matching denom after each authorized operation. Reset to spend_limit when the current cycle ends (see expiration and period below).
• fee_spend_limit (DenomAmount[]) (optional): maximum total amount of fees that can be paid using this authorization.
• remaining_fee_spend (DenomAmount[]) (conditional): runtime balance for fee_spend_limit. Present iff fee_spend_limit is set. Initialized, decremented and reset following the same rules as remaining_spend.
• expiration (timestamp) (optional): authorization window boundary. If period is unset, this is the absolute end-of-life: when now() >= expiration, the authorization is dead. If period is set, this is the end of the current cycle: when now() >= expiration, the runtime balances are reset to their original limits and expiration is advanced to now() + period (the authorization auto-renews until the corporation revokes it).
• period (duration) (optional): reset period for spend_limit and fee_spend_limit. If set, expiration MUST also be set.

§ FeeGrant

FeeGrant:

• grantor (group) (mandatory): the corporation granting the fee allowance.
• grantee (account) (mandatory): the account that receives the fee grant from grantor.
• msg_types (msg_type[]) (mandatory): list of VPR delegable message types for which the fee allowance applies.
• spend_limit (DenomAmount[]) (optional): maximum amount of fees that can be spent using this grant.
• remaining_spend (DenomAmount[]) (conditional): runtime balance for spend_limit. Present iff spend_limit is set. Initialized to spend_limit at create time. Decremented per matching denom after each authorized operation. Reset to spend_limit when the current cycle ends (see expiration and period below).
• expiration (timestamp) (optional): grant window boundary. If period is unset, this is the absolute end-of-life: when now() >= expiration, the grant is dead. If period is set, this is the end of the current cycle: when now() >= expiration, remaining_spend is reset to spend_limit and expiration is advanced to now() + period (the grant auto-renews until the grantor revokes it).
• period (duration) (optional): reset period for spend_limit. If set, expiration MUST also be set.

§ VSOperatorAuthorization

A VSOperatorAuthorization groups all ParticipantAuthorizationRecord entries delegated by one corporation to one vs_operator. It is keyed by the (corporation, vs_operator) pair. The entry exists if, and only if, it has at least one record.

• corporation (group) (mandatory): the corporation granting the authorization.
• vs_operator (account) (mandatory): the operator account receiving the authorization.
• records (ParticipantAuthorizationRecord[]) (mandatory): per-permission authorization records granted to vs_operator by corporation.

§ ParticipantAuthorizationRecord

A ParticipantAuthorizationRecord carries the per-permission authorization configuration that was previously stored on Participant.vs_operator_authz_* fields. Each record is globally unique by participant_id: for any Participant.id, at most one record exists system-wide, so (corporation, vs_operator) can be derived from participant_id via a direct lookup.

• participant_id (uint64) (mandatory): id of the Participant this authorization record applies to. Globally unique across all ParticipantAuthorizationRecord entries.
• msg_types (msg_type[]) (mandatory): list of delegable message types for which the vs_operator is authorized on behalf of corporation when acting in the context of participant_id. Declared by the applicant at record creation time (see [MOD-PP-MSG-1] and [MOD-PP-MSG-14]). Frozen after creation.
• spend_limit (DenomAmount[]) (optional): maximum amount the vs_operator is allowed to spend, in the context of this Participant entry, as a direct consequence of executing authorized messages.
• remaining_spend (DenomAmount[]) (conditional): runtime balance for spend_limit. Present iff spend_limit is set. Initialized to spend_limit at create time. Decremented per matching denom after each authorized operation. Reset to spend_limit when the current cycle ends (see expiration and period below).
• fee_spend_limit (DenomAmount[]) (optional): maximum total amount of transaction fees that can be spent by vs_operator (paid by corporation via fee grant) in the context of this Participant entry.
• remaining_fee_spend (DenomAmount[]) (conditional): runtime balance for fee_spend_limit. Present iff fee_spend_limit is set. Initialized, decremented and reset following the same rules as remaining_spend.
• with_feegrant (bool) (mandatory): if true, corporation pays the transaction fees for vs_operator when executing authorized messages in the context of this Participant entry, through an on-chain FeeGrant.
• expiration (timestamp) (mandatory): authorization window boundary. If period is unset, this is the absolute end-of-life: when now() >= expiration, the record is dead. If period is set, this is the end of the current cycle: when now() >= expiration, the runtime balances are reset to their original limits and expiration is advanced to now() + period (the record auto-renews until removed via [MOD-DE-MSG-6]). Initially written to now at [MOD-PP-MSG-1] (disabled until validation) and to Participant.effective_until at [MOD-PP-MSG-3] / [MOD-PP-MSG-8] / [MOD-PP-MSG-14].
• period (duration) (optional): reset period for spend_limit and fee_spend_limit in the context of this Participant entry.

§ ExchangeRate

Represents an on-chain exchange rate between two assets.

ExchangeRate:

• base_asset_type (PricingAssetType, mandatory): Type of the base asset.
• base_asset (string, mandatory if base_asset_type is COIN or FIAT, null if base_asset_type is TU): Identifier of the base asset.
• quote_asset_type (PricingAssetType, mandatory): Type of the quote asset.
• quote_asset (string, mandatory): Identifier of the quote asset.
• rate (string, mandatory): Fixed-point integer representing the exchange rate from base asset to quote asset.
• rate_scale (uint32, mandatory): Number of decimal digits used to scale rate.
• validity_duration (duration, mandatory): when updated, set expires to block time plus validity_duration.
• updated (timestamp, mandatory): Timestamp of the last exchange rate update.
• expires (timestamp, mandatory): Timestamp after which the exchange rate is considered invalid.
• state (boolean, mandatory): true means enabled, false means disabled.

§ ExchangeRateAuthorization

Represents the authorization granted by network governance to a specific operator account to execute [MOD-XR-MSG-2] Update Exchange Rate on a given ExchangeRate entry.

Exchange rates are a protocol-level oracle: they are consumed by [MOD-XR-QRY-3] Get Price and used across the protocol (trust deposit pricing, fees). Therefore, ownership and update permission of an ExchangeRate is scoped to the network (governance), not to a corporation. ExchangeRateAuthorization is the on-chain record that designates which operator account is authorized to push fresh values for a given ExchangeRate, and under what runtime constraints.

ExchangeRateAuthorization:

• xr_id (uint64, mandatory): id of the ExchangeRate this authorization applies to. Together with operator, forms the composite key.
• operator (account, mandatory): account authorized to execute [MOD-XR-MSG-2] on xr_id. Together with xr_id, forms the composite key.
• expiration (timestamp, mandatory): authorization end-of-life. When now() >= expiration, the authorization is dead and [MOD-XR-MSG-2] MUST be rejected.
• min_interval (duration, optional): anti-spam guard. If set, two successive successful [MOD-XR-MSG-2] calls under this authorization MUST be separated by at least min_interval.
• max_deviation_bps (uint32, optional): circuit breaker, expressed in basis points (1 bps = 0.01%). If set, [MOD-XR-MSG-2] MUST be rejected if the relative change between the new rate and the current xr.rate exceeds max_deviation_bps / 10000. A larger move requires a fresh governance proposal (typically a new [MOD-XR-MSG-1] or an updated authorization).

§ GlobalVariables

GlobalVariables:

Credential Schema:

• 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.

Trust Deposit:

• trust_deposit_share_value(number) (mandatory): Value of one share of trust deposit, in native 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 an ecosystem.
• JSON formatting MUST obey to data model regarding attribute names. A method that returns a Ecosystem entry MUST return an entry called “ecosystem”. A method that returns a list of Ecosystems MUST return an entry called “ecosystems” that contain a list of Ecosystem entries.

Examples:

Get an Ecosystem

"ecosystem": {
  {
    "active_version": 0,
    "corporation": "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",
        "ecosystem_id": "string",
        "version": 0,
        "documents": [
          {
            "created": "2025-01-14T19:40:37.967Z",
            "gfv_id": "string",
            "digest_sri": "string",
            "id": "string",
            "language": "string",
            "url": "string"
          }
        ]
      }
    ]  
  }

"ecosystems": [ {
  {
    "active_version": 0,
    "corporation": "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",
        "ecosystem_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,
    "corporation": "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",
        "ecosystem_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.

§ Authorization and Fee Grants

§ Delegable Module Messages

Most VPR module messages (Msg) support delegation and follow the pattern described below.

Delegable messages are defined as messages that can be executed by an operator account on behalf of a corporation group, provided that the appropriate authorization has been granted.

Such messages conceptually involve two roles:

• corporation (group):
  The group that owns the created or manipulated resource.
  The corporation is represented in the Msg through an authorization granted to an operator account.

• operator (account):
  The account that executes the Msg on behalf of the corporation.
  The operator MUST be explicitly authorized for the given message type.

When a delegable message is executed directly by an operator account, both roles are authenticated and enforced by the authorization system.

Using this model makes it possible to:

• identify, within the Msg, both the authenticated corporation and the executing operator,
• allow network fees to be paid either by the operator account or by the corporation account via a fee grant.

For the execution of delegable messages:

• the operator account MUST have a valid authorization from the corporation group for the specific message type being executed.

A corporation group is not required to delegate all message types to the same operator.
It is entirely up to the corporation group to decide which accounts may execute which messages.

• Authorizations MUST be granted to individual accounts through group proposals.
• Authorizations MAY include an optional spend_limit and an optional expiration date.

§ Not Delegable Module Messages

Some module messages specify only a corporation:

• corporation (group):
  The group that owns the manipulated resource.

Such messages cannot be delegated and MUST be executed exclusively through a corporation proposal.

§ Governance-Signed Module Messages

Some module messages can be executed only through a VPR council governance proposal.

These messages do not support delegation and are not executable by accounts, whether directly or via group authorization.

§ Fee Grants

A corporation MAY allow its operators to pay network transaction fees using the corporation’s funds.

Fee grants are not created directly.
They are created, updated, and revoked exclusively by Authorization module messages.
When an authorization is created or updated, it MAY optionally include an associated fee grant.

§ [AUTHZ-CHECK] Common Authorization and Fee Grant Precondition Checks

For any delegable message executed by an operator on behalf of a corporation, the following precondition checks MUST be performed before any method-specific checks. If any check fails, the transaction MUST abort.

§ [AUTHZ-CHECK-1] Operator Authorization checks

1. An OperatorAuthorization oauthz MUST exist where oauthz.corporation = corporation, oauthz.operator = operator, and oauthz.msg_types includes the current message type.
2. If oauthz.expiration is set:
   • if oauthz.period is set and now() >= oauthz.expiration:
     • if oauthz.spend_limit is set, set oauthz.remaining_spend := oauthz.spend_limit.
     • if oauthz.fee_spend_limit is set, set oauthz.remaining_fee_spend := oauthz.fee_spend_limit.
     • set oauthz.expiration := now() + oauthz.period.
   • else, oauthz.expiration MUST be strictly greater than now(). Abort otherwise.
3. If oauthz.spend_limit is set, oauthz.remaining_spend MUST be sufficient for the operation. After successful execution, the consumed amount MUST be deducted from oauthz.remaining_spend (per matching denom entry).

§ [AUTHZ-CHECK-2] Fee Grant checks

If the transaction fees are paid by the corporation account (via fee grant) instead of the operator account:

1. A FeeGrant fg MUST exist where fg.grantor = corporation, fg.grantee = operator, and fg.msg_types includes the current message type.
2. If fg.expiration is set:
   • if fg.period is set and now() >= fg.expiration:
     • if fg.spend_limit is set, set fg.remaining_spend := fg.spend_limit.
     • set fg.expiration := now() + fg.period.
   • else, fg.expiration MUST be strictly greater than now(). Abort otherwise.
3. If fg.spend_limit is set, fg.remaining_spend MUST be sufficient for the estimated transaction fees. After successful execution, the consumed fee amount MUST be deducted from fg.remaining_spend (per matching denom entry).

§ [AUTHZ-CHECK-3] VS Operator Authorization checks

A second authorization grant mode exists for vs-agents. It is used when a corporation delegates a specific permission (and a specific set of message types, scoped to that permission) to a vs_operator account. The authorization model differs from other delegable messages: it relies on VSOperatorAuthorization / ParticipantAuthorizationRecord instead of OperatorAuthorization.

Note: the set of messages a vs_operator is authorized to execute in the context of a permission is declared by the applicant at permission creation time (see [MOD-PP-MSG-1-1] and [MOD-PP-MSG-14-1]) and stored in record.msg_types. It is frozen for the lifetime of the record and can only be changed by revoking the permission and starting a new one.

Given a corporation, an operator (the vs_operator), a primary permission id participant_id (determined by the calling method), and the current message type msg_type:

1. A ParticipantAuthorizationRecord record MUST exist for participant_id. Abort if not found.
2. record MUST belong to VSOperatorAuthorization[corporation, operator], that is: the containing VSOperatorAuthorization MUST have corporation as its corporation and operator as its vs_operator. Abort otherwise.
3. msg_type MUST be in record.msg_types. Abort otherwise.
4. Cycle / expiration check:
   • if record.period is set and now() >= record.expiration:
     • if record.spend_limit is set, set record.remaining_spend := record.spend_limit.
     • if record.fee_spend_limit is set, set record.remaining_fee_spend := record.fee_spend_limit.
     • set record.expiration := now() + record.period.
   • else, record.expiration MUST be strictly greater than now(). Abort otherwise.
5. If record.spend_limit is set, record.remaining_spend MUST be sufficient for the operation. After successful execution, the consumed amount MUST be deducted from record.remaining_spend (per matching denom entry).

§ [AUTHZ-CHECK-4] VS Operator Fee Grant checks

If the transaction fees are paid by the corporation account (via fee grant) instead of the operator account, using the same ParticipantAuthorizationRecord record looked up in [AUTHZ-CHECK-3]:

1. record.with_feegrant MUST be true, else abort.
2. The cycle / expiration check from [AUTHZ-CHECK-3] step 4 has already been performed against the same record; record.remaining_fee_spend is therefore current.
3. If record.fee_spend_limit is set, record.remaining_fee_spend MUST be sufficient for the estimated transaction fees. After successful execution, the consumed fee amount MUST be deducted from record.remaining_fee_spend (per matching denom entry).

§ [AUTHZ-CHECK-5] Corporation Registration check

A Corporation entry MUST exist for the signing corporation (i.e., keyed by its underlying Cosmos SDK group). If none exists, the transaction MUST abort with an error indicating that the underlying group has not yet been registered as a corporation (see [MOD-CO-MSG-1]).

Exception: this check MUST NOT be applied for [MOD-CO-MSG-1], whose explicit purpose is to register a Cosmos SDK group as a new Corporation. That method enforces the inverse precondition (the entry MUST NOT yet exist) in its own basic checks.

This check applies to every delegable message that invokes [AUTHZ-CHECK]. As a result, all Create-* methods (and every other delegable Msg) implicitly require the signing corporation to be a registered Corporation.

§ Example

A corporation group corporationABC wants to authorize an operator account accountABC to execute the
mod-pp-msg-10-create-or-update-participant-session, mod-pp-msg-3-set-participant-op-to-validated, and mod-pp-msg-15-trigger-resolver messages.

Additionally, the corporation wants accountABC to pay the transaction fees for this message using the corporation’s funds.

To achieve this, corporationABC MUST:

• create an authorization from corporationABC to accountABC for the
  mod-pp-msg-10-create-or-update-participant-session, mod-pp-msg-3-set-participant-op-to-validated, and mod-pp-msg-15-trigger-resolver message types, optionally enabling an associated fee grant.

As a result, accountABC is authorized to:

• execute the specified messages type on behalf of corporationABC, including any state changes and fund movements that are a direct consequence of that message, and
• pay the network transaction fees for that message using the funds of corporationABC, via the associated fee grant.

§ Method List

§ Corporation Module

This module manages corporation entries — the VPR-level entity that extends a Cosmos SDK group with a DID, a governance framework, and lifecycle attributes. A Corporation entry MUST exist before its underlying group can be referenced as the corporation (group) in any other VPR Create-* method (see [MOD-CO-MSG-1]).

§ [MOD-CO-MSG-1] Create New Corporation

Any authorized operator CAN execute this method on behalf of a Cosmos SDK group to register a new Corporation entry for that group.

§ [MOD-CO-MSG-1-1] Create New Corporation parameters

An authorized operator that would like to register a Cosmos SDK group as a Corporation MUST call this method by specifying:

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed. For this method specifically, the underlying Cosmos SDK group of corporation is the group that wants to register itself — no Corporation entry exists for that group yet.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• did (string) (mandatory): the DID of the Corporation.
• language (string) (mandatory): primary language tag (BCP 47) of this Corporation.
• doc_url (string) (mandatory): URL where the v1 CGF document is published.
• doc_digest_sri (string) (mandatory): digest_sri of the v1 CGF document.

Provided document MUST be of the same language as the primary language of the Corporation.

§ [MOD-CO-MSG-1-2] Create New Corporation precondition checks

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

§ [MOD-CO-MSG-1-2-1] Create New Corporation basic checks

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

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• A Corporation entry for the signing group MUST NOT exist; if one exists, method MUST abort (a group MAY register itself as a Corporation at most once).

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

• did MUST NOT already be the did of any existing Corporation entry; if some Corporation entry already holds this did, method MUST abort (per-Corporation did uniqueness invariant: a DID is the did of at most one Corporation).

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

• 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-CO-MSG-1-2-2] Create New Corporation fee checks

Fee payer MUST have the required estimated transaction fees in its account.

§ [MOD-CO-MSG-1-3] Create New Corporation 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.

• create and persist a new Corporation entry co keyed by the signing Cosmos SDK group (1:1):

• co.did: did

• co.created: current timestamp

• co.modified: co.created

• co.archived: null

• co.language: language

• co.active_version: 1

• create and persist a new GovernanceFrameworkVersion entry gfv:

• gfv.id: auto-incremented uint64

• gfv.ecosystem_id: null

• gfv.corporation: the signing corporation (i.e., the underlying group of co)

• 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

Subsequent governance framework documents and version activations for this Corporation MUST be managed through [MOD-GF-MSG-1] and [MOD-GF-MSG-2].

§ [MOD-CO-MSG-2] Update Corporation

Any authorized operator CAN execute this method on behalf of a corporation.

§ [MOD-CO-MSG-2-1] Update Corporation parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• did (string) (mandatory): the new DID of the Corporation.

Note: language is set at creation time by [MOD-CO-MSG-1] and is immutable thereafter; it cannot be updated through this method.

§ [MOD-CO-MSG-2-2] Update Corporation precondition checks

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

§ [MOD-CO-MSG-2-2-1] Update Corporation basic checks

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

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• A Corporation entry co for the signing corporation MUST exist; if none exists, method MUST abort.

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

• did MUST NOT already be the did of any other Corporation entry (i.e., any Corporation entry whose underlying group differs from the signing corporation); if some other Corporation entry already holds this did, method MUST abort (per-Corporation did uniqueness invariant). Rotating to the same value co.did already holds is a no-op and MUST be allowed.

§ [MOD-CO-MSG-2-2-2] Update Corporation fee checks

Fee payer MUST have available balance in its account to cover the required transaction fees.

§ [MOD-CO-MSG-2-3] Update Corporation 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 Corporation entry co for the signing corporation and set:

• co.did: did

• co.modified: current timestamp

§ [MOD-CO-MSG-3] Archive Corporation

Any authorized operator CAN execute this method on behalf of a corporation.

§ [MOD-CO-MSG-3-1] Archive Corporation parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• archive (boolean) (mandatory): true means archive, false means unarchive.

§ [MOD-CO-MSG-3-2] Archive Corporation precondition checks

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

§ [MOD-CO-MSG-3-2-1] Archive Corporation basic checks

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

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• load Corporation co from the id of the signing corporation. If none exists, MUST abort.

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

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

§ [MOD-CO-MSG-3-2-2] Archive Corporation fee checks

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

§ [MOD-CO-MSG-3-3] Archive Corporation 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 Corporation entry co:
• if archive is true: set co.archived to current timestamp.
• if archive is false: set co.archived to null.
• co.modified: current timestamp

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

Update Module Parameters.

Can only be executed through a governance proposal.

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

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

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

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

§ [MOD-CO-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-CO-MSG-4-2-2] Update Module Parameters fee checks

provided transaction fees MUST be sufficient for execution.

§ [MOD-CO-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-CO-QRY-1] Get Corporation

Anyone CAN execute this method.

§ [MOD-CO-QRY-1-1] Get Corporation query parameters

• corporation (group) (mandatory): the corporation to fetch (i.e., the underlying Cosmos SDK group whose Corporation entry is keyed by it).
• 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, preferring preferred_language.

§ [MOD-CO-QRY-1-2] Get Corporation query checks

If any of these checks fail, query MUST fail.

• corporation (group) (mandatory): MUST be a valid group id.

§ [MOD-CO-QRY-1-3] Get Corporation execution

Return the Corporation entry keyed by corporation (if any), as well as all its nested GovernanceFrameworkVersion and GovernanceFrameworkDocument entries. If active_gf_only is true, return only nested GovernanceFrameworkVersion and GovernanceFrameworkDocument entries for the active version.

§ [MOD-CO-QRY-2] List Corporations

§ [MOD-CO-QRY-2-1] List Corporations query parameters

The following parameters are optional:

• modified_after (timestamp) (optional): if specified, returns only Corporation entries with Corporation.modified greater than modified_after.
• 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, preferring preferred_language.
• response_max_size (small number) (optional): default to 64. Max 1,024.

§ [MOD-CO-QRY-2-2] List Corporations 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-CO-QRY-2-3] List Corporations execution

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

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

Anyone CAN run this query.

§ [MOD-CO-QRY-3-3] List Module Parameters execution

Return the list of parameters of this module as a json file:

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

§ Ecosystem Module

§ [MOD-ES-MSG-1] Create New Ecosystem

Any authorized operator CAN execute this method on behalf of a corporation.

§ [MOD-ES-MSG-1-1] Create New Ecosystem parameters

An authorized operator that would like to create a ecosystem MUST call this method by specifying:

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• did (string) (mandatory): the did of the ecosystem that is creating the ecosystem.
• language (string) (mandatory): primary language tag (BCP 47) of this ecosystem.
• 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 ecosystem.

§ [MOD-ES-MSG-1-2] Create New Ecosystem precondition checks

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

§ [MOD-ES-MSG-1-2-1] Create New Ecosystem basic checks

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

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

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

• if any existing Ecosystem entry has did equal to the provided did, its corporation MUST equal the signing corporation; else method MUST abort (per-Ecosystem (did, corporation) consistency invariant: at any block height, all Ecosystem entries sharing a did are controlled by the same Corporation).

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

• 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-ES-MSG-1-2-2] Create New Ecosystem fee checks

Fee payer MUST have an available balance to cover the estimated transaction fees.

§ [MOD-ES-MSG-1-3] Create New Ecosystem 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.

• create and persist a new Ecosystem entry ecosystem:

• ecosystem.id : auto-incremented uint64

• ecosystem.did: did

• ecosystem.corporation: corporation

• ecosystem.created: current timestamp

• ecosystem.modified: ecosystem.created

• ecosystem.language: language

• ecosystem.active_version: 1

• create and persist a new GovernanceFrameworkVersion entry gfv:

• gfv.id: auto-incremented uint64

• gfv.ecosystem_id: ecosystem.id

• gfv.corporation: null

• 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

Subsequent governance framework documents and version activations for this ecosystem MUST be managed through [MOD-GF-MSG-1] and [MOD-GF-MSG-2].

§ [MOD-ES-MSG-2] Update Ecosystem

Any authorized operator CAN execute this method on behalf of a corporation.

§ [MOD-ES-MSG-2-1] Update Ecosystem parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• id (uint64) (mandatory): the id of the ecosystem.
• did (string) (mandatory): the did of the ecosystem.

§ [MOD-ES-MSG-2-2] Update Ecosystem precondition checks

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

§ [MOD-ES-MSG-2-2-1] Update Ecosystem basic checks

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

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• id (uint64) (mandatory): a Ecosystem entry ecosystem with id id MUST exist and corporation executing the method MUST be the corporation of the Ecosystem entry ecosystem.

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

• if any other Ecosystem entry (i.e., any Ecosystem entry whose id differs from the supplied id) has did equal to the provided did, its corporation MUST equal the signing corporation; else method MUST abort (per-Ecosystem (did, corporation) consistency invariant). Rotating ecosystem.did to a value already held by another Ecosystem controlled by a different corporation is forbidden.

§ [MOD-ES-MSG-2-2-2] Update Ecosystem fee checks

Fee payer must have available balance in its account to cover the required transaction fees.

§ [MOD-ES-MSG-2-3] Update Ecosystem 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 Ecosystem entry ecosystem from id and set:

• ecosystem.did: did

• ecosystem.modified: current timestamp

§ [MOD-ES-MSG-3] Archive Ecosystem

Any authorized operator CAN execute this method on behalf of a corporation.

§ [MOD-ES-MSG-3-1] Archive Ecosystem parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• id (uint64) (mandatory) id of the ecosystem (mandatory);
• archive (boolean) (mandatory), true means archive, false means unarchive.

§ [MOD-ES-MSG-3-2] Archive Ecosystem precondition checks

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

§ [MOD-ES-MSG-3-2-1] Archive Ecosystem basic checks

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

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• load Ecosystem ecosystem from id. ecosystem.corporation MUST be the corporation executing the method, else MUST abort.

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

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

§ [MOD-ES-MSG-3-2-2] Archive Ecosystem fee checks

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

§ [MOD-ES-MSG-3-3] Archive Ecosystem 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 Ecosystem entry ecosystem with ecosystem.id equal to id:
• if archived is true: set ecosystem.archived to current timestamp.
• if archived is false: set ecosystem.archived to null.
• ecosystem.modified: current timestamp

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

Update Module Parameters.

Can only be executed through a governance proposal.

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

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

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

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

§ [MOD-ES-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-ES-MSG-4-2-2] Update Module Parameters fee checks

provided transaction fees MUST be sufficient for execution

§ [MOD-ES-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-ES-QRY-1] Get Ecosystem

Anyone CAN execute this method.

§ [MOD-ES-QRY-1-1] Get Ecosystem parameters

• id (uint64) (mandatory): id of the ecosystem.
• 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-ES-QRY-1-2] Get Ecosystem checks

§ [MOD-ES-QRY-1-3] Get Ecosystem execution

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

§ [MOD-ES-QRY-2] List Ecosystems

§ [MOD-ES-QRY-2-1] List Ecosystems query parameters

The following parameters are optional:

• corporation (group) (optional): if specified, filter by corporation.
• modified_after (timestamp) (optional): if specified, returns only Ecosystem entries with Ecosystem.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-ES-QRY-2-2] List Ecosystems 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-ES-QRY-2-3] List Ecosystems 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 desc.

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

Anyone CAN run this query.

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

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

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

Return the list of the existing parameters and their values.

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

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

§ Governance Framework Module

This module handles governance framework documents and version activation for both ecosystems and corporations. Methods are polymorphic over the owning subject: every message takes an optional ecosystem_id parameter to designate whose governance framework is being modified — if set, the target subject is that Ecosystem (and the signing corporation MUST be its controller); if not set, the target subject is the signing corporation’s own CGF (a Corporation may only edit its own CGF, so no extra parameter is needed).

The initial GovernanceFrameworkVersion and its first GovernanceFrameworkDocument are created atomically by Create New Ecosystem (and, by parallel construction, by Create New Corporation). After that, subsequent versions and documents are added through this module.

§ [MOD-GF-MSG-1] Add Governance Framework Document

Any authorized operator CAN execute this method on behalf of a corporation.

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

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• ecosystem_id (uint64) (optional): id of the target ecosystem whose governance framework will be modified. If set, the signing corporation MUST be the controller of the target Ecosystem. If not set, the target subject is the signing corporation’s own CGF.
• doc_language (string) (mandatory): language tag (BCP 47) of the governance framework document.
• 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 will replace the corresponding entry. Else, a new entry is created. It is only possible to edit future versions. Active version cannot be modified.

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

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

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

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• Define subject as:
  • if ecosystem_id is set: the Ecosystem entry with this id. The entry MUST exist and subject.corporation MUST be equal to the signing corporation.
  • if ecosystem_id is not set: the Corporation entry whose underlying group is the signing corporation. The entry MUST exist (a Corporation may only edit its own governance framework, so no further check is required).
• version: there MUST exist a GovernanceFrameworkVersion entry gfv whose owner matches subject (i.e., gfv.ecosystem_id = ecosystem_id if subject is an Ecosystem, else gfv.corporation = corporation) and gfv.version = version, OR version MUST be exactly equal to the biggest gfv.version + 1 of all GovernanceFrameworkVersion entries owned by subject. version MUST be greater than subject.active_version.
• doc_language (string) (mandatory): MUST be a language tag (BCP 47).
• 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-GF-MSG-1-2-2] Add Governance Framework Document fee checks

Fee payer MUST have the required estimated transaction fees in its account.

§ [MOD-GF-MSG-1-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.

• if a GovernanceFrameworkVersion entry gfv matching subject and version does not exist, create and persist a new one:

  • gfv.id: auto-incremented uint64
  • gfv.ecosystem_id: ecosystem_id (or null if subject is a Corporation)
  • gfv.corporation: the signing corporation (or null if subject is an Ecosystem)
  • gfv.created: current timestamp
  • gfv.version: version
  • gfv.active_since: null

• if a GovernanceFrameworkDocument entry gfd exists with gfd.gfv_id = gfv.id and gfd.language = doc_language, update it:

  • gfd.url: doc_url
  • gfd.digest_sri: doc_digest_sri

• else, create and persist a new 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-GF-MSG-2] Increase Active Governance Framework Version

Any authorized operator CAN execute this method on behalf of a corporation.

§ [MOD-GF-MSG-2-1] Increase Active Governance Framework Version parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• ecosystem_id (uint64) (optional): id of the target ecosystem. If set, the signing corporation MUST be its controller. If not set, the target subject is the signing corporation’s own CGF.

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

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

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

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

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• Define subject as:

  • if ecosystem_id is set: the Ecosystem entry with this id. The entry MUST exist and subject.corporation MUST be equal to the signing corporation.
  • if ecosystem_id is not set: the Corporation entry whose underlying group is the signing corporation. The entry MUST exist.

• Find a GovernanceFrameworkVersion entry gfv owned by subject (matching gfv.ecosystem_id or gfv.corporation as appropriate) whose gfv.version is equal to subject.active_version + 1. If none is found, transaction MUST abort.

• Find a GovernanceFrameworkDocument gfd for gfd.gfv_id = gfv.id and gfd.language = subject.language. If no document is found (and thus no document exists for the default language of this version for this subject), transaction MUST abort.

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

Fee payer MUST have the required estimated transaction fees in its account.

§ [MOD-GF-MSG-2-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 subject (Ecosystem or Corporation as identified above).
• Find a GovernanceFrameworkVersion entry gfv owned by subject whose gfv.version is equal to subject.active_version + 1.
• Update subject.active_version to subject.active_version + 1.
• Set subject.modified to current timestamp.
• Set gfv.active_since to current timestamp.
• Persist changes.

§ [MOD-GF-QRY-1] Get Governance Framework Version

Anyone CAN execute this method.

§ [MOD-GF-QRY-1-1] Get Governance Framework Version query parameters

• id (uint64) (mandatory): the id of the GovernanceFrameworkVersion.
• preferred_language (string) (optional): if set, return only one document per version, preferring preferred_language. If not set, return all documents of all languages.

§ [MOD-GF-QRY-1-2] Get Governance Framework Version query checks

If any of these checks fail, query MUST fail.

• id (uint64) (mandatory): MUST be a valid uint64.

§ [MOD-GF-QRY-1-3] Get Governance Framework Version execution

Return the GovernanceFrameworkVersion entry with id, including its owning subject reference (ecosystem_id or corporation) and its nested GovernanceFrameworkDocument entries (filtered by preferred_language if set).

§ [MOD-GF-QRY-2] List Governance Framework Versions

Anyone CAN execute this method.

§ [MOD-GF-QRY-2-1] List Governance Framework Versions query parameters

Exactly one of ecosystem_id and corporation MUST be set:

• ecosystem_id (uint64) (conditional): filter by ecosystem. MUST be set if corporation is null.
• corporation (group) (conditional): filter by corporation (the underlying Cosmos SDK group of the target Corporation). MUST be set if ecosystem_id is null.
• active_only (boolean) (optional): if true, return only the entry corresponding to the subject’s active_version.
• preferred_language (string) (optional): if set, return only one document per version, preferring preferred_language.
• response_max_size (small number) (optional): default to 64. Max 1,024.

§ [MOD-GF-QRY-2-2] List Governance Framework Versions query checks

If any of these checks fail, query MUST fail.

• Exactly one of ecosystem_id and corporation MUST be set.
• response_max_size must be between 1 and 1,024. Default to 64 if unspecified.

§ [MOD-GF-QRY-2-3] List Governance Framework Versions execution

Return the list of GovernanceFrameworkVersion entries matching the filter, with their nested GovernanceFrameworkDocument entries (filtered as above). Entries MUST be ordered by ascending version.

§ Credential Schema Module

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

Any authorized operator CAN execute this method on behalf of a corporation.

§ [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:

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• ecosystem_id id of the ecosystem (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_onboarding_mode (IssuerOnbpardingMode) (mandatory).
• verifier_onboarding_mode (VerifierOnboardingMode) (mandatory).
• holder_onboarding_mode (HolderOnboardingMode) (mandatory).
• pricing_asset_type (PricingAssetType) (mandatory).
• pricing_asset (string) (mandatory).
• digest_algorithm (string) (mandatory): valid values are defined in the Verifiable Trust spec.

§ [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.

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• ecosystem_id MUST represent an existing Ecosystem entry ecosystem and ecosystem.corporation MUST be the corporation 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 is ignored and 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_onboarding_mode (IssuerOnbpardingMode) (mandatory). MUST be a valid IssuerOnboardingMode.

• verifier_onboarding_mode (VerifierOnboardingMode) (mandatory). MUST be a valid VerifierOnboardingMode.

• holder_onboarding_mode (HolderOnboardingMode) (mandatory). MUST be a valid HolderOnboardingMode.

• digest_algorithm (string) (mandatory) MUST be a valid digest algorithm as defined in the Verifiable Trust spec.

• pricing_asset_type (PricingAssetType) (mandatory): used asset for paying business fees. Can be TU (Trust Unit), COIN (a token available on the VPR chain), FIAT (means chain is used for settlement only and payment is done off-chain). Not that in all cases, trust deposits are always handled in denom.

• pricing_asset (string) (mandatory): "tu" if pricing_asset_type is set to TU, else examples: COIN: denom "uvna", "ufoo", "ibc/3A0F9C2E4E2A9B7D6F...", "factory/verana1.../ueurv", FIAT: "EUR", "GBP",…

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

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

§ [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.

• create and persist a new CredentialSchema entry cs:

  • cs.id: auto-incremented uint64.
  • cs.ecosystem_id: id of the Ecosystem entry that will be the owner of cs.
  • cs.json_schema: json_schema, with VPR_CREDENTIAL_SCHEMA_ID string replaced by generated cs.id, and then canonicalize it using the JSON Canonicalization Scheme (JCS) as defined in RFC 8785. Schema MUST be saved canonized.
  • 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_onboarding_mode: issuer_onboarding_mode
  • cs.verifier_onboarding_mode: verifier_onboarding_mode
  • cs.holder_onboarding_mode: holder_onboarding_mode
  • cs.created: current timestamp
  • cs.modified: cs.created.
  • cs.pricing_asset_type: pricing_asset_type
  • cs.pricing_asset: pricing_asset
  • cs.digest_algorithm: digest_algorithm

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

Any authorized operator CAN execute this method on behalf of a corporation.

§ [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:

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• 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.

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• id MUST represent an existing CredentialSchema entry cs.

• load Ecosystem ecosystem from cs.ecosystem_id. ecosystem.corporation MUST be the corporation 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

Fee payer 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.modified: current timestamp.

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

Any authorized operator CAN execute this method on behalf of a corporation.

§ [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:

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• 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.

• corporation (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.

• id MUST represent an existing CredentialSchema entry cs.

• load Ecosystem ecosystem from cs.ecosystem_id. ecosystem.corporation MUST be the corporation 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

Fee payer 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-MSG-5] Create Schema Authorization Policy

Any authorized operator CAN execute this method on behalf of a corporation.

This message creates a draft SchemaAuthorizationPolicy for a given (schema_id, role), or overwrites the existing draft policy if one already exists.
A draft policy is defined as a policy with effective_from == null and MUST NOT be revoked.

Accordingly, if a credential schema defines one or more active policies for the ISSUER or VERIFIER role, the corresponding corporation that grants the ISSUER or VERIFIER role for this schema (ISSUER_GRANTOR, VERIFIER_GRANTOR, or ECOSYSTEM, depending on how schema issuer and verifier modes have been configured) MUST issue an IAC or VAC credential to the candidate upon successful completion of the onboarding process. Refer to the Verifiable Trust spec for more information.

§ [MOD-CS-MSG-5-1] Create Schema Authorization Policy parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• schema_id (uint64): id of the related CredentialSchema (mandatory).
• role (SchemaAuthorizationPolicyRole): ISSUER or VERIFIER (mandatory).
• url (string): URL where the policy document is published (mandatory).
• digest_sri (string): SRI digest of the policy document (mandatory).

§ [MOD-CS-MSG-5-2] Create Schema Authorization Policy precondition checks

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

§ [MOD-CS-MSG-5-2-1] Create Schema Authorization Policy basic checks

• if a mandatory parameter is not present, method MUST abort.
• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• schema_id MUST reference an existing CredentialSchema entry controlled by corporation.
• role MUST be a valid SchemaAuthorizationPolicyRole.
• url MUST be a non-empty valid URI.
• digest_sri MUST be non-empty.
• there MUST NOT exist more than one policy for (schema_id, role) with effective_from == null and revoked == false.

§ [MOD-CS-MSG-5-2-2] Create Schema Authorization Policy fee checks

Fee payer MUST have an available balance in its account to cover the required estimated transaction fees.

§ [MOD-CS-MSG-5-3] Create Schema Authorization Policy 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:

• if a draft policy exists for (schema_id, role):
  • update the existing policy by setting:
    • url = url
    • digest_sri = digest_sri
• otherwise, create and persist a new SchemaAuthorizationPolicy entry sap:
  • sap.id: auto-incremented uint64
  • sap.schema_id: schema_id
  • sap.role: role
  • sap.version: max existing version for (schema_id, role) + 1, or 1 if none exist
  • sap.url: url
  • sap.digest_sri: digest_sri
  • sap.created: current timestamp
  • sap.effective_from: null
  • sap.effective_until: null
  • sap.revoked: false

§ [MOD-CS-MSG-6] Increase Active Schema Authorization Policy Version

Any authorized operator CAN execute this method on behalf of a corporation.

This message activates the current draft SchemaAuthorizationPolicy for the given (schema_id, role) and deactivates any previously active version. Deactivation does not constitute revocation; credentials issued under earlier policies MAY continue to be considered valid.

§ [MOD-CS-MSG-6-1] Increase Active Schema Authorization Policy Version parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• schema_id (uint64): id of the related CredentialSchema (mandatory).
• role (SchemaAuthorizationPolicyRole): ISSUER or VERIFIER (mandatory).

§ [MOD-CS-MSG-6-2] Increase Active Schema Authorization Policy Version precondition checks

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

§ [MOD-CS-MSG-6-2-1] Basic checks

• if a mandatory parameter is not present, method MUST abort.
• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• schema_id MUST reference an existing CredentialSchema entry controlled by corporation.
• exactly one draft policy MUST exist for (schema_id, role) with effective_from == null and revoked == false.
• the draft policy MUST have non-empty url and digest_sri.

§ [MOD-CS-MSG-6-2-2] Fee checks

Fee payer MUST have an available balance in its account to cover the required estimated transaction fees.

§ [MOD-CS-MSG-6-3] Increase Active Schema Authorization Policy Version execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks atomically in a transaction:

• let draft be the unique policy with effective_from == null and revoked == false.
• let prev_active be the active policy for (schema_id, role), if any.
• set draft.effective_from = now.
• if prev_active exists:
  • set prev_active.effective_until = now.

§ [MOD-CS-MSG-7] Revoke Schema Authorization Policy

Any authorized operator CAN execute this method on behalf of a corporation.

This message revokes a previously enabled SchemaAuthorizationPolicy version. Revoked means previously issued credential that refer to this policy are automatically considered revoked.

§ [MOD-CS-MSG-7-1] Revoke Schema Authorization Policy parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• schema_id (uint64): id of the related CredentialSchema (mandatory).
• role (SchemaAuthorizationPolicyRole): ISSUER or VERIFIER (mandatory).
• version (integer): policy version to revoke (mandatory).

§ [MOD-CS-MSG-7-2] Revoke Schema Authorization Policy precondition checks

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

§ [MOD-CS-MSG-7-2-1] Basic checks

• if a mandatory parameter is not present, method MUST abort.
• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• a policy MUST exist for (schema_id, role, version).
• the targeted policy MUST have effective_from != null (a policy that has never been enabled MUST NOT be revoked).
• the targeted policy MUST NOT already be revoked.

§ [MOD-CS-MSG-7-2-2] Fee checks

Fee payer MUST have an available balance in its account to cover the required estimated transaction fees.

§ [MOD-CS-MSG-7-3] Revoke Schema Authorization Policy execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following task in a transaction:

• set revoked = true on the targeted SchemaAuthorizationPolicy entry.

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

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

• ecosystem_id (uint64) (optional): to filter by ecosystem 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_onboarding_mode (IssuerOnboardingMode): if set, filter by issuer_onboarding_mode.
• verifier_onboarding_mode (VerifierOnboardingMode): if set, filter by verifier_onboarding_mode.
• holder_onboarding_mode (HolderOnboardingMode): if set, filter by holder_onboarding_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 DESC.

§ [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”.

Schema MUST be rendered cononized, even if it was not created canonized using the JSON Canonicalization Scheme (JCS) as defined in RFC 8785.

§ [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",
    ...
    ...
  }
}

§ [MOD-CS-QRY-5] Get Schema Authorization Policy

This query returns a single SchemaAuthorizationPolicy identified by its unique id.

§ [MOD-CS-QRY-5-1] Get Schema Authorization Policy parameters

• id (uint64): unique identifier of the SchemaAuthorizationPolicy (mandatory).

§ [MOD-CS-QRY-5-2] Get Schema Authorization Policy precondition checks

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

• id MUST be provided.
• a SchemaAuthorizationPolicy entry with the given id MUST exist.

§ [MOD-CS-QRY-5-3] Get Schema Authorization Policy execution

If all precondition checks pass, the query MUST return the corresponding SchemaAuthorizationPolicy entry:

• id
• schema_id
• role
• version
• url
• digest_sri
• created
• effective_from
• effective_until
• revoked

§ [MOD-CS-QRY-6] List Schema Authorization Policies

This query returns the list of SchemaAuthorizationPolicy entries associated with a given (schema_id, role) pair.

§ [MOD-CS-QRY-6-1] List Schema Authorization Policies parameters

• schema_id (uint64): id of the related CredentialSchema (mandatory).
• role (SchemaAuthorizationPolicyRole): ISSUER or VERIFIER (mandatory).

§ [MOD-CS-QRY-6-2] List Schema Authorization Policies precondition checks

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

• schema_id MUST be provided.
• role MUST be a valid SchemaAuthorizationPolicyRole.
• schema_id MUST reference an existing CredentialSchema entry.

§ [MOD-CS-QRY-6-3] List Schema Authorization Policies execution

If all precondition checks pass, the query MUST return the list of SchemaAuthorizationPolicy entries matching (schema_id, role).

Returned entries MUST include at least the following fields:

• id
• schema_id
• role
• version
• url
• digest_sri
• created
• effective_from
• effective_until
• revoked

Entries MUST be ordered by ascending version.

§ Participant Module

§ Participant Module Overview

This section is non-normative.

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

ECOSYSTEM Participants are created directly by the credential schema owner. All other Participants are created by running an onboarding process — except when onboarding mode is set to OPEN for ISSUER and/or VERIFIER Participants, which any account CAN create directly:

• ISSUER Participants when issuer_onboarding_mode is OPEN;
• VERIFIER Participants when verifier_onboarding_mode is OPEN.

An onboarding process (OP) involves an applicant (the corporation of a given Participant entry) and a validator Participant. It MAY require the applicant to pay validation_fees in addition to transaction fees.

An onboarding process is run 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;
• obtain a HOLDER Participant entry from an issuer of a specific credential schema and be issued a verifiable credential of that schema (the HOLDER Participant entry carries credential status — revoked, etc.).

In all cases, the process is very similar. Example execution of an onboarding process:

1. The applicant starts an onboarding process by running [MOD-PP-MSG-1]. The process MAY be subject to paying validation_fees, as defined in the validator's Participant entry.
2. The applicant connects to the validator's VS (identified by its DID) and executes the validation steps required for the onboarding process to conclude.
3. If the applicant qualifies, the validator runs [MOD-PP-MSG-3] to update the Participant entry; the applicant is then granted the new Participant entries and/or issued a credential.

Once in the VALIDATED state, a Participant entry remains valid for a specific period (e.g., 365 days), configured in the credential schema for credential-schema-related onboarding, or set by the ecosystem for user-agent onboarding.

If the VALIDATED state is set to expire, an applicant that wishes to extend the expiration timestamp MUST renew its onboarding process (see [MOD-PP-MSG-2]).

At any time, the applicant CAN cancel the onboarding process (see [MOD-PP-MSG-6]).

Some unexpected situations may arise and MUST be mitigated. Examples:

• if the selected validator Participant entry is revoked while the applicant is in PENDING state: applicant CAN cancel the onboarding process (see [MOD-PP-MSG-6]);
• if the selected validator Participant entry is revoked while the applicant is in VALIDATED state: applicant CAN renew the onboarding process by choosing a new validator (see [MOD-PP-MSG-2]).

§ [MOD-PP-MSG-1] Start Participant OP

Any authorized operator CAN execute this method on behalf of a corporation.

§ [MOD-PP-MSG-1-1] Start Participant OP parameters

An Applicant that would like to start an onboarding process MUST execute this method by specifying:

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• vs_operator (account) (optional): the account of the Veriable Service we want to authorize to create participant sessions linked to this participant. If not specified, Verifiable Service will not be able to use the payment delegation feature. Required to use the payment delegation feature.
• role (ParticipantRole) (mandatory): (ISSUER_GRANTOR, VERIFIER_GRANTOR, ISSUER, VERIFIER, HOLDER): the Participant role that the applicant would like to get;
• validator_participant_id (uint64) (mandatory): the validator participant (parent participant in the tree), chosen by the applicant.
• validation_fees (number) (optional): Requested validation_fees for this participant (can be modified by validator).
• issuance_fees (number) (optional): Requested issuance_fees for this Participant entry (can be modified by validator).
• verification_fees (number) (optional): Requested verification_fees for this Participant entry (can be modified by validator).
• did (string) (required): MUST conform to the DID Syntax, as specified [DID-CORE].

The following VS Operator Authorization parameters are optional and collectively define the initial ParticipantAuthorizationRecord that will be created for this Participant entry. Presence of vs_operator_authz_msg_types is the trigger: if it is not provided, no authorization record is created and the Participant entry operates in manual mode (the corporation signs and pays for its own Participant-related transactions directly). VSOA configuration is frozen at creation time and cannot be modified later; to change it, the Participant entry MUST be revoked and re-created.

• vs_operator_authz_msg_types[] (msg_type[]) (optional): list of VPR delegable message types vs_operator is authorized to execute on behalf of corporation in the context of this Participant entry. If provided, a ParticipantAuthorizationRecord is created (see execution below) and vs_operator MUST be specified. The permitted list of message types is provided below.
• vs_operator_authz_spend_limit (DenomAmount[]) (optional): maximum amount of funds vs_operator is allowed to spend in the context of this Participant entry as a direct consequence of executing authorized messages.
• vs_operator_authz_with_feegrant (bool) (optional, default: false): if true, corporation pays transaction fees for vs_operator via an on-chain FeeGrant when executing authorized messages in the context of this Participant entry.
• vs_operator_authz_fee_spend_limit (DenomAmount[]) (optional): maximum total amount of transaction fees that can be spent by vs_operator (paid by corporation via fee grant) in the context of this Participant entry.
• vs_operator_authz_period (duration) (optional): reset period for vs_operator_authz_spend_limit and vs_operator_authz_fee_spend_limit in the context of this Participant entry.

Permitted message types to be set in vs_operator_authz_msg_types depends on role.

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

§ [MOD-PP-MSG-1-2] Start Participant OP precondition checks

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

§ [MOD-PP-MSG-1-2-1] Start Participant OP basic checks

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• role (ParticipantRole) (mandatory) MUST be a valid ParticipantRole: ISSUER_GRANTOR, VERIFIER_GRANTOR, ISSUER, VERIFIER, HOLDER.
• validator_participant_id (uint64) (mandatory): see MOD-PP-MSG-1-2-2.
• validation_fees (number) (optional): Requested validation_fees for this Participant entry (can be modified by validator).
• issuance_fees (number) (optional): Requested issuance_fees for this Participant entry (can be modified by validator).
• verification_fees (number) (optional): Requested verification_fees for this Participant entry (can be modified by validator).
• did, if specified, MUST conform to the DID Syntax, as specified [DID-CORE].
• if did is specified and any existing Participant entry has non-null did equal to the provided did, its corporation MUST equal the signing corporation; else method MUST abort (per-Participant (did, corporation) consistency invariant: at any block height, all Participant entries sharing a non-null did are owned by the same Corporation).
• VS Operator Authorization parameters: if any of vs_operator_authz_* parameters is provided, vs_operator_authz_msg_types MUST also be provided and vs_operator MUST NOT be null, else abort. If vs_operator_authz_msg_types is provided, it MUST be a non-empty list of VPR delegable message types, and match the permitted messages defined in MOD-PP-MSG-1-1.

§ [MOD-PP-MSG-1-2-2] Start Participant OP permission checks

• Load Participant entry validator_participant from validator_participant_id. It MUST be a active participant else transaction MUST abort.

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

• if role (ParticipantRole) is equal to ISSUER:

  • if cs.issuer_onboarding_mode is equal to GRANTOR_ONBOARDING_PROCESS: validator_participant.role MUST be ISSUER_GRANTOR, else MUST abort.

  • else if cs.issuer_onboarding_mode is equal to ECOSYSTEM_ONBOARDING_PROCESS: validator_participant.role MUST be ECOSYSTEM, else MUST abort.

  • else MUST abort.

• else if role (ParticipantRole) is equal to ISSUER_GRANTOR:

  • if cs.issuer_onboarding_mode is equal to GRANTOR_ONBOARDING_PROCESS: validator_participant.role MUST be ECOSYSTEM, else MUST abort.

  • else abort.

• else if role (ParticipantRole) is equal to VERIFIER:

  • if cs.verifier_onboarding_mode is equal to GRANTOR_ONBOARDING_PROCESS: validator_participant.role MUST be VERIFIER_GRANTOR, else MUST abort.

  • else if cs.verifier_onboarding_mode is equal to ECOSYSTEM_ONBOARDING_PROCESS: validator_participant.role MUST be ECOSYSTEM, else MUST abort.

  • else abort.

• else if role (ParticipantRole) is equal to VERIFIER_GRANTOR:

  • if cs.verifier_onboarding_mode is equal to GRANTOR_ONBOARDING_PROCESS: validator_participant.role MUST be ECOSYSTEM, else MUST abort.

  • else abort.

• else if role (ParticipantRole) is equal to HOLDER:

  • if cs.holder_onboarding_mode is equal to ISSUER_ONBOARDING_PROCESS: validator_participant.role MUST be ISSUER, else MUST abort.

  • else abort.

At the end, if a active participant validator_participant is not found, transaction MUST abort.

§ [MOD-PP-MSG-1-2-3] Start Participant OP fee checks

• Load Participant entry validator_participant from validator_participant_id.

• Load CredentialSchema entry cs from validator_participant.schema_id.

• Fee payer MUST have an available balance in its account, to cover the estimated transaction fees;

If a conversion is needed below, use Get Price to convert amounts to native denom:

• For trust fees:

if (cs.pricing_asset_type, cs.pricing_asset) is set to (COIN, [[ref: native denom]]):

• corporation MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = validator_participant.validation_fees in native denom.
  • the required validation_trust_deposit_in_native_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to (TU, "tu"):

• corporation MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validator_participant.validation_fees) in native denom;
  • the required validation_trust_deposit_in_native_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to an arbitrary coin (COIN, [[ref: denom]]):

• corporation MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = validator_participant.validation_fees in specified (cs.pricing_asset_type, cs.pricing_asset)
  • the required validation_trust_deposit_in_native_denom: getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validation_fees_in_denom) * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to an arbitrary coin (FIAT, [[ref: denom]]):

• corporation MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = 0 in native denom.
  • the required validation_trust_deposit_in_native_denom: getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validator_participant.validation_fees) * GlobalVariables.trust_deposit_rate in native denom.

§ [MOD-PP-MSG-1-2-4] Start Participant OP overlap checks

We want to make sure that 2 onboarding processes cannot be active at the same time in the same context. This does not prevent a corporation from running different OP with differents validators for the same schema_id, role.

Find all Participant entries participants[] for schema_id, role, validator_participant_id, corporation with op_state = VALIDATED or PENDING.

if size of participants[] > 0, it means there is already an existing onboarding process in this context, so MUST abort.

note: this check was not present in v3.

§ [MOD-PP-MSG-1-3] Start Participant OP 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 Participant entry validator_participant of the selected validator.

• calculate validation_fees_in_denom and validation_trust_deposit_in_native_denom as explained above in fee checks.

• use [MOD-TD-MSG-1] to increase by validation_trust_deposit_in_native_denom the trust deposit of corporation 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 Participant entry applicant_participant:

  • applicant_participant.id: auto-incremented uint64.
  • applicant_participant.schema_id = validator_participant.schema_id
  • applicant_participant.corporation: corporation.
  • applicant_participant.vs_operator: vs_operator.
  • applicant_participant.role: role.
  • applicant_participant.created: now
  • applicant_participant.modified: now
  • applicant_participant.deposit: validation_trust_deposit_in_native_denom.
  • applicant_participant.validation_fees: validation_fees.
  • applicant_participant.issuance_fees: issuance_fees.
  • applicant_participant.verification_fees: verification_fees.
  • applicant_participant.validator_participant_id: validator_participant_id.
  • applicant_participant.op_last_state_change: now
  • applicant_participant.op_state: PENDING.
  • applicant_participant.op_current_fees (number): validation_fees_in_denom.
  • applicant_participant.op_current_deposit (number): validation_trust_deposit_in_native_denom.
  • applicant_participant.op_summary_digest: null.
  • applicant_participant.op_validator_deposit: 0.

If vs_operator_authz_msg_types is provided, create the ParticipantAuthorizationRecord in disabled state (expiration = now) by calling [MOD-DE-MSG-5] Grant VS Operator Authorization with:

• corporation: corporation
• vs_operator: vs_operator
• record:
  • record.participant_id: applicant_participant.id
  • record.msg_types: vs_operator_authz_msg_types
  • record.spend_limit: vs_operator_authz_spend_limit
  • record.fee_spend_limit: vs_operator_authz_fee_spend_limit
  • record.with_feegrant: vs_operator_authz_with_feegrant (default: false)
  • record.expiration: now
  • record.period: vs_operator_authz_period

Note: the record is created with expiration = now so authorization is not yet active. [AUTHZ-CHECK-3] will reject any attempt to use it until [MOD-PP-MSG-3] updates expiration to applicant_participant.effective_until. No on-chain FeeGrant object is created at this stage even if with_feegrant is true (the recompute subroutine in [MOD-DE-MSG-5-5] requires expiration > now).

§ 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 an onboarding process, if the associated validator_participant 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.

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 vs_operator account specified in the Participant entry (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 Participant entry 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 onboarding process and create the Participant entry accordingly. This Participant-entry configuration usually includes:

• validation_fees
• issuance_fees
• verification_fees
• Participant expiration

The validator may compile a summary file of the onboarding 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_participant.op_summary_digest.

§ [MOD-PP-MSG-2] Renew Participant OP

Any authorized operator CAN execute this method on behalf of a corporation.

This section is non-normative.

• Requesting a renewal has no effect on Participant expiration or issued credentials.
• Renewal is only possible with the same validator.
• If validator Participant is not valid anymore, applicant MUST perform a new onboarding process with another validator.
• Renewal does not allow changing the participant.validation_fees, participant.issuance_fees, participant.verification_fees. To change these values, applicant MUST start a new onboarding process.
• if applicant_participant is revoked, slashed, or repaid, method MUST fail.

§ [MOD-PP-MSG-2-1] Renew Participant OP parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• id (uint64) (mandatory): id of the Participant entry for which applicant would like to renew the onboarding process;

§ [MOD-PP-MSG-2-2] Renew Participant OP precondition checks

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

§ [MOD-PP-MSG-2-2-1] Renew Participant OP basic checks

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• id MUST be a valid uint64 and a Participant entry with the same id MUST exist.

§ [MOD-PP-MSG-2-2-2] Renew Participant OP permission checks

• Load Participant entry applicant_participant. corporation running the operation MUST be applicant_participant.corporation, else MUST abort. applicant_participant MUST be a active participant.
• Load Participant entry validator_participant from applicant_participant.validator_participant_id. It MUST exist, and be a active participant, else MUST abort.

§ [MOD-PP-MSG-2-2-3] Renew Participant OP fee checks

• Load Participant entry validator_participant from applicant_participant.validator_participant_id.

• Load CredentialSchema entry cs from validator_participant.schema_id.

• Fee payer MUST have an available balance in its account, to cover the estimated transaction fees;

If a conversion is needed below, use Get Price to convert amounts to native denom:

• For trust fees:

if (cs.pricing_asset_type, cs.pricing_asset) is set to (COIN, [[ref: native denom]]):

• corporation MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = validator_participant.validation_fees in native denom.
  • the required validation_trust_deposit_in_native_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to (TU, "tu"):

• corporation MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validator_participant.validation_fees) in native denom;
  • the required validation_trust_deposit_in_native_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to an arbitrary coin (COIN, [[ref: denom]]):

• corporation MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = validator_participant.validation_fees in specified (cs.pricing_asset_type, cs.pricing_asset)
  • the required validation_trust_deposit_in_native_denom: getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validation_fees_in_denom) * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to an arbitrary coin (FIAT, [[ref: denom]]):

• corporation MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = 0 in native denom.
  • the required validation_trust_deposit_in_native_denom: getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validator_participant.validation_fees) * GlobalVariables.trust_deposit_rate in native denom.

§ [MOD-PP-MSG-2-3] Renew Participant OP 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 Participant entry applicant_participant.

• Load Participant entry validator_participant from applicant_participant.validator_participant_id.

• calculate validation_fees_in_denom and validation_trust_deposit_in_native_denom as explained above in fee checks.

• use [MOD-TD-MSG-1] to increase by validation_trust_deposit_in_native_denom the trust deposit of corporation 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 Participant entry:

  • applicant_participant.op_state: PENDING.
  • applicant_participant.op_last_state_change: current timestamp.
  • applicant_participant.deposit: applicant_participant.deposit + validation_trust_deposit_in_native_denom.
  • applicant_participant.op_current_fees (number): validation_fees_in_denom.
  • applicant_participant.op_current_deposit (number): validation_trust_deposit_in_native_denom.
  • applicant_participant.modified: now

§ [MOD-PP-MSG-3] Set Participant OP to Validated

Any authorized operator CAN execute this method on behalf of a corporation.

§ [MOD-PP-MSG-3-1] Set Participant OP to Validated parameters

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

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• id (uint64) (mandatory): id of the onboarding process;
• effective_until (timestamp) (optional): timestamp until when (exclusive) this Participant is effective, null if no time limit should been set for this Participant entry or if we want it to be aligned with the onboarding process expiration timestamp calculated by this method.
• validation_fees (number) (mandatory): Agreed validation_fees for this Participant entry. Can be set only the first time this method is called (cannot be set for renewals). Use 0 for no fees.
• issuance_fees (number) (mandatory): Agreed issuance_fees for this Participant entry. Can be set only the first time this method is called (cannot be set for renewals). Use 0 for no fees.
• verification_fees (number) (mandatory): Agreed verification_fees for this Participant entry. Can be set only the first time this method is called (cannot be set for renewals). Use 0 for no fees.
• op_summary_digest (string) (optional): an optional digest, set by validator, of a summary of the information, proofs… provided by the applicant.
• issuance_fee_discount: (number) (mandatory): use 0 for no discount. Maximum 1 (100% discount). Can be set to an ISSUER_GRANTOR or ISSUER Participant entry (if GRANTOR_ONBOARDING_PROCESS mode) or to an ISSUER Participant entry (ECOSYSTEM_ONBOARDING_PROCESS mode) to reduce (or void) calculated issuance fees for the subtree of Participant entries. Note: this should generally not be used because it reduces or void commission of all related ecosystem participants.
• verification_fee_discount: (number) (mandatory): use 0 for no discount. Maximum 1 (100% discount). Can be set to a VERIFIER_GRANTOR or VERIFIER Participant entry (if GRANTOR_ONBOARDING_PROCESS mode) and/or to a VERIFIER Participant entry (ECOSYSTEM_ONBOARDING_PROCESS mode) to reduce (or void) calculated fees for the subtree of Participant entries. Note: this should generally not be used because it reduces or void commission of all related ecosystem participants.

§ [MOD-PP-MSG-3-2] Set Participant OP to Validated precondition checks

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

§ [MOD-PP-MSG-3-2-1] Set Participant OP to Validated basic checks

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• id MUST be a valid uint64.
• Load Participant entry applicant_participant from id. If no entry found, abort.
• Load Participant entry validator_participant from applicant_participant_validator_participant_id.
• Authorization:

either (executed by any operator of corporation): [AUTHZ-CHECK-1] MUST pass for this (corporation, operator) tuple and SetParticipantOPtoValidated message. [AUTHZ-CHECK-2] MUST pass for this (corporation, operator) tuple and SetParticipantOPtoValidated message. OR (executed by vs-agent account defined in validator Participant): [AUTHZ-CHECK-3] MUST pass for this (corporation, operator, validator_participant) tuple. [AUTHZ-CHECK-4] MUST pass for this (corporation, operator, validator_participant) tuple. else MUST abort.

• applicant_participant.op_state MUST be equal to PENDING, else abort.

• validation_fees (number) (mandatory): MUST be zero or a positive integer. If applicant_participant.effective_from is not null (we are in renewal) validation_fees MUST be equal to applicant_participant.validation_fees, else abort.

• issuance_fees (number) (mandatory): MUST be zero or a positive integer. If applicant_participant.effective_from is not null (we are in renewal) issuance_fees MUST be equal to applicant_participant.issuance_fees or, else abort.

• verification_fees (number) (mandatory): MUST be zero or a positive integer. If applicant_participant.effective_from is not null (we are in renewal) verification_fees MUST be equal to applicant_participant.verification_fees, else abort.

• op_summary_digest (string) (optional): MUST be a valid digest. Example: sha384-MzNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26.

• Load CredentialSchema cs from applicant_participant.schema_id.

• Load Participant validator_participant from applicant_participant.validator_participant_id.

• issuance_fee_discount : (number) (mandatory):

  • if applicant_participant.effective_from is not null (renewal), then issuance_fee_discount must be equal to applicant_participant.issuance_fee_discount else MUST abort.
  • if cs.issuer_onboarding_mode is set to GRANTOR_ONBOARDING_PROCESS:
    • if applicant_participant.role == ISSUER_GRANTOR: issuance_fee_discount can be set between 0 (no discount) and 1 (100% discount) inclusive.
    • if applicant_participant.role == ISSUER: if validator_participant.issuance_fee_discount is defined, issuance_fee_discount can be set between 0 (no discount) and validator_participant.issuance_fee_discount (100% discount) inclusive.
  • if cs.issuer_onboarding_mode is set to ECOSYSTEM_ONBOARDING_PROCESS:
    • if applicant_participant.role == ISSUER: issuance_fee_discount can be set between 0 (no discount) and 1 (100% discount) inclusive.
  • else MUST abort.

• verification_fee_discount : (number) (mandatory):

  • if applicant_participant.effective_from is not null (renewal), then verification_fee_discount must be equal to applicant_participant.verification_fee_discount else MUST abort.
  • if cs.verifier_onboarding_mode is set to GRANTOR_ONBOARDING_PROCESS:
    • if applicant_participant.role == VERIFIER_GRANTOR: verification_fee_discount can be set between 0 (no discount) and 1 (100% discount) inclusive.
    • if applicant_participant.role == VERIFIER: if validator_participant.verification_fee_discount is defined, verification_fee_discount can be set between 0 (no discount) and validator_participant.verification_fee_discount (100% discount) inclusive.
  • if cs.verifier_onboarding_mode is set to ECOSYSTEM_ONBOARDING_PROCESS:
    • if applicant_participant.role == VERIFIER: verification_fee_discount can be set between 0 (no discount) and 1 (100% discount) inclusive.
  • else MUST abort.

Calculation of op_exp, the onboarding process expiration timestamp, required to verify provided effective_until:

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

• if validity_period is NULL: op_exp = NULL.

• else if applicant_participant.op_exp is null, op_exp = timestamp of now() plus validity_period.

• else op_exp = applicant_participant.op_exp plus validity_period

Now, let’s verify effective_until:

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

§ [MOD-PP-MSG-3-2-2] Set Participant OP to Validated validator perms

• load validator_participant from applicant_participant.validator_participant_id. validator_participant MUST be a active participant.
• corporation running the method MUST be validator_participant.corporation.

If validator_participant is not a active participant (expired, revoked, slashed…) then applicant MUST start a new onboarding process.

§ [MOD-PP-MSG-3-2-3] Set Participant OP to Validated fee checks

• Fee payer MUST have the required estimated transaction fees in its account, else transaction MUST abort.
• if applicant_participant.op_current_fees is not in native denom, corporation account MUST have applicant_participant.op_current_deposit available in native denom on its account for paying the trust deposit.

§ [MOD-PP-MSG-3-2-4] Set Participant OP to Validated overlap checks

We want to make sure that 2 Participant entries cannot be active at the same time for the same validator_participant_id. That should not occur in this method, but better do the check anyway.

Find all active participants participants[] (not revoked, not slashed, not repaid) for schema_id, role, validator_participant_id, corporation.

for each Participant entry p from participants[]:

• if p.effective_until is greater than effective_from, method execution MUST abort.
• if p.effective_from is lower than effective_until, method execution MUST abort.
• if p.effective_until is NULL (never expire), creation of a new Participant entry doesn’t make any sense and method execution MUST abort.

note: this check was not present in v3.

§ [MOD-PP-MSG-3-3] Set Participant OP 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 Participant entry applicant_participant from id.
• Load Participant entry validator_participant from applicant_participant.validator_participant_id.
• define now timestamp of now().

Calculate op_exp:

• Load CredentialSchema cs from applicant_participant.schema_id.

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

• if validity_period is NULL: op_exp = NULL.

• else if applicant_participant.op_exp is null, op_exp = timestamp of now() plus validity_period.

• else op_exp = applicant_participant.op_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 op_exp.

• else if applicant_participant.effective_until is NULL:

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

• else:

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

Fees and Trust Deposits:

• transfer the full amount applicant_participant.op_current_fees in the proper denom from escrow account to validator corporation account validator_participant.corporation;
• Increase validator perm trust deposit: use [MOD-TD-MSG-1] to increase by applicant_participant.op_current_deposit the trust deposit of corporation running the method and transfer the corresponding amount to TrustDeposit module. Set applicant_participant.op_validator_deposit to applicant_participant.op_validator_deposit + applicant_participant.op_current_deposit.

Important: if applicant_participant.op_current_fees is not in native denom, corporation account MUST have applicant_participant.op_current_deposit available for paying the trust deposit.

Update Participant applicant_participant:

• set applicant_participant.modified to now.
• set applicant_participant.op_state to VALIDATED.
• set applicant_participant.op_last_state_change to now.
• set applicant_participant.op_current_fees to 0;
• set applicant_participant.op_current_deposit to 0;
• set applicant_participant.op_summary_digest to op_summary_digest.
• set applicant_participant.op_exp to op_exp.
• set applicant_participant.effective_until to effective_until.
• if applicant_participant.effective_from IS NULL (first time method is called for this perm, and thus we are not in a renewal):
  • set applicant_participant.validation_fees to validation_fees;
  • set applicant_participant.issuance_fees to issuance_fees;
  • set applicant_participant.verification_fees to verification_fees;
  • set applicant_participant.effective_from to now.
  • set applicant_participant.issuance_fee_discount to issuance_fee_discount.
  • set applicant_participant.verification_fee_discount to verification_fee_discount.

Activate VS Operator Authorization, if any. Call [MOD-DE-MSG-9] Update VS Operator Authorization Expiration with:

• participant_id: applicant_participant.id
• new_expiration: applicant_participant.effective_until

This call is a no-op if no record was created at [MOD-PP-MSG-1] (i.e., the applicant did not declare vs_operator_authz_msg_types). If a record exists, its expiration is updated from now (disabled) to applicant_participant.effective_until, and the on-chain FeeGrant for the containing VSOA is granted for the first time (or refreshed) via [MOD-DE-MSG-5-5].

§ [MOD-PP-MSG-4] Void

§ [MOD-PP-MSG-5] Void

§ [MOD-PP-MSG-6] Cancel Participant OP Last Request

Any authorized operator CAN execute this method on behalf of a corporation.

At any time, applicant of an onboarding process may request cancellation of the process, provided state is PENDING. Upon method execution, the pending validation is cancelled and escrewed trust fees are refunded. If op_exp is not null, op_state is set back to VALIDATED, else op_state is set to TERMINATED.

§ [MOD-PP-MSG-6-1] Cancel Participant OP Last Request parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• id (uint64) (mandatory): id of the Participant entry;

§ [MOD-PP-MSG-6-2] Cancel Participant OP Last Request precondition checks

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

§ [MOD-PP-MSG-6-2-1] Cancel Participant OP Last Request basic checks

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• id MUST be a valid uint64.
• Load Participant entry applicant_participant with this id. It MUST exist.
• corporation running the transaction MUST be applicant_participant.corporation.
• applicant_participant.op_state MUST be PENDING.
• if applicant_participant.deposit has been slashed and not repaid, MUST abort

§ [MOD-PP-MSG-6-2-2] Cancel Participant OP Last Request fee checks

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

§ [MOD-PP-MSG-6-3] Cancel Participant OP 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 Participant entry applicant_participant with id. It MUST exist.

• define now: current timestamp.

• set applicant_participant.modified to now.

• if applicant_participant.op_exp is null (validation never completed), set applicant_participant.op_state to TERMINATED, else set applicant_participant.op_state to VALIDATED.

• set applicant_participant.op_last_state_change to now.

• if applicant_participant.op_current_fees > 0:

  • transfer applicant_participant.op_current_fees in proper denom back from escrow account to applicant account, applicant_participant.corporation.
  • set applicant_participant.op_current_fees to 0;

• if applicant_participant.op_current_deposit > 0:

  • call [MOD-TD-MSG-1] to reduce trust deposit of applicant_participant.corporation by applicant_participant.op_current_deposit
  • set applicant_participant.op_current_deposit to 0.

If applicant_participant.op_state was set to TERMINATED (i.e. applicant_participant.op_exp was null so validation never completed), call [MOD-DE-MSG-6] Revoke VS Operator Authorization with participant_id = applicant_participant.id to remove any disabled authorization record created at [MOD-PP-MSG-1]. The call is a no-op if no record exists. If applicant_participant.op_state was set back to VALIDATED, no VSOA changes are needed (the existing record’s expiration remains at the value set by the previous successful validation).

§ [MOD-PP-MSG-7] Create Root Participant

Any authorized operator CAN execute this method on behalf of a corporation.

This method is used by controller authorities of Ecosystems. When they create a Credential Schema, they need to create (a) Participant entry(ies) of role ECOSYSTEM so that other participants can run onboarding processes (if schema mode is ECOSYSTEM) or self create their Participant entries (schema mode set to OPEN).

§ [MOD-PP-MSG-7-1] Create Root Participant parameters

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

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• schema_id (uint64) (mandatory)
• vs_operator (account) (optional): the account we want to authorize to act on behalf of corporation in the context of this Participant entry. Required for payment delegation.
• did (string) (mandatory): DID of the VS.
• effective_from (timestamp) (mandatory): 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 an onboarding process that uses this perm as validator, for a given validation period, in the denom specified in the credential schema. Default to 0. Note that setting validation fees for OPEN schemas has no effect and does not mean an onboarding process must take place. For enabling onboarding 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 the denom specified in the credential schema. 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 the denom specified in the credential schema. Default to 0.

The following VS Operator Authorization parameters are optional and collectively define the initial ParticipantAuthorizationRecord for this Participant entry. Presence of vs_operator_authz_msg_types is the trigger: if it is not provided, no authorization record is created and the Participant entry operates in manual mode. VSOA configuration is frozen at creation time and cannot be modified later; to change it, the Participant entry MUST be revoked and re-created.

• vs_operator_authz_msg_types[] (msg_type[]) (optional): list of VPR delegable message types vs_operator is authorized to execute on behalf of corporation in the context of this Participant entry. If provided, a ParticipantAuthorizationRecord is created (see execution below) and vs_operator MUST be specified. The permitted list of message types is provided below.
• vs_operator_authz_spend_limit (DenomAmount[]) (optional): maximum amount of funds vs_operator is allowed to spend in the context of this Participant entry as a direct consequence of executing authorized messages.
• vs_operator_authz_with_feegrant (bool) (optional, default: false): if true, corporation pays transaction fees for vs_operator via an on-chain FeeGrant when executing authorized messages in the context of this Participant entry.
• vs_operator_authz_fee_spend_limit (DenomAmount[]) (optional): maximum total amount of transaction fees that can be spent by vs_operator (paid by corporation via fee grant) in the context of this Participant entry.
• vs_operator_authz_period (duration) (optional): reset period for vs_operator_authz_spend_limit and vs_operator_authz_fee_spend_limit in the context of this Participant entry.

Permitted message types to be set in vs_operator_authz_msg_types depends on role. Since Create Root Participant always creates an ECOSYSTEM Participant entry, only the following is allowed:

§ [MOD-PP-MSG-7-2] Create Root Participant precondition checks

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

§ [MOD-PP-MSG-7-2-1] Create Root Participant basic checks

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• 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].
• if did is specified and any existing Participant entry has non-null did equal to the provided did, its corporation MUST equal the signing corporation; else method MUST abort (per-Participant (did, corporation) consistency invariant).
• effective_from must be in the future.
• effective_until, if not null, must be greater than effective_from
• validation_fees (number) (mandatory): MUST be >= 0.
• issuance_fees (number) (mandatory): MUST be >= 0.
• verification_fees (number) (mandatory): MUST be >= 0.
• VS Operator Authorization parameters: if any of vs_operator_authz_* parameters is provided, vs_operator_authz_msg_types MUST also be provided and vs_operator MUST NOT be null, else abort. If vs_operator_authz_msg_types is provided, it MUST be a non-empty list of VPR delegable message types, and match the permitted messages defined in MOD-PP-MSG-7-1.

§ [MOD-PP-MSG-7-2-2] Create Root Participant 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 Ecosystem entry ecosystem is loaded from cs.ecosystem_id.
• corporation executing the method MUST be ecosystem.corporation.
• else MUST abort.

§ [MOD-PP-MSG-7-2-3] Create Root Participant fee checks

Fee payer MUST have the required estimated transaction fees available.

§ [MOD-PP-MSG-7-2-4] Create Root Participant overlap checks

We want to make sure that 2 Participant entries cannot be active at the same time. If corporation wishes to create a new Participant entry but the existing one never expires (or expires too far from now), corporation MUST use first the Set Participant Effective Until to set or adjust the effective_until value.

Find all active participants participants[] (not revoked, not slashed, not repaid) for schema_id, ECOSYSTEM, corporation.

Note: unlike overlap checks from other methods, here we do not need to check for validator_participant_id, as for ECOSYSTEM-role Participant entries it is NULL.

for each Participant entry p from participants[]:

• if p.effective_until is greater than effective_from, method execution MUST abort.
• if p.effective_from is lower than effective_until, method execution MUST abort.
• if p.effective_until is NULL (never expire), creation of a new Participant entry doesn’t make any sense and method execution MUST abort.

note: this check was not present in v3.

§ [MOD-PP-MSG-7-3] Create Root Participant 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 Participant perm MUST be created:

• participant.id: auto-incremented uint64.
• participant.schema_id: schema_id.
• participant.modified to now.
• participant.role: ECOSYSTEM.
• participant.did: did.
• participant.corporation: corporation.
• participant.vs_operator: vs_operator.
• participant.created: now
• participant.effective_from: effective_from
• participant.effective_until: effective_until
• participant.validation_fees: validation_fees
• participant.issuance_fees: issuance_fees
• participant.verification_fees: verification_fees
• participant.deposit: 0

If vs_operator_authz_msg_types is provided, create the ParticipantAuthorizationRecord in active state by calling [MOD-DE-MSG-5] Grant VS Operator Authorization with:

• corporation: corporation
• vs_operator: vs_operator
• record:
  • record.participant_id: participant.id
  • record.msg_types: vs_operator_authz_msg_types
  • record.spend_limit: vs_operator_authz_spend_limit
  • record.fee_spend_limit: vs_operator_authz_fee_spend_limit
  • record.with_feegrant: vs_operator_authz_with_feegrant (default: false)
  • record.expiration: participant.effective_until
  • record.period: vs_operator_authz_period

Note: like [MOD-PP-MSG-14], the record is created with expiration = participant.effective_until and is therefore immediately active. If with_feegrant is true and participant.effective_until > now, [MOD-DE-MSG-5-5] grants the on-chain FeeGrant as part of this execution.

§ [MOD-PP-MSG-8] Set Participant Effective Until

Any authorized operator CAN execute this method on behalf of a corporation.

This method can be called:

• by participant.corporation, if the Participant entry has role ECOSYSTEM.
• by participant.corporation, if it is a self-created Participant entry (schema configuration is open).
• by a corporation of a validator Participant, if the Participant entry is managed by an OP.

§ [MOD-PP-MSG-8-1] Set Participant Effective Until parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• id (uint64) (mandatory): id of the Participant entry;
• effective_until (timestamp) (mandatory): timestamp until when (exclusive) this Participant will be effective.

§ [MOD-PP-MSG-8-2] Set Participant Effective Until precondition checks

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

§ [MOD-PP-MSG-8-2-1] Set Participant Effective Until basic checks

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• id MUST be a valid uint64.
• Load Participant entry applicant_participant from id. If no entry found, abort.
• applicant_participant MUST be a active participant
• applicant_participant.effective_until MUST be greater than now().
• else MUST abort.

Note: This method can be used to both Extend or Reduce the effective_until, or set an effective_until if it was null, which was not the case in spec v3.

§ [MOD-PP-MSG-8-2-2] Set Participant Effective Until advanced checks

1. ECOSYSTEM Participant entries

• if applicant_participant.validator_participant_id is null and applicant_participant.role is ECOSYSTEM, corporation running the method MUST be applicant_participant.corporation.

2. Self-created Participant entries

• load validator_participant from applicant_participant.validator_participant_id. validator_participant MUST be a active participant of role ECOSYSTEM. corporation running the method MUST be applicant_participant.corporation.

3. OP-managed Participant entries

• effective_until MUST be lower or equal to applicant_participant.op_exp else MUST abort.
• load validator_participant from applicant_participant.validator_participant_id. validator_participant MUST be a active participant. corporation running the method MUST be validator_participant.corporation.

§ [MOD-PP-MSG-8-2-3] Set Participant Effective Until fee checks

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

§ [MOD-PP-MSG-8-2-4] Set Participant Effective Until overlap checks

We want to make sure that 2 Participant entries cannot be active at the same time for the same validator_participant_id. If corporation wishes to create a new Participant entry but the existing one never expires (or expires too far from now), corporation MUST use first the Set Participant Effective Until to set or adjust the effective_until value.

Find all active participants participants[] (not revoked, not slashed, not repaid) for schema_id, role, validator_participant_id, corporation.

for each Participant entry p from participants[]:

• if p.effective_until is greater than effective_from, method execution MUST abort.
• if p.effective_from is lower than effective_until, method execution MUST abort.
• if p.effective_until is NULL (never expire), creation of a new Participant entry doesn’t make any sense and method execution MUST abort.

note: this check was not present in v3.

§ [MOD-PP-MSG-8-3] Set Participant Effective Until 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 Participant entry applicant_participant from id.

• set applicant_participant.effective_until to effective_until

• set applicant_participant.adjusted to now

• set applicant_participant.modified to now

Synchronise VS Operator Authorization expiration, if any. Call [MOD-DE-MSG-9] Update VS Operator Authorization Expiration with:

• participant_id: applicant_participant.id
• new_expiration: applicant_participant.effective_until

This call is a no-op if no record exists for applicant_participant.id. If a record exists, its expiration is updated and the on-chain FeeGrant for the containing VSOA is refreshed via [MOD-DE-MSG-5-5]. Set Participant Effective Until does not accept VSOA parameters and cannot modify any other field of the record; VSOA configuration is frozen at record creation (see [MOD-PP-MSG-1] and [MOD-PP-MSG-14]). This method also cannot create a record that does not already exist.

§ [MOD-PP-MSG-9] Revoke Participant

Any authorized operator CAN execute this method on behalf of a corporation.

This method can only be called:

• by an ancestor (corporation of a validator in the Participant branch until the root Participant entry (GRANTOR, ECOSYSTEM, OPEN schema mode)).
• by the grantee corporation (OPEN, GRANTOR, ECOSYSTEM schema mode).
• by the Ecosystem corporation (owner of the credential schema).

§ [MOD-PP-MSG-9-1] Revoke Participant parameters

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• id (uint64) (mandatory): id of the Participant entry;

§ [MOD-PP-MSG-9-2] Revoke Participant precondition checks

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

§ [MOD-PP-MSG-9-2-1] Revoke Participant basic checks

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (corporation, operator) pair and this message type.
• id MUST be a valid uint64.
• Load Participant entry applicant_participant from id. If no entry found, abort.
• applicant_participant MUST be a active participant

§ [MOD-PP-MSG-9-2-2] Revoke Participant advanced checks

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

Option #1: executed by a validator ancestor

if applicant_participant.validator_participant_id is defined:

• set validator_participant = applicant_participant
• while validator_participant.validator_participant_id is defined,
  • load validator_participant from validator_participant.validator_participant_id.
  • if validator_participant is a active participant and validator_participant.corporation is who is running the method, => return true.
• end
• return false.

Option #2: executed by Ecosystem controller

• load CredentialSchema cs from applicant_participant.schema_id
• load Ecosystem ecosystem from cs.ecosystem_id
• if corporation running the method is ecosystem.corporation, return true.
• else return false.

Option #3: executed by applicant_participant.corporation: return true.

Example:

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

• by “Verifier E”, if the corresponding Participant entry is a active participant;
• by “Verifier Grantor D”, if the corresponding Participant entry is a active participant;
• by “Ecosystem A”, if the corresponding root Participant entry is a active participant;
• by the Ecosystem object controller, obtained by resolving perm => credential schema => ecosystem.

§ [MOD-PP-MSG-9-2-3] Revoke Participant fee checks

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

§ [MOD-PP-MSG-9-3] Revoke Participant 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 Participant entry applicant_participant from id.

• set applicant_participant.revoked to now

• set applicant_participant.modified to now

Call [MOD-DE-MSG-6] Revoke VS Operator Authorization with participant_id = applicant_participant.id to remove any authorization record for this Participant entry. The call is a no-op if no record exists.

§ [MOD-PP-MSG-10] Create or Update Participant Session

Any authorized operator CAN execute this method on behalf of a corporation.

Any credential exchange that requires issuer or verifier to pay fees, register a digest_sri, or produce a proof implies the creation of a ParticipantSession.

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;
• optional: the agent_participant_id Participant id of the agent that will receive the credential, if peer is a Verifiable User Agent. it MUST NOT be set if peer is a Verifiable Service.
• optional: the wallet_agent_participant_id Participant id of the agent wallet that will store the credential. If this is the same software than the agent, then it should be equal to agent_participant_id. It MUST NOT be set if peer is a Verifiable Service.

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

• a uuid for session identification;
• optional: the agent_participant_id Participant id of the agent that will receive the credential, if peer is a Verifiable User Agent. it MUST NOT be set if peer is a Verifiable Service.
• optional: a map of compatible found credentials in available wallets for the requested schema_id: Map<uint64[] issuer_participant_ids, uint64: wallet_agent_participant_id>. wallet_agent_participant_id MUST NOT be set if peer is a Verifiable Service.

In case peer is a Verifiable Service and illegaly set agent_participant_id and/or wallet_agent_participant_id, the other end MUST refuse the request.

payer MUST create a Participant 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-PP-MSG-10-1] Create or Update Participant Session parameters

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

• corporation (group): (Signer) the signing corporation on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the corporation to run this Msg.
• id (uuid) (mandatory): id of the ParticipantSession.
• issuer_participant_id (uint64) (optional): the id of the perm of the issuer, if we are dealing with the issuance of a credential.
• verifier_participant_id (uint64) (optional): the id of the perm of the verifier, if we are dealing with the verification of a credential.
• agent_participant_id (uint64) (optional): the agent credential issuer Participant id (extracted from the agent credential that VUA has in its wallet) of the agent that received the request (credential offer for issuance, presentation request for verification). Only set by VUAs, MUST NOT be specified when peer is a VS.
• wallet_agent_participant_id (uint64) (optional): the wallet credential issuer Participant id of the VUA where the credential will be or is stored. Can be the same perm than agent_participant_id if agent and wallet_agent are the same agent. Only set by VUAs, MUST NOT be specified when peer is a VS.
• digest (string) (optional): digest derived from an issued or verified credential.

§ [MOD-PP-MSG-10-2] Create or Update Participant Session precondition checks

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

• corporation (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• id MUST be a valid uuid. If an entry existing_entry with id already exist, then existing_entry.corporation MUST be equal to corporation AND existing_entry.vs_operator MUST be equal to operator, else abort.

if issuer_participant_id is null AND verifier_participant_id is null, MUST abort.

• define issuer_participant as null.
• define verifier_participant as null.

if issuer_participant_id is not null:

• Load issuer_participant from issuer_participant_id.
• if issuer_participant.role is not ISSUER, abort.
• if issuer_participant is not a active participant, abort.
• if issuer_participant.vs_operator is not equal to operator, abort.
• if issuer_participant.corporation is not equal to corporation, abort.
• if digest_sri is present but not a valid digest SRI, abort.

if verifier_participant_id is not null:

• Load verifier_participant from verifier_participant_id.
• if verifier_participant.role is not VERIFIER, abort.
• if verifier_participant is not a active participant, abort.
• if verifier_participant.vs_operator is not equal to operator, abort.
• if verifier_participant.corporation is not equal to corporation, abort.
• if digest_sri is present but not a valid digest SRI, abort.

Define the primary Participant perm: if verifier_participant is not null, perm = verifier_participant (the caller is the vs_operator of the verifier). Else, perm = issuer_participant (the caller is the vs_operator of the issuer).

[AUTHZ-CHECK-3] MUST pass for this (corporation, operator, perm) tuple. [AUTHZ-CHECK-4] MUST pass for this (corporation, operator, perm) tuple.

agent:

• Load agent_participant from agent_participant_id.
• if agent_participant.role is not ISSUER, abort.
• if agent_participant is not a active participant, abort.

wallet_agent:

• Load wallet_agent_participant from wallet_agent_participant_id.
• if wallet_agent_participant.role is not ISSUER, abort.
• if wallet_agent_participant is not a active participant, abort.

§ [MOD-PP-MSG-10-3] Create or Update Participant Session fee checks

• Load CredentialSchema entry cs from issuer_participant.schema_id if issuer_participant is not null, else from verifier_participant.schema_id.
• Fee payer MUST have sufficient available balance for the required estimated transaction fees.

For trust fees, corporation account MUST have sufficient available balance as explained below.

Step 1: Calculate total beneficiary fees in credential schema pricing asset

Use “Find Beneficiaries” query method to get the set of beneficiary Participant entries found_participant_set (all ancestors in the Participant tree).

• define total_beneficiary_fees = 0

If Credential Issuance (issuer_participant is NOT null):

• for each perm in found_participant_set:
  • total_beneficiary_fees = total_beneficiary_fees + participant.issuance_fees × (1 - issuer_participant.issuance_fee_discount)

If Credential Verification (verifier_participant is NOT null):

• for each perm in found_participant_set:
  • total_beneficiary_fees = total_beneficiary_fees + participant.verification_fees × (1 - verifier_participant.verification_fee_discount)

Note: total_beneficiary_fees is expressed in the credential schema pricing asset (cs.pricing_asset_type, cs.pricing_asset).

Step 2: Calculate amounts payer must have available

Based on the credential schema pricing configuration, calculate the total amounts the payer (corporation) must have available.

Define the following variables:

Initialize:

• total_fees_in_pricing_asset = total_beneficiary_fees
• total_fees_in_native_denom = 0
• total_payer_trust_deposit = 0
• total_payees_trust_deposit = 0
• total_payees_fees_to_account = 0
• total_user_agent_reward = 0
• total_wallet_agent_reward = 0

If a conversion is needed below, use Get Price to convert amounts.

Case A: (cs.pricing_asset_type, cs.pricing_asset) = (COIN, [[ref: native denom]])

Pricing is in native token. No conversion needed.

Calculate:

• total_fees_in_native_denom = total_fees_in_pricing_asset
• total_payer_trust_deposit = total_fees_in_native_denom × GlobalVariables.trust_deposit_rate
• total_payees_trust_deposit = total_payer_trust_deposit
• total_payees_fees_to_account = total_fees_in_native_denom × (1 - GlobalVariables.trust_deposit_rate)

if agent_participant_id is set:

• total_user_agent_reward = total_fees_in_native_denom × GlobalVariables.user_agent_reward_rate

if wallet_agent_participant_id is set:

• total_wallet_agent_reward = total_fees_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

Required balance check:

• corporation MUST have available balance ≥ total_fees_in_native_denom + total_payer_trust_deposit + total_user_agent_reward + total_wallet_agent_reward in native denom.

Case B: (cs.pricing_asset_type, cs.pricing_asset) = (TU, "tu")

Pricing is in Trust Units. Convert to native denom for all on-chain payments.

Calculate:

• total_fees_in_native_denom = getPrice(TU, "tu", COIN, [[ref: native denom]], total_fees_in_pricing_asset)
• total_payer_trust_deposit = total_fees_in_native_denom × GlobalVariables.trust_deposit_rate
• total_payees_trust_deposit = total_payer_trust_deposit
• total_payees_fees_to_account = total_fees_in_native_denom × (1 - GlobalVariables.trust_deposit_rate)

if agent_participant_id is set:

• total_user_agent_reward = total_fees_in_native_denom × GlobalVariables.user_agent_reward_rate

if wallet_agent_participant_id is set:

• total_wallet_agent_reward = total_fees_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

Required balance check:

• corporation MUST have available balance ≥ total_fees_in_native_denom + total_payer_trust_deposit + total_user_agent_reward + total_wallet_agent_reward in native denom.