Pilot Participant Guide

This guide is for GRID Pilot Participants. It explains the setup for participants based on the Pilot Design (see Pilot Design Document).

It is a good idea to read the introduction to Pilots here and the design document first to understand the context for these instructions.

This guide is expected to be updated as more pilot participants join the program and improvements are identified.

1. Overview

You are setting up a Sovereign Node. This is a standard GitLab (or GitHub) repository that you completely control.

Through a process called "Data Normalization at the Edge," your repository will automatically convert your human-readable registry data into machine-readable JSON and publish it to a public web endpoint.

The GRID will "harvest" this public data. If your data is valid and you have provided a Decentralized Identifier (DID), the GRID will mathematically sign and issue a W3C Verifiable Credential (UNTP Digital Identity Anchor) for your Registry and display the verified results in the Global Registry Information Directory.

Note that these instructions are written to enable digital participation in the GRID Pilot. It is possible (and acceptable) for authoritative registrars to participate that meet the eligibility requirements but that don't yet have a digital environment. These would be represented as one or more rows in the GRID table with human readable content describing the authoritative registrar, their registry (or registries), the legal basis for their authority and other relevant details. These details would need to be shared with the GRID Pilot directly through a channel considered secure enough by both the Pilot participant and the GRID Pilot operator.

This architecture guarantees that the UN cannot modify your data, but acts strictly as a Trust Framework to verify and anchor the data you choose to publish.

2. Requirements

1. GitLab/GitHub Repo: A repository on your own infrastructure to store your registry data.
2. Decentralized Identifier (DID): You must host a did:web identity document. Note: The GRID enforces a strict "No DID = No Anchor" rule. Without this, you will be listed in the directory, but no UN Verifiable Credential will be issued.

3. Setup Instructions

Step 1: Repository Structure

Your repository represents your UN Member State. You may host multiple registrars inside it. Create the following folder structure:

/ (Root)
├── .gitlab-ci.yml            <-- The automated publishing pipeline
├── did.json                  <-- Your Identity Document (Hosted by you)
└── registrars/               <-- Folder for your data
    ├── companies.yml         <-- Registrar #1
    └── land-registry.yml     <-- Registrar #2

Step 2: Creating Registrar Entries

For each registrar, create a YAML (.yml) file in the registrars/ folder. Important: follow the JSON structure defined in schemas/registrar-v1.json.

This is an example template - you can use this structure and replace the values with your own:

# Registry Metadata
UN_member_state: "AT"
subdivision_code: null
registrar_full_name: "Sea Companies Registrar of Atlantis"
registrar_identifier_code: "ACR"
register_name: "National Company Registry"
register_type: "business"
legal_basis: "https://atlantis.legislation.gov/organisation-act"
authoritative_body: "https://ministry.atlantis.gov"
participant_profile: "D"
register_id: "AT.ACR"
registered_id_pattern: "AT.ACR.^\\d{8}$"  # Note: In YAML strings, escape backslashes!
id_example: "AT.ACR.12345678"

# Pointing to your self-hosted DID
did: "did:web:atlantis.gov.gtr-pilots.gitlab.io:atlantis:companies"
status: "active"
contacts: "11dot2+atlantis@gmail.com"

Step 3: Configuring the CI/CD Pipeline

To ensure the UNTP Harvester can read your data, you must convert your YAML files into strict JSON and host them on the web. We provide a pipeline template that does this automatically.

Create a file named exactly .gitlab-ci.yml in the root of your repository and paste this code:

image: alpine:latest

pages:
  stage: deploy
  before_script:
    # Install YAML processor and GNU awk
    - apk add --no-cache yq gawk
  script:
    - echo "Building public data directory for GRID harvesting..."
    - mkdir -p public/registrars
    
    # 1. Host the DID document at the root of the site (if it exists)
    - if [ -f did.json ]; then cp did.json public/; fi
    
    # 2. Process both YAML and Markdown files dynamically
    - |
      for file in registrars/*.yml registrars/*.md; do
        if [ -f "$file" ]; then
          filename=$(basename "$file")
          base="${filename%.*}"
          ext="${filename##*.}"
          
          if [ "$ext" = "yml" ]; then
            yq -o=json '.' "$file" > "public/registrars/${base}.json"
          elif [ "$ext" = "md" ]; then
            gawk '/^---$/ { if (!p) {p=1; next} else {exit} } p {print}' "$file" | yq -o=json '.' > "public/registrars/${base}.json"
			cp "$file" "public/registrars/${base}.md"
          fi
        fi
      done
      
  artifacts:
    paths:
      - public
  only:
    - main

CRITICAL GitLab Setting: Go to Settings > Pages in GitLab and uncheck "Use unique domain". This ensures your URL remains predictable.

Step 4: Hosting your DID (Identity)

For the pilot, we are currently using the did:web standard. Your DID document contains the public key necessary for cryptographic verification.

1. Place your W3C-compliant did.json file in your repository root.

2. When you commit your code, the pipeline from Step 3 will automatically publish it to your web root.

3. Your DID will look something like: did:web:gtr-pilots.gitlab.io:genovia, mapping directly to your Pages URL.

Step 5: Connection

To go live, simply send the following to the UN/CEFACT Pilot Lead via a secure channel:

1. Your GitLab Pages Base URL (e.g., https://gtr-pilots.gitlab.io/uk-pilot/)

2. Your Primary DID Once received, we will add your endpoint to the Harvester. After the next build process of the GRID site, your registrars will appear in the Global Directory with a Verified Trust Badge and a direct link to your newly minted Digital Identity Anchor.

Pilot Limitations

To maximize agility and focus on demonstrating decentralized data harvesting, this pilot implements a simplified cryptographic architecture. While the output data is formatted as valid W3C Verifiable Credentials, it intentionally diverges from strict UNTP production requirements in the following ways.

Embedded vs. Enveloped Proofs

Pilot Implementation: The GRID script signs data using W3C DataIntegrityProof blocks embedded directly within the JSON payload.

Production Roadmap: The UNTP specification requires credentials to be wrapped as IETF JOSE Enveloping Proofs (JWT/SD-JWT). This will be implemented in a future operational phase.

Revocation Infrastructure

Pilot Implementation: The pilot currently issues DIAs without a credentialStatus block.

Production Roadmap: The production GRID will deploy a cryptographic Revocation Registry (such as a W3C Bitstring Status List) to allow UN/CEFACT to revoke accredited registrars in real-time.