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 Pair

Guardians are uniquely identified by a public-private key pair. The private key is used to sign issued zkKYCs. The public one is used for verification — to prove that a specific person or app indeed signed the certificate with their corresponding private key.

Galactica uses EdDSA keys because they are more efficient in zero-knowledge proofs than traditional keys used by EVM wallets.

If a Guardian doesn't have an EdDSA key and doesn't know how to generate one, we included convenience methods in SDK to help in obtaining one. Using these methods Guardian can either create a new random key or derive it from their Ethereum private key.

We consider a completely random key to be more secure. Key derived from Ethereum private key, however, can be deterministically derived again in case of loss of the EdDSA private key. At the same time it makes it less secure: in case of leak of the Ethereum private key, it will lead to leak of the derived EdDSA private key as well.

Choose carefully.

Assuming you already have an Ethereum private key, a Guardinan EdDSA key can be created with these steps:

TypeScript

1. Create an environment variable containing your wallet private key, source it in the console and include the name of the environment variable in packages/zk-certificates/hardhat.config.ts under the accounts of the network you want to use.

2. With this setup, the scripts for Guardians will derive the EdDSA key from a wallet signature when needed. This is achieved in TypeScript by the function

   const providerEdDSAKey = await getEddsaKeyFromEthSigner(provider);

GoLang

1. Create a file containing your Ethereum private key. The key must be hex-encoded without 0x prefix. Example: bffb2fb8cdc39199b3dd16ead2075c73decefc15c011ad00030f17687bc43107.

2. Run the following command:\

   galactica-guardian generateEdDSAKeyPair -k /path/to/ethereum-key.hex

   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. Alternatively, the private key may be derived programmatically using function keymanagement.DeriveEdDSAKeyFromEthereumPrivateKey.

Hardware wallet or multisig wallet

The key can be obtained by signing the following message:

Signing this message generates your EdDSA private key. Only do this on pages you trust to manage your zkCertificates.

Use the R component (which is usually first 32 bytes) of the resulting signature as the EdDSA private key.

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.

Obtaining a License

At the moment, KYC Guardians need to be whitelisted in a KYC registry to be able to issue zkKYCs. This registry is a smart contract maintained by the Galactica Foundation. Please contact us through https://galactica.com/contact to be included.

To become whitelisted, you need to pass

1. The address of admin account for your guardian. It will be able to issue zkCertificates on-chain.

2. The EdDSA key generated above

3. The IPFS link to your metadata

The current whitelist system is intended as simple solution for the early phase of Galactica. In the long term, everyone will be able to issue attestations in the form of zkCerts. The validity of a zkCert will then depend on decentralized metrics, such as the reputation of the provider. Please send us your feedback and suggestions on how to improve the design, technology and processes.

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.

Multiple issuer addresses

It is possible to register multiple addresses that are able to issue zkCerts. This can help you if you want to split the on-chain activity of your guardian business to multiple accounts or servers.

In the whitelisting process, one of your addresses was registered as admin for your guardian. The EdDSA key and metadata are attached to it. This admin address may add and remove issuer addresses using the following smart contract methods of the guardian registry. The admin address is automatically also an issuer. Adding more issuer addresses is optional.

/**
 * Add an issuer account to a guardian's account.
 * @param issuer - This account may issue zkCerts on behalf of the guardian.
 */
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)