Introduction

The Trusted Nodes List (TNL) is a crucial resource for developers within the EBSI ecosystem. It serves as the entry point for various applications providing a secure and updated list of API endpoints (individual domains) for Trusted Nodes within a specified EBSI network such as Pilot, pre-production and Production.

Maintained by the EBSI technical Office, the TNL ensures that all network changes - including domain name updates, new node additions, and existing node removals - are reflected in this dynamic list.

The Trusted Nodes List

The TNL serves as a trusted resource for application developers and load balancer providers. Presented as a Verifiable Credential (VC) wrapped in a Verifiable Presentation (VP) JWT, includes a comprehensive collection of nodes per environment and it is generated and signed by the Support Office before being reviewed and also signed by the EBSI Service Operations Manager.

info

To streamline the process of retrieving and validating the list of trusted nodes, an EBSI TNL tool is now available. Additionally, consumers can utilize the TNL library, which is designed to guide them through all the necessary steps.

Format Data model

The TNL VC contains a detailed list of nodes for each environment, signed by the SO and issued to the Service Ops Manager. This involves using a verification method from the SO's DID document, registered in the DID Registry, and accredited in the Trusted Issuer Registry.

Property	Value
Credential format	JWT-VC
Signature format	JWS Compact Serialization
Signing algorithm	ES256
Signer	Support Office

Upon receiving the VC, the Service Ops Manager reviews the list, converts it into a Verifiable Presentation, and signs it.

Property	Value
Credential format	JWT-VP
Signature format	JWS Compact Serialization
Signing algorithm	ES256
Signer	Service Ops Manager

Data model

The trusted nodes list data model extends the Verifiable Attestation credentialSubject with the following properties:

Claims		Required	Type	Description
id		Yes	string/DID	DID of Service Ops Manager who will receive the Trusted Nodes List for review.
environment		Yes	string/enum	Defines the environment for which the Trusted Nodes List is valid. One of: test pilot conformance preprod prod
chainId		Yes	integer	Defines the chain ID, which is part of the transaction signing process to protect against transaction replay attacks.
version		Yes	integer	Defines the version of the Trusted Nodes List. First version MUST be 1.
nodesTotal		Yes	integer	Defines the total number of nodes in the list.
nodes		Yes	array/object
	apis	Yes	string/URL	MUST be a valid domain name starting with https://api-{environment}.ebsi. Note: on production, "-{environment}" is skipped. The URL will therefore start with https://api.ebsi.
	explorer	No (not all the nodes have a block explorer)	string/URL	If present, MUST be a valid domain name starting with https://blockexplorer-{environment}.ebsi. Note: on production, "-{environment}" is skipped. The URL will therefore start with https://blockexplorer.ebsi.
	country	Yes	string	MUST be a three-letter country code as per ISO 3166-1 alpha-3

Trusted Nodes List Payload Example

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "id": "urn:uuid:8568b525-a24e-4bc0-9d97-6a8459ec0130",
  "type": ["VerifiableCredential", "VerifiableAttestation", "TrustedNodesList"],
  "issuer": "did:ebsi:00001234",
  "issuanceDate": "2021-11-01T00:00:00Z",
  "validFrom": "2021-11-01T00:00:00Z",
  "issued": "2021-11-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:ebsi:00005678",
    "environment": "pilot",
    "chainId": 6179,
    "version": 1,
    "nodesTotal": 2,
    "nodes": [
      {
        "apis": "https://api-pilot.ebsi.stsisp.ro",
        "explorer": "https://blockexplorer-pilot.ebsi.stsisp.ro",
        "country": "rou"
      },
      {
        "apis": "https://api-pilot.ebsi.fnmt.es",
        "country": "esp"
      }
    ]
  },
  "termsOfUse": [
    {
      "id": "ebsi:pilot:trusted-issuers-registry:/issuers/did:ebsi:00001234/attributes/b40fd9b404418a44d2d9911377a03130dde450eb546c755b5b80acd782902e6d",
      "type": "IssuanceCertificate"
    }
  ],
  "credentialSchema": {
    "id": "ebsi:pilot:trusted-schemas-registry:/schemas/zDjVp7fDTKbhqFUuCSQ7tvxGMPjns8KeyqfMSFUREuyq8",
    "type": "FullJsonSchemaValidator2021"
  }
}

Trusted Node List Location

To access the latest TNL versions, please refer to the two public repositories maintained and updated by the EBSI team. You can find the TNL at the following locations:

• Bitbucket Repository
• GitLab Repository

Recommendations for securely getting the list of trusted nodes

As has been defined in the reference implementation, the following steps describe the recommended process to get and validate the Trusted Nodes List:

1. Fetch the tnl.jwt file from the two different locations. Refer to the two public repositories on Bitbucket and GitLab, which are maintained and updated by the EBSI team:
   1. If both files are the same, continue to step 2.
   2. Otherwise, decode the JWT headers of both JWTs and compare the kid property.
      1. If they match, you can continue to step 2 with the tnl.jwt file which has the highest version number.
      2. If the kid properties don't match, it means that the 2 files have been signed with 2 different public keys. In this case, please contact the Support Office to remediate this situation.
2. Decode the VP JWT header the tnl.jwt file
3. Extract the kid from the VP JWT header, fetch the corresponding public key from the pubkeys/ folder.
   1. If the pubkeys/ folder doesn't contain the corresponding public key, the tnl.jwt file can't be trusted. Please contact the Support Office to remediate this situation.
4. Validate the VP JWT signature
   1. If the signature is invalid, the tnl.jwt file can't be trusted. Please contact the Support Office to remediate this situation.
5. Extract the VC from the VP
6. Extract the kid from the VC JWT header, fetch the corresponding public key from the pubkeys/ folder.
   1. If the pubkeys/ folder doesn't contain the corresponding public key, the tnl.jwt file can't be trusted. Please contact the Support Office to remediate this situation.
7. Validate the VC JWT signature
   1. If the signature is invalid, the tnl.jwt file can't be trusted. Please contact the Support Office to remediate this situation.
8. Additionally, and only after going through all the previous steps, the VP JWT can be validated by using the VP library and trusting one of the nodes listed in tnl.jwt. This node must be healthy (check "Node health check services" section above).

tip

We do not recommend caching the trusted nodes list for a long time — e.g. no more than 5 minutes. It should be regularly checked for updates. However, the logic of fetching, validating and caching the trusted nodes list could be abstracted by the implementer (wallet provider or other), moving the complexity away from the end user.

Every application should define a policy for when the new nodes list should be applied. For example: a new nodes list is used after all sources return the same list.

The APIs consumer can use this list of trusted nodes to build an application's internal logic that can connect the application to the APIs endpoints in different ways:

1. Stay connected to one predefined endpoint until it is off. Connect to the next one based on internal priorities.
2. Connect randomly to any of them (it can be used as a software Round Robin or any other model)
3. Connect only to a predefined list of on nodes (for example, all the nodes that are in the same country as the application service provider's headquarter, or in the same country where the user is accessing the app)
4. Use an internal load balancer that equally distributes the load to all the available endpoints in the list (potentially based on some criteria).
5. Some other scenarios can be created based on the need of each use case.

Need assistance or have any queries? Please don't hesitate to contact our Support Office