Skip to main content

Pilot Participant Guide

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

It is a good idea to read the introductions to Pilots (http://localhost:3000/unece/uncefact/gtr/docs/Pilots/) and 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 repository that you control. We will "harvest" the test-data you make available about the test Registries you choose to publish, we will check it against the signature you tell us you will use, and we will display the verified results in the Global Registrar Information Directory.

This means that we cannot modify your data but we can check the data we find has been signed by your key.

2. Requirements​

  1. GPG Key: You must generate a GPG Keypair (RSA 4096) to act as your Digital Identity.

  2. GitLab Repo: A private repository on GitLab.com.

  3. Deploy Token: A read-only token so our Harvester can see your repo.

3. Setup Instructions​

Step 1: Identity & Config​

  1. Generate your GPG Key and upload the Public Key to your GitLab User Settings.

  2. Configure your local Git to sign commits automatically:

    Bash

    git config --global user.signingkey <YOUR_KEY_ID>
    git config --global commit.gpgsign true

    You may also do this manually if preferred and develop your own approval/merge and CI/CD pipeline. The harvester will ckecl that your GPG key has signed the commit.

Step 2: Repository Structure​

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

Plaintext

/ (Root)
├── did.json                  <-- Your Identity Document
└── registrars/               <-- Folder for your data
    ├── companies-house.md    <-- Registrar #1
    └── land-registry.md      <-- Registrar #2

Step 3: Creating Registrar Entries​

For each registrar, create a markdown file in the registrars/ folder. Important: follow the JSON structure defined in schemas/registrar-v1.json, here

Template (registrars/companies.md):

YAML

---
#machine readable code
UN_member_state: GV
subdivision_code: null
registrar_full_name: "TP: Royal Ministry of Genovia Companies"
registrar_identifier_code: TP-MGC
register_name: "TP: Genovia Company House"
register_type: "Organisation"
legal_basis: https://legislation.genovia.gov/companies-act
authoritative_body: https://ministry.genovia.gov
register_id: "https://companies.genovia.gov"
registered_id_description: "9-digit numeric code in 3 blocks of 3-digits with a 2-digit prefix"
registered_id_pattern: "GV.TP-MGC.^\\d{2}\\s\\d{3}\\s\\d{3}\\s\\d{3}"  # Note: In YAML strings, escape backslashes!
id_example: "GV.TP-MGC.51 824 753 556"

# Pointing to your Docusaurus static path
did: "did:web:gitlab.com:gtr-pilots:genovia"
status: "active"
contacts: "11dot2+genovia@gmail.com"

# Using a test pilot GPG key here, because we are signing for the Registrar
signing_key_id: "2EBA5339DBEE1079D295A3DE7782530389BB46E3"
---

## Royal Ministry of Genovia

### Verification Policy

This registry is a test pilot bootstrap node managed by the GTR Project Team for Companies registered in the fictitious UN Member State of Genovia. None of the content here is official.

This fictitious registry is hosted on gitlab.com, here: https://gitlab.com/gtr-pilots/genovia

Format of the Genovia Identifier

:::note[]

this text is a copy of the Australian Business Number text with "Australian" replaced with "Genovian". The original text is here:

[ABN Format](https://abr.business.gov.au/Help/AbnFormat)

The use of this text is for illustrative purposes only to create realistic content - it does not imply participation.
:::

The Genovian Business Number (GBN) is a unique 11 digit identifier issued to all entities registered in the Genovian Business Register (GBR).

The 11 digit GBN is structured as a 9 digit identifier with two leading check digits. The leading check digits are derived using a modulus 89 (remainder after dividing by 89) calculation.

To verify an GBN:

1. Subtract 1 from the first (left-most) digit of the GBN to give a new 11 digit number
2. Multiply each of the digits in this new number by a "weighting factor" based on its position as shown in the table below
3. Sum the resulting 11 products
4. Divide the sum total by 89, noting the remainder
5. If the remainder is zero the number is a valid ABN

For example, to check if 51 824 753 556 is a valid ABN:

1. Subtract 1 from the first (left-most) digit (5) to give 41 824 753 556
2. Multiply each of the digits in 41 824 753 556 by the "weighting factor" based on its position as shown in the table below
3. Sum (Digit * weight) to give a total of 534
4. Divide 534 by 89 giving 6 with zero remainder.
5. As the remainder is zero, 51 824 753 556 is a valid ABN.

Validate ABN example

| Digit | Position | Weighting | Digit * weight |
| -----:| --------:| ---------:| --------------:|
| 4     | 1        | 10        | 40             |
| 1     | 2        | 1         | 1              |
| 8     | 3        | 3         | 24             |
| 2     | 4        | 5         | 10             |
| 4     | 5        | 7         | 28             |
| 7     | 6        | 9         | 63             |
| 5     | 7        | 11        | 55             |
| 3     | 8        | 13        | 39             |
| 5     | 9        | 15        | 75             |
| 5     | 10       | 17        | 85             |
| 6     | 11       | 19        | 114            |
| ----  | ----     | ----      | ----           |
|       |          | **Total** | 534            |


Note that the signing_key_id value must be the "fingerprint" value of the public key. You can use this command to find the string:

gpg --list-secret-keys --keyid-format LONG

The output will look something like this, where the fingerprint is the long string of numbers and letters on the second line:

sec   rsa4096/3AA5C34371567BD2 2024-03-01 [SC]
      F296BDE50FC2E9348271031C3AA5C34371567BD2   <-- COPY THIS
uid                 [ultimate] UK Pilot Admin <admin@pilot.gov>

Update your registrar.md file with that full string:

registrar_name: "UK Companies House"
signing_key_id: "F296BDE50FC2E9348271031C3AA5C34371567BD2"

Step 4: Hosting your DID (Identity)​

For the pilot we are currently using the did:web standard. This means that you must publish your pilot did.json file to the web.

  1. Place did.json in your repository root.

  2. Add a .gitlab-ci.yml file to publish it:

    YAML

    pages:
     stage: deploy
     script:
       - mkdir public
       - cp did.json public/
     artifacts:
       paths:
         - public
     only:
       - main

  3. CRITICAL: Go to Settings > Pages and uncheck "Use unique domain".

  4. Your DID will be something like: did:web:gtr-pilots.gitlab.io:genovia, where gtr-pilots.gitlab.io:genovia is replaced by your pages URL and project name.

Step 5: Connection​

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

  1. Repository URL (e.g., https://gitlab.com/gtr-pilots/uk-pilot.git)

  2. Deploy Token Username & Password (Scope: read_repository)

  3. Your Public GPG Key (The .asc file)

Once received, we will add you to the Harvester. After the next build process of the GTR site, your registrars will appear in the Global Directory with a Verified Trust Badge.