# Galactica Snap JSON-RPC API

This page documents the JSON-RPC API of the Galactica Snap. It follows the structure for snap methods provided by Metamask ([see here](https://docs.metamask.io/snaps/reference/rpc-api/#wallet_invokesnap)).

To simplify the integration in front-end projects, we provide the NPM package [@galactica-net/snap-api](https://www.npmjs.com/package/@galactica-net/snap-api). It includes TypeScript methods, parameters and return types for the interaction.

## Connection Methods

### `wallet_requestSnaps`

Requests permission for a DApp to communicate with Metamask and the Galactica Snap.

Visit the [Metamask Documentation](https://docs.metamask.io/guide/snaps-rpc-api.html#wallet-requestsnaps) for more details.

#### Example

```javascript
const result = await ethereum.request({
  method: 'wallet_requestSnaps',
  params: {
    'npm:@galactica-net/snap': {},
  },
});

console.log(result);
// Will print something of the form:
// {
//   "npm:@galactica-net/snap": {
//     "blocked": false,
//     "enabled": true,
//     "id": "npm:@galactica-net/snap",
//     "initialPermissions": {
//       "endowment:rpc": {
//         "dapps": true,
//         "snaps": false
//       },
//       "endowment:ethereum-provider": {},
//       "endowment:long-running": {},
//       "snap_notify": {},
//       "snap_dialog": {},
//       "snap_manageState": {}
//     },
//     "permissionName": "wallet_snap_npm:@galactica-net/snap",
//     "version": "0.2.1"
//   }
// }
```

### `wallet_getSnaps`

#### Description

This method returns the IDs of the caller's permitted snaps and some relevant metadata.

See the [Metamask documentation](https://docs.metamask.io/guide/snaps-rpc-api.html#wallet-getsnaps) for more details.

## Galactica Specific Methods

All following methods are invoked through the `wallet_invokeSnap` method of the [Metamask RPC-API](https://docs.metamask.io/guide/snaps-rpc-api.html#wallet-invokesnap).

These methods are restricted, meaning that you first need to aquire permission using the connection method.

### `getHolderCommitment`

#### Description

Asks the Snap to return the holder commitment needed for issuing new zkCertificates. It is used to provide the guardian of a zkCert with the field that links the zkCert to the holder. This link is hidden in a commitment so that the guardian can not associate it with any on-chain address. This method also returns the public key for encrypting the zkCert. The private decryption key is secured inside the snap.

#### Parameters

None

#### Returns

* `object`
  * `holderCommitment` - The holder commitment as decimal `string`.
  * `encryptionPubKey` - Public encryption key `string` to encrypt the zkCert with.

Throws error if the user rejects the confirmation.

#### Example

```javascript
import { getHolderCommitment } from '@galactica-net/snap-api';
const holderCommitmentData = getHolderCommitment();
```

### `genZkCertProof`

#### Description

Sends a request for generating a ZK proof in the Snap. It is generic because you can request different kind of ZK proof depending on the parameters. It selects one ZkCert imported by the user and forwards its contents to the private proof inputs together with additional inputs provided in `inputs`.

Shows the user what is going to be proven and asks for confirmation.

#### Parameters

* `object`
  * `input` - An `object`, containing public ZKP input for the statements to be shown by the generated proof.
  * `requirements` - `object`
    * `zkCertStandard`: `string` for the standard of the zkCertificate that should be used for the proof.
    * `registryAddress`: `string` EVM address where the zkCertificate is registered.
  * `prover` - `object` containing
    * `wasm` - `string` base64 encoded wasm binary of the prover. The wasm can be generated using circom and encoded with the script in `src/scripts/proofGenerationPrep.ts`.
    * `zkeyHeader` - `object` of zkey headers used by snarkjs. The binary fields are base64 encoded.
    * `zkeySections` - `array` of base64 encoded zkey sections used by snarkjs.
  * `userAddress` - `string` with the account address the user is going to use to submit the proof.
  * `description` - `string` Description of what the proof if for. The user will see this as description when being asked for confirmation by the Snap.
  * `publicInputDescriptions` - `string[]` List of short descriptions what each field disclosed in the resulting proof input is needed for.

#### Returns

Generated proof on accepted confirmation and successful computation. Throws error otherwise.

* `object`
  * `proof` - `object`
    * `pi_a` - `object` holding proof verification data.
    * `pi_b` - `object` holding proof verification data.
    * `pi_c` - `object` holding proof verification data.
    * `protocol` - `string` Protocol used for ZKP, usually "groth16".
    * `curve` - `string` Curve used for ZKP, usually "bn128".
  * `publicSignals`: `array` List of public inputs for the proof as decimal strings.

#### Example

```javascript
import { getHolderCommitment } from '@galactica-net/snap-api';
// Requesting proof for zkKYC and age >= 18

// expected time for between pressing the generation button and the verification happening on-chain
const estimatedProofCreationDuration = 20;

const currentTimestamp =
  (await getCurrentBlockTime()) + stimatedProofCreationDuration;
const dateNow = new Date(currentTimestamp * 1000);

const proofInput = {
  currentTime: currentTimestamp,
  dAppAddress: '0xf1947AeD2d0a5Ff90D54b63C85904d258D3B5E63',
  investigationInstitutionPubKey: [], // fill with pubkeys if fraud investigation is needed
  currentYear: dateNow.getUTCFullYear().toString(),
  currentMonth: (dateNow.getUTCMonth() + 1).toString(),
  currentDay: dateNow.getUTCDate().toString(),
  ageThreshold: '18',
};

return await generateZKProof({
  input: proofInput,
  prover: await getProver('/provers/exampleMockDApp.json'),
  requirements: {
    zkCertStandard: ZkCertStandard.ZkKYC,
  },
  userAddress: getUserAddress(),
  disclosureDescription:
    'This proof discloses that you hold a valid zkKYC and that your age is at least 18. The proof includes 3 encrypted fragments for test institutions. 2 are needed to decrypt your zkKYC DID for fraud investigation.',
});

// Should return something like:
// {
//   "proof": {
//     "pi_a": [
//       "17407499557855479094412111859538240424111472258125783015858813919815373704619",
//       "18128677868601693983827893970719326131214195171042021234179379044169730862651",
//       "1"
//     ],
//     "pi_b": [
//       [
//         "17792771401466707362701636891264864127929589644831579368515954432422229774445",
//         "13322517950661839404366860539623846150703987405896094568766754897006695020304"
//       ],
//       [
//         "159187298954882081522062472144132288168610805554524398765911845338289258212",
//         "15657949055482864856641089614049190837954674706375448381006265359982794480149"
//       ],
//       [
//         "1",
//         "0"
//       ]
//     ],
//     "pi_c": [
//       "3040903384873419199294037770869928465455153606144433400954341650060775903677",
//       "146329608595190310527006670514062849554280797627326909476418461538368213705",
//       "1"
//     ],
//     "protocol": "groth16",
//     "curve": "bn128"
//   },
//   "publicSignals": [
//     "1",
//     "11209916212079559410136633032138482335659351203987398533814440017698336323514",
//     "1678883749",
//     "478873986970679317615613077202381596613806366113",
//     "2023",
//     "3",
//     "15",
//     "18"
//   ]
// }
```

### `clearStorage`

#### Description

Request for removing data stored in the Snap (holders and zkCertificates).

Asks the user for confirmation.

#### Parameters

None

#### Returns

* `object`
  * `string` - "zkCert storage cleared" on success. Returns [an error](https://github.com/Galactica-corp/galactica-snap/blob/main/packages/snap-api/src/api/error.ts) otherwise.

#### Example

```javascript
import { getHolderCommitment } from '@galactica-net/snap-api';
await clearStorage();
```

### `importZkCert`

#### Description

Imports a zkCertificate from a file into the Snap. The file is created, signed and encrypted by the provider and given to the user for being imported in the wallet.

Asks user for confirmation

#### Parameters

* `object`
  * `encryptedZkCert` - `[EncryptedZkCert](https://github.com/Galactica-corp/galactica-monorepo/blob/20e3435e2b9e7deeb05dd5358687f7380ff8d25b/packages/galactica-types/src/zkCert.ts#L77) object`, containing the zkCertificate encrypted using [eth-sig-util](https://github.com/MetaMask/eth-sig-util) and containing the holderCommitment to associate it.
  * `listZkCerts` - `boolean`, (optional) flag if the Snap should return an overview after the import, same as in the `listZkCerts` method.

#### Returns

* `object`
  * `string` "zkCert added to storage" on successful import. If `listZkCerts` is set to `true`, it returns the zkCert overview instead (same as in the `listZkCerts` method). Returns [an error](https://github.com/Galactica-corp/galactica-snap/blob/main/packages/snap-api/src/api/error.ts) if the import fails.

#### Example

```javascript
import { importZkCert } from '@galactica-net/snap-api';
await importZkCert({ encryptedZkCert: JSON.parse(fileContent) });
```

### `exportZkCert`

#### Description

Exports a zkCertificate stored in the snap in encrypted form.

Asks the user for confirmation and selection of the zkCertificate to be exported

#### Parameters

* `object`
  * `zkCertStandard` - `string` identifying the standard of the zkCertificate to be deleted (optional).
  * `expirationDate` - `number` identifying the expiration date of the zkCertificate to be deleted (optional).
  * `providerAx` - `string` identifying the provider pubkey (Ax part only) of the zkCertificate to be deleted (optional).

#### Returns

* JSON `object` of the encrypted zkCertificate according to the standard.

#### Example

```javascript
import { exportZkCert } from '@galactica-net/snap-api';
return await exportZkCert({ zkCertStandard: ZkCertStandard.ZkKYC });
```

### `deleteZkCert`

#### Description

Delete a zkCertificate stored in the snap.

You can provide some filter criteria which zkCert should be deleted based on the response from the `listZkCerts` method. It asks the user for confirmation and selection of the zkCertificate to be deleted if the filter is ambiguous.

#### Parameters

* `object`
  * `zkCertStandard` - `string` identifying the standard of the zkCertificate to be deleted (optional).
  * `expirationDate` - `number` identifying the expiration date of the zkCertificate to be deleted (optional).
  * `providerAx` - `string` identifying the provider pubkey (Ax part only) of the zkCertificate to be deleted (optional).

#### Returns

* `object`
  * `string` - "Deleted zkCert." on success. Throws error otherwise.

#### Example

```javascript
import { deleteZkCert } from '@galactica-net/snap-api';
return await deleteZkCert({ zkCertStandard: ZkCertStandard.ZkKYC });
```

### `listZkCerts`

#### Description

Requests overview of zkCertificates held in the Snap for management

To not limit the privacy risks of the user, this overview only contains zkCertificate metadata that is usually not shown in a ZKP. This should prevent cross referencing multiple disclosures submitted from different addresses.

Asks the user for confirmation. As a website you only need to query this once and then you can cache and reuse this data until the hash from the `getZkCertStorageHash` changes.

#### Parameters

None

#### Returns

* `object`
  * `[zkCertStandard: string]`: JSON `object` holding zkCertificate metadata.
    * `provider` - JSON `object` including publickey of provider.
    * `expirationDate` - `number` Unix timestamp of expiration date.

Throws an error if the user rejected the confirmation.

#### Example

```javascript
import { listZkCerts } from '@galactica-net/snap-api';
return await listZkCerts();
```

### `getZkCertStorageHashes`

#### Description

You can use `getZkCertStorageHash` to detect changes in the zkCert storage of the snap. This can be done without requiring user interaction (besides the initial connect) and therefore does not dirsturb the user flow.

#### Parameters

None

#### Returns

* `object`
  * `[zkCertStandard: string]`: `string` for the storage hash of all zkCerts of this type held by the Snap.

#### Example

```javascript
import { getZkStorageHashes } from '@galactica-net/snap-api';
return await getZkStorageHashes();
```

### `getZkCertHashes`

#### Description

You can use `getZkCertHash` to query the leaf hashes of the zkCerts imported in the snap. This is needed for updating the Merkle proof. It is useful because it improves privacy by not using the same publicly trackable Merkle root.

However this function exposes the unique hash of zkCerts and should therefore only be on sites the user trusts to handle this ID confidentially.

#### Parameters

None

#### Returns

* `object`
  * `[string]` list of zkCert hashes of all zkCerts held by the Snap.

#### Example

```javascript
import { getZkCertHashes } from '@galactica-net/snap-api';
return await getZkCertHashes();
```

### `updateMerkleProof`

#### Description

This method updates the Merkle proof of a list of zkCerts. This is helpful to prevent tracking through the publicly disclosed merkle root.

You can create the Merkle proof with the scripts in the zkKYC repository.

#### Parameters

* `object`
  * `proofs: [MerkleProof]` list of MerkleProofs to update.

Each Merkle proof has the following [form defined in the zkKYC repository](https://github.com/Galactica-corp/zkKYC/blob/f3b92a5e18c2ef8e09143156ec8b54b677cc828c/lib/merkleTree.ts#L161).

#### Returns

* `object`
  * `string` - Success message.

Throws error on failure.

#### Example

```javascript
import { updateMerkleProof } from '@galactica-net/snap-api';
await updateMerkleProof({
  proofs: [
    {
      leaf: '19630604862894493237865119507631642105595355222686969752403793856928034143008',
      root: '17763126929763058632596384403463503447502390993612973244727217445899815879260',
      pathIndices: 0,
      pathElements: [
        '913338630289763938167212770624253461411251029088142596559861590717003723041',
        '8950197483297962010688249615565850791722784770941154749153756652440041255541',
        '9917272083296999008482951374949279205405409343140430270441153151503507424016',
        '17619695615639375563172755451063681091123583187367666354590446695851847455206',
        '13318301576191812234266801152872599855532005448246358193934877587650370582600',
        '14788131755920683191475597296843560484793002846324723605628318076973413387512',
        '15889843854411046052299062847446330225099449301489575711833732034292400193334',
        '4591007468089219776529077618683677913362369124318235794006853887662826724179',
        '974323504448759598753817959892943900419910101515018723175898332400800338902',
        '10904304838309847003348248867595510063038089908778911273415397184640076197695',
        '6882370933298714404012187108159138675240847601805332407879606734117764964844',
        '5139203521709906739945343849817745409005203282448907255220261470507345543242',
        '13660695785273441286119313134036776607743178109514008645018277634263858765331',
        '10348593108579908024969691262542999418313940238885641489955258549772405516797',
        '8081407491543416388951354446505389320018136283676956639992756527902136320118',
        '9958479516685283258442625520693909575742244739421083147206991947039775937697',
        '7970914938810054068245748769054430181949287449180056729094980613243958329268',
        '9181633618293215208937072826349181607144232385752050143517655282584371194792',
        '4290316886726748791387171617200449726541205208559598579274245616939964852707',
        '6485208140905921389448627555662227594654261284121222408680793672083214472411',
        '9758704411889015808755428886859795217744955029900206776077230470192243862856',
        '2597152473563104183458372080692537737210460471555518794564105235328153976766',
        '3463902188850558154963157993736984386286482462591640080583231993828223756729',
        '4803991292849258082632334882589144741536815660863591403881043248209683263881',
        '8436762241999885378816022437653918688617421907409515804233361706830437806851',
        '1050020814711080606631372470935794540279414038427561141553730851484495104713',
        '12563171857359400454610578260497195051079576349004486989747715063846486865999',
        '15261846589675849940851399933657833195422666255877532937593219476893366898506',
        '3948769100977277285624942212173034288901374055746067204399375431934078652233',
        '5165855438174057791629208268983865460579098662614463291265268210129645045606',
        '19766134122896885292208434174127396131016457922757580293859872286777805319620',
        '21875366546070094216708763840902654314815506651483888537622737430893403929600',
      ],
    },
  ],
});
```

### `updateMerkleProofURL`

#### Description

This method updates the URL used to fetch Merkle proofs from. Regenerating the Merkle proof is needed if a zkCert registry with revocable entries changes it's root. With this method, the user can control the URL. It is only a fallback if the official URL is down during the testnet. Before mainnet, we want to upgrade to an decentralized solution that figures out the URL from which node to query the Merkle proof from automatically.

#### Parameters

* `object`
  * `url: string` URL to upgrade to.

#### Returns

* `object`
  * `string` - Success message.

Throws error on failure.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.galactica.com/galactica-developer-documentation/building-a-galactica-dapp/front-end/galactica-snap-json-rpc-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.