Access Node Instantiation and Compliance Guide

This document describes the Access Node integration process, including the steps to follow, the necessary documentation and the verification criteria, as well as clarifying any possible configuration doubts for preparing the environment.

The goal is to provide a clear and concise guide for users participating in this process. To achieve this, the document will be divided into sections or checkpoints. These will detail everything necessary to proceed, including other processes with their respective guides. Failure to meet these checkpoints will prevent us from continuing with the Access Node integration procedure. 

Note that for this guide, all the environments mentioned that we will work with will be either a local environment or SBX, but it could be applied to higher environments. 

1. Registration validation: DOME

The first step in the setup process is to confirm that our company is registered in DOME and therefore we have a LEAR Credential Employee with Onboarding permissions available so that we can issue our credentials. 

If you are not registered or there is any problem with the credential’s permissions, consult this guide: Onboarding Guide 

2. Issuance Validation: LEAR Credential Machine

The second step is to validate that we currently have a LEAR Credential Machine at our disposal. To do this, we must confirm that we have access to the Wallet and see if our credential has been downloaded. 

If you do not have access or do not have the required credentials, please review the credential issuance guide . 

Once we have our issued credentials, we will need to consult the next 3 points:  

       Image when we issued a new LEAR Credential Machine

         After downloaded your credential, you can view your info

3. Data Validation: DLT

Once we have the issued credential, we need to generate our machine's addresses using this tool: Dome Access Node  Keys Generator.

To do that, we need our machine's DID key, obtained previously. 

 The generated addresses will be as follows: 

 

4. AN Configuration: Secrets

Check this guide if you will work with secrets: Github sealed secrets guide.

5. AN Configuration: Chart.yaml

This is how your chart.yaml should look. All necessary dependencies are included in the AN configuration. 

Check the last version here: 

apiVersion: v2
name: access-node
description: Chart holder for ArgoCD
type: application
version: 0.7.31
appVersion: 0.1.0
dependencies:
- name: access-node
  condition: access-node.enabled
  repository: https://dome-marketplace.github.io/access-node
  version: <check the last version>

6. AN Configuration: Values.yaml

First, we need to consider whether we've decided to work with secrets (remember rename the file to values.yaml), or not, as the file format may vary slightly. 

Values with secrets.yaml

Values without secrets.yaml

First of all, we will check that the file header starts as shown in the image: 

 


Now let’s configure all the blocks.

Modify the ingress hots:

For example this is our domain:  desmos.dome-marketplace-lcl.org

The next thing to check is that we have specified your DID key in the following field: 

 

Next, we will need to review the configured domains: 

We will need to configure your protocol (in this case it was http but usually it would be https) and the domain of our machine, the URL with which it will be identified.

The next step is to configure the private key, which, if we are working with secrets, will look like this: 

 

Or without secrets:

The next step will be to configure our databases.

Here we need to configure our database host; this example uses an embedded database. We'll also need to specify our database details and whether or not we're using secrets. 

As you can see, without secrets, we will need to specify our database password and disable secrets. 

The next block is the DLT block; here we will need to configure the data obtained with the dome key generator: 

 

In case of working without secrets: 

For the configuration of our Postgres, we must take into account the configuration of the secrets. 

 

And for the case of no secrets: 

For the Scorpio configuration:  

And for the configuration without secrets, we would only have to configure the password as shown in the image:

 

The same procedure applies to secrets;. 

 

And without secrets: 

This would be all the configuration to take into account to prepare our AN to be able to perform the synchronization tests. 

Logically, there are more blocks in the file that we haven't mentioned, but we suggest not editing them without having the necessary knowledge.

7. Registering the node in the Trusted Lists

In order for your AN node to communicate and connect with ours, it must be registered on the following two lists. 

Trusted Access node list 

Trusted Access Node list file 

The format to follow is as follows: 

  - name: <your company name>
    dlt_address: <dlt_address generated above> 

Trusted Services list 

Trusted services list file 

The format to follow is as follows: 

  • clientId : <"did:key of your machine">
    redirectUris : []
    scopes : [] 
    clientAuthenticationMethods: ["client_secret_jwt"]
    authorizationGrantTypes: ["client_credentials"]
    postLogoutRedirectUris : []
    requireAuthorizationConsent: false
    requireProofKey: false
    jwkSetUrl: " https://verifier.dome-marketplace-sbx.org/oidc/did/did:key:<did key of our machine>"
    tokenEndpointAuthenticationSigningAlgorithm: "ES256" 

8. AN Synchronization Tests

These are the steps that will be taken before the tests:

8.1. Backup before testing

Perform a dump backup of the Scorpio data so we can restore it afterwards and delete the data of your DB. Remember to put it out of your docker or it will disappear if you restart your AN.

8.2. Configuration for testing

Add the externalAccessNodesUrls configuration inside the APP block as shown on the image below, which should be adapted for these tests. (It will be reconfigured later to point to the correct location.)

externalAccessNodesUrls: 
  enableCustomUrls: true 
  customUrls: “https://desmos.dome-marketplace-lcl.org”

How it should looks

8.3. Review the values configuration and Trusted Lists registry

Verify that you complete all the steps above and your machine is correctly registered in the Trusted lists

Trusted Lists github

8.4. Install AN

After doing the previous steps, be sure that you installed your AN correctly. I'm leaving these commands here in case they're helpful. Remember that you need to throw these commands inside your values.yaml directory.

helm dependency build
helm install myaccessnode . -f values.yaml
8.5. Desmos running without errors

Confirm that your desmos pod is working correctly. You could check it with 

kubectl logs desmos-648bdbc988-pl2ft -n <your-namespace> -c desmos

Tests to Perform

We will perform two tests: 

  1. Synchronization with the blockchain 

  1. P2P verification

We will create a temporary entity, one on your node and another on ours, and see if it synchronizes via the blockchain. 

We can do it using Postman or using the curl command by postforwarding to Scorpio: 

kubectl port-forward svc/scorpio 9090:9090 -n marketplace 

Or if we have access to the bae marketplace, from there; For example, this is our configured site: Bae marketplace local 

curl --location 'http://localhost:9090/ngsi-ld/v1/entities/?type=catalog' \
--header 'Content-Type: application/json' \
--data '{
"id": "urn:catalog:MyDummyTest",
"type": "catalog",
"version": "2.5",
"lastUpdate": "2024-07-09T12:00:00Z",
"lifecycleStatus": "Launched"
}' 

And we will validate that it has been created correctly using curl

curl --location 'http://localhost:9090/ngsi-ld/v1/entities/urn:catalog:MyDummyTest'