Setup to become a Guardian

SDK

We provide an SDK, which has a collection of commands to help you interact with the blockchain and process zero knowledge certificates. Currently we implemented two SDKs in the following programming languages:

• TypeScript SDK

• GoLang SDK

All SDKs provide the same functionality, so choose one based on how you familiar with the programming language and it's ecosystem. The rest of this guide will show instructions for each of the SDKs in a corresponding tab.

Installation Instructions

TypeScript

1. Make sure you have git and yarn installed. Their installation is out of scope of this guide.

2. Run the following commands in your command line shell:

   git clone [e-mail]:Galactica-corp/galactica-monorepo.git
   cd galactica-monorepo
   yarn install

GoLang

1. Make sure you have go installed and it's environment is configured properly. It's installation is out of scope of this guide.

2. Run the following command in your command line shell:

   go install github.com/galactica-corp/guardians-sdk/cmd/galactica-guardian@latest

Key Pairs

Every Guardian on Galactica needs an EVM (ECDSA) keypair, consisting of:

1. Private ECDSA key

2. Public ECDSA key (address that corresponds to this key is later used on-chain to identify the Guardian)

This keypair is used to interact with the blockchain itself and it will be further mentioned as the main or admin ECDSA. Later we will need at least one more.

And a second keypair, which will be used to sign ZK Certificates, consisting of

1. Private EdDSA key

2. Public EdDSA key

Public keys are specifically mentioned here because they should be transferred to the Galactica Foundation for Whitelisting. The private keys you should keep as secure as possible, and never share them with anyone.

Only if both private keys were compromised, it would allow an attacker to fully act on behalf of the Guardian and make changes to the Merkle trees storing the data. Because of that, we recommend to backup them separately, and make sure that the access to the servers, where the issuer node(s) operate(s) is secured.

Even if both keys are compromised, the attacker cannot read the data that was used to generate ZK Certificates. It is only possible to issue more ZK Certificates, or modify/revoke existing ones. Generally, in that situation, the Guardian gets denounced, which also revokes all previously issued ZK Certificates.

Overall Process

1. Generate EdDSA private key.

2. Generate ECDSA private key (it will be the main one).

   1. Instead of generating a new ECDSA key, you can use any existing one, if you are sure it was generated and stored securely.

   2. We recommend using multisig or a cold wallet for generating and storing the main key. It will only be used to authorize your other ECDSAs (we get to them in p4).

3. Send main ECDSA and EdDSA public keys, together with your Metadata, described in this section, to Galactica Foundation for whitelisting. At later stages, the Whitelisting process will be transferred to a DAO.

4. Generate one more ECDSA key - the one we will be using on the server. If you plan to have several issuing nodes (backends), you can already generate more keys to cover them all.

5. [Once you are whitelisted] Whitelist your server ECDSA key(s) using your admin ECDSA key. This adds your server keys as children to the main one. You will be able to revoke them using your admin key in case of an incident at any time.

6. If you generated the main ECDSA key outside the cold wallet and you didn't use a multisig, at this step you should move your main ECDSA key to the cold storage or a vault and make sure it is not mentioned on servers and/or any other places.

7. Deploy your issuing node(s) to the server with its personal ECDSA key and the common EdDSA key.

The schema shows the recommended setup you're gonna end up with following our guide.

Private key (ECDSA)

Generation and rotation

A new ECDSA keypair can be generated in the following ways:

• With cold wallet or multisig (applicable and recommended for the main key only)

• Through Metamask or any other non-custodial wallet

• Utilizing Ethereum SDK

• Using the following shell script, file key will contain the generated private key:

  # Generate the private and public keys
  openssl ecparam -name secp256k1 -genkey -noout | openssl ec -text -noout > key
  
  # Extract the private key and remove the leading zero byte
  cat key | grep priv -A 3 | tail -n +2 | tr -d '\n[:space:]:' | sed 's/^00//' > priv

The main keypair is not meant to be rotated, as it is assumed that it never leaves the cold wallet. Child ECDSA keys can be rotated, provided that the newly created keys are preemptively whitelisted by your main ECDSA key.

Key permissions

• Full control over the associated Ethereum account, which means:

  • Access to the funds (Guardian needs to keep the balance to pay for TX fees)

  • Ability to sign transactions from the Guardian's address

• [Only main ECDSA] Ability to add and remove additional child addresses to the Guardians whitelist.

While it's possible to, having this key, send transactions on behalf of the Guardian, it won't be possible to change any data in the merkle trees (e.g. issue, update or revoke any ZK Certificates) in any meaningful way, since these actions also require EdDSA signature inside the transaction body.

Managing children keys

Having access to your main ECDSA key, it's possible to whitelist more ECDSA keys to use on your servers. The main key technically can be also used on servers to issue ZK Certificates, but we strongly recommend against doing so.

To add or revoke a new ECDSA key, you need to call method addIssuerAccount or removeIssuerAccount of the ZkCertificate Guardian Whitelist contract correspondingly.

/**
 * Add an issuer account to a guardian's account.
 * @param issuer - This account may issue zkCerts on behalf of the guardian.
 */
function addIssuerAccount(address issuer)

/**
 * Remove an issuer account from a guardian's account.
 * @param issuer - This account may no longer issue zkCerts on behalf of the guardian.
 */
function removeIssuerAccount(address issuer)

It is possible to call those methods manually: via block explorer (from your cold wallet, as recommended) or using multisig. You will have to do perform these steps:

1. Find the relevant Guardian Whitelist smart contract address. Currently, Galactica has 2 networks:

   1. Reticulum Testnet addresses are listed here,

   2. Andomeda Devnet addresses - here.

2. Paste the address obtained on the previous step to the search bar of the block explorer of the corresponding network.

   1. Reticulum block explorer

   2. Andromeda block explorer

3. Send a transaction!

   1. If you use multisig, you need the ABI. It is available on the smart contract page in the block explorer in tab Contract, then in tab Code in section Contract ABI.
   2. If you want to send transaction from the block explorer, find the method you want to call in tab Contract, then in tab Write contract. You will be able to connect any wallet with Wallet Connect, including the cold wallets.

If the key is lost or compromised

1. In case it's not the main ECDSA key, you can simply revoke it using the admin ECDSA key.

2. In case it's the main ECDSA key, the Guardian should be renounced. You can do it yourself using renounceGuardianRole method of the ABI or contact Galactica Foundation for it.

Signing key (EdDSA)

Generation and rotation

Use the guardians-sdk to generate the key:

GoLang

1. Run the following command:

   galactica-guardian generateEdDSAKeyPair

   The command will save the generated EdDSA private key to file named eddsa-private-key.hex (you can customise output location with -o flag). It will also print the generated public key to the console for reference.

Rotation of this key will become possible with the further updates, once the system will allow Guardian to have multiple EdDSA keys.

Key permissions

• Signing ZK Certificates

While it's possible to, having this key, sign ZK Certificates, it won't be possible to submit them on-chain without having the whitelisted ECDSA key, allowing to send the transaction on behalf of Guardians' account.

If the key is lost or compromised

1. In case the key is or may be compromised, the Guardian should be renounced. You can do it yourself using renounceGuardianRole method of the ABI or contact Galactica Foundation for it. This action will lead to unavailability of all previously signed ZK Certificates, so users will have to approach Guardian again to get new ones.

2. In case the key is lost, but not under any risk of being compromised, Guardian has to generate new keypairs and contact Galactica Foundation for whitelisting. The old keypairs will stay until all signed ZK Certificates are expired.

Metadata

Guardians in the registry have some metadata that defines how you are shown to users. The metadata is a .json file that is referenced on-chain by an URL.

Your metadata file should include the same fields as the following example:

{
  "name": "Galactica Example Guardian",
  "certificate_name": "Galactica Test zkKYC",
  "icon": "https://raw.githubusercontent.com/Galactica-corp/galactica-monorepo/main/packages/snap/images/logo_galactica.svg",
  "cert_background": "https://galactica.com/assets/images/home/bg-bottom-sm.webp",
  "description": "Example Metadata of the Galactica guardian for Zero-Knowledge KYC",
  "certificate_type": "gip1",
  "url": "https://galactica.com/"
}

This metadata file can be uploaded to IPFS to generate a link such as ipfs://QmbxKQbSU2kMRx3Q96JWFvezKVCKv8ik4twKg7SFktkrgx. If you are new to IPFS, we can recommend https://www.pinata.cloud/ as easy to use tool to upload and pin files to IPFS.

To update the metadata link after the whitelisting, you just need to repeat the obtaining a license step.

User Interface

Users need some kind of interface to get KYCed by a Guardian. We offer to forward users from the Galactica Passport portal to your website.

When users are forwarded, we also pass a Holder Commitment in a URL parameter. This commitment is a hash that needs to be collected by the Guardian. It is required for creating a zkKYC because it ties the resulting zkKYC to an EVM wallet. This preserves user privacy in zero-knowledge proofs because the Guardian can not link personal details to on-chain addresses.

If zkKYCs should be created without the Galactica Passport portal, e.g. for testing, the method getHolderCommitment of the Galactica Snap JSON-RPC API can be used. It generates the commitment inside the Galactica Snap for Metamask. Furthermore it exports a public encryption key of the user so that zkKYC details can be transmitted in an encrypted file.

Data Storage for Compliance

The compliance model of Galactica is build on proactively proven Contingent Transactions and retroactive fraud investigations inspired by the zkKYC paper.

In case of fraud investigations, authorities can decrypt the link between on-chain zero-knowledge proofs and the zkKYC decentralized identity (DID). Legal authorities can then approach the Guardian to reveal details associated with a zkKYC DID. Therefore, Guardians are required to store, safeguard and keep KYC details of users for retroactive fraud investigations.

Personal details revealed in this way are handed directly to legal authorities, so that they stay off-chain.