Add Merkle Tree

.eslintrc.js

@@ -18,5 +18,10 @@ module.exports = {
  root: true,
  rules: {
  '@typescript-eslint/require-await': 'off',
+ '@typescript-eslint/no-unsafe-assignment': 'off',
+ '@typescript-eslint/no-unsafe-return': 'off',
+ '@typescript-eslint/no-unsafe-member-access': 'off',
+ '@typescript-eslint/no-unsafe-call': 'off',
+ '@typescript-eslint/no-unsafe-argument': 'off',
  },
 };

.gitignore

@@ -71,3 +71,11 @@ dist
 
 # Stores VSCode versions used for testing VSCode extensions
 .vscode-test
+
+# Example Accounts and MerkleTree are not committed
+data/example/accounts.json
+data/example/key-pairs.json
+data/example/merkle-root.json
+data/example/merkle-tree-result.json
+data/example/merkle-tree-result-detailed.json
+data/example/signatures.json

.prettierignore

@@ -24,6 +24,7 @@ REVISION
 *.tsbuildinfo
 *.blob
 *.lock
+*.keep
 
 ## jest snapshot
 *.snap

README.md

@@ -1 +1,13 @@
 # lisk-token-claim
+
+This library is the monorepo for:
+
+### Tree Builder
+
+Builds Merkle Tree from a snapshot and computes Merkle Root.
+
+## Setup and Installation
+
+```
+$ yarn && yarn build
+```

packages/tree-builder/README.md

@@ -0,0 +1,112 @@
+# Tree Builder
+
+This library builds Merkle Tree from a snapshot and computes Merkle Root.
+
+## Run
+
+```
+$ cd packages/tree-builder
+$ ./bin/run.js generate-merkle-tree --network=mainnet # Mainnet
+$ ./bin/run.js generate-merkle-tree --network=testnet # Testnet
+$ ./bin/run.js generate-merkle-tree --network=example # Example, see below
+```
+
+## Files
+
+| Name | Description | Generated By |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `/data/<network>/accounts.json` | Stores addresses, balances, and multisig details(If any) per account after a snapshot is taken, addresses must be sorted in ascending order. Will be used for MerkleTree computation. | Snapshot |
+| `/data/<network>/merkle-tree-result-detailed.json` | Stores MerkleRoot, and leaves for each account. Will be used for examination by 3rd Party or public, also used by Claim Backend API. | `$ ./bin/run.js generate-merkle-tree --network=<network>` |
+| `/data/<network>/merkle-tree-result.json` | Stores MerkleRoot, and leaves for each account. A lightweight version of `merkle-tree-result-detailed.json`. Will be used for testing of Claim Contract. | `$ ./bin/run.js generate-merkle-tree --network=<network>` |
+| `/data/<network>/merkle-root.json` | Stores MerkleRoot only. Will be used for deployment of Claim Contract. | `$ ./bin/run.js generate-merkle-tree --network=<network>` |
+
+## Merkle Leaf
+
+Each leaf will be encoded as ABI-format, in the following order:
+
+```
+LSK_ADDRESS_IN_HEX: bytes20
+BALANCE_IN_BEDDOWS: uint64
+NUMBER_OF_SIGNATURES: uint32
+MANDATORY_KEYS: bytes32[]
+OPTIONAL_KEYS: bytes32[]
+
+P.S. If the address is not a multisig address, NUMBER_OF_SIGNATURES would be 0, MANDATORY_KEYS and OPTIONAL_KEYS be []
+```
+
+### Params
+
+```
+accounts.json:
+{
+ lskAddress: string;
+ balance: number;
+ balanceBeddows: number;
+ numberOfSignatures?: number;
+ mandatoryKeys?: string[];
+ optionalKeys?: string[];
+}
+
+merkle-tree-result-detailed.json:
+{
+ merkleRoot: string;
+ leaves: {
+ lskAddress: string;
+ address: string;
+ balance: number;
+ balanceBeddows: number;
+ numberOfSignatures: number;
+ mandatoryKeys: string[];
+ optionalKeys: string[];
+ hash: string;
+ proof: string[];
+ }[];
+}
+
+merkle-tree-result.json:
+{
+ merkleRoot: string;
+ leaves: {
+ b32Address: string;
+ balanceBeddows: number;
+ mandatoryKeys: string[];
+ numberOfSignatures: number;
+ optionalKeys: string[];
+ proof: string[];
+ }[];
+}
+# `address` is a reserved in solidity, hence `b32Address` here
+
+merkle-root.json:
+{
+ merkleRoot: string;
+}
+
+# Only used at example
+signatures.json:
+{
+ message: string;
+ sigs: {
+ pubKey: string
+ r: string
+ s: string
+ }[];
+}[];
+```
+
+## _Demo/Testing Purpose Only_
+
+```
+$ ./bin/run.js example [--amountOfLeaves <value>] [--recipient <value>]
+
+# FLAGS
+# --amountOfLeaves=<value> [default: 100] Amount of leaves in the tree
+# --recipient=<value> [default: 0x34A1D3fff3958843C43aD80F30b94c510645C316] Destination address at signing stage. Default is the contract address created by default mnemonic in Anvil/Ganache when nonce=0
+```
+
+By running the command above, it will, at `data/example` folder:
+
+1. Create `key-pairs.json`, which stores public-private key pairs, along with the corresponding address and path
+2. Create `accounts.json` using addresses in `key-pairs.json`, with random LSK balance.
+3. Create `merkle-root.json`, `merkle-tree-result.json`, `merkle-tree-result-detailed.json` using the accounts above (Equivalent to `./bin/run.js generate-merkle-tree --network=example`).
+4. Sign every leaf using the private keys in `key-pairs.json` and output to `signatures.json`.

packages/tree-builder/package.json

@@ -39,16 +39,16 @@
  "plugins": [
  "@oclif/plugin-help"
  ],
- "topicSeparator": " ",
- "topics": {
- "hello": {
- "description": "Say hello to the world and others"
- }
- }
+ "topicSeparator": " "
  },
  "dependencies": {
+ "@liskhq/lisk-cryptography": "4.1.0",
  "@oclif/core": "^3",
- "@oclif/plugin-help": "^6"
+ "@oclif/plugin-help": "^6",
+ "@openzeppelin/merkle-tree": "^1.0.5",
+ "ethereumjs-util": "^7.1.5",
+ "ethers": "^6.8.1",
+ "tweetnacl": "^1.0.3"
  },
  "devDependencies": {
  "@oclif/prettier-config": "^0.2.1",
@@ -60,6 +60,7 @@
  "mocha": "^10",
  "oclif": "^3.17.2",
  "shx": "^0.3.3",
+ "sinon": "^17.0.1",
  "ts-node": "^10.9.2",
  "typescript": "^5"
  }

packages/tree-builder/src/applications/example/create_accounts.ts

@@ -0,0 +1,100 @@
+import * as fs from 'fs';
+import { address } from '@liskhq/lisk-cryptography';
+import { ExampleKey } from '../../interface';
+
+// 1 LSK = 10^8 Beddows
+const LSK_MULTIPLIER = 10 ** 8;
+
+// Balances are random between 0 - <RANDOM_RANGE>
+const RANDOM_RANGE = 10000;
+
+// Multisig Accounts
+// For each account it will use the address of the index as account holder,
+// while the "keys" are used from #0 onwards
+
+// First (numberOfAccounts - multiSigs.length) accounts would be regular accounts
+// For e.g. numberOfAccounts = 54
+// #50: numSig 3 => 3m
+// #51: numSig 2 => 1m + 2o
+// #52: numSig 5 => 3m + 3o
+// #53: numSig 64 => 64m
+const multiSigs = [
+ {
+ numberOfSignatures: 3,
+ numberOfMandatoryKeys: 3,
+ numberOfOptionalKeys: 0,
+ },
+ {
+ numberOfSignatures: 2,
+ numberOfMandatoryKeys: 1,
+ numberOfOptionalKeys: 2,
+ },
+ {
+ numberOfSignatures: 5,
+ numberOfMandatoryKeys: 3,
+ numberOfOptionalKeys: 3,
+ },
+ {
+ numberOfSignatures: 64,
+ numberOfMandatoryKeys: 64,
+ numberOfOptionalKeys: 0,
+ },
+];
+
+const randomBalance = (range: number): number => Number((range * Math.random()).toFixed(8));
+
+export function createAccounts(numberOfAccounts = 54) {
+ const keyPairs = JSON.parse(
+ fs.readFileSync('../../data/example/key-pairs.json', 'utf-8'),
+ ) as ExampleKey[];
+
+ // to ensure a deterministic tree construction, the accounts array must be sorted in lexicographical order of their addr entries.
+ const sortedKeyPairs = [...keyPairs].sort((key1, key2) =>
+ address
+ .getAddressFromLisk32Address(key1.address)
+ .compare(address.getAddressFromLisk32Address(key2.address)),
+ );
+
+ const results: {
+ lskAddress: string;
+ balance: number;
+ balanceBeddows: number;
+ numberOfSignatures?: number;
+ mandatoryKeys?: string[];
+ optionalKeys?: string[];
+ }[] = [];
+
+ // Regular Accounts
+ for (let index = 0; index < numberOfAccounts - multiSigs.length; index++) {
+ const account = sortedKeyPairs[index];
+ const balance = randomBalance(RANDOM_RANGE);
+ const balanceBeddows = Math.round(balance * LSK_MULTIPLIER);
+
+ results.push({
+ lskAddress: account.address,
+ balance,
+ balanceBeddows,
+ });
+ }
+
+ for (const multiSig of multiSigs) {
+ const account = sortedKeyPairs[results.length];
+ const balance = randomBalance(RANDOM_RANGE);
+ const balanceBeddows = Math.round(balance * LSK_MULTIPLIER);
+
+ results.push({
+ lskAddress: account.address,
+ balance,
+ balanceBeddows,
+ numberOfSignatures: multiSig.numberOfSignatures,
+ mandatoryKeys: [...Array(multiSig.numberOfMandatoryKeys).keys()].map(
+ (_, index) => keyPairs[index].publicKey,
+ ),
+ optionalKeys: [...Array(multiSig.numberOfOptionalKeys).keys()].map(
+ (_, index) => keyPairs[index + multiSig.numberOfMandatoryKeys].publicKey,
+ ),
+ });
+ }
+
+ fs.writeFileSync('../../data/example/accounts.json', JSON.stringify(results), 'utf-8');
+}

packages/tree-builder/src/applications/example/create_key_pairs.ts

@@ -0,0 +1,20 @@
+import * as fs from 'fs';
+import { address, ed } from '@liskhq/lisk-cryptography';
+import { ExampleKey } from '../../interface';
+
+const initialPath = "m/44'/134'";
+
+export async function createKeyPairs(amount = 100) {
+ const keys: ExampleKey[] = [];
+ for (let i = 0; i < amount; i++) {
+ const keyPath = `${initialPath}/${i}'`;
+ const privateKey = await ed.getPrivateKeyFromPhraseAndPath('lisk', keyPath);
+ keys.push({
+ address: address.getLisk32AddressFromAddress(address.getAddressFromPrivateKey(privateKey)),
+ keyPath,
+ publicKey: ed.getPublicKeyFromPrivateKey(privateKey).toString('hex'),
+ privateKey: privateKey.toString('hex'),
+ });
+ }
+ fs.writeFileSync('../../data/example/key-pairs.json', JSON.stringify(keys), 'utf-8');
+}

packages/tree-builder/src/applications/example/sign_accounts.ts

@@ -0,0 +1,78 @@
+import * as fs from 'fs';
+import { AbiCoder, keccak256 } from 'ethers';
+import * as tweetnacl from 'tweetnacl';
+import { MerkleTree, ExampleKey } from '../../interface';
+import { append0x } from '../../utils';
+
+interface SigPair {
+ pubKey: string;
+ r: string;
+ s: string;
+}
+
+interface Signature {
+ message: string;
+ sigs: SigPair[];
+}
+
+const abiCoder = new AbiCoder();
+const signMessage = (message: string, key: ExampleKey): string => {
+ return Buffer.from(
+ tweetnacl.sign.detached(
+ Buffer.from(message.substring(2), 'hex'),
+ Buffer.from(key.privateKey, 'hex'),
+ ),
+ ).toString('hex');
+};
+
+const BYTES_9 = '000000000000000000';
+
+export function signAccounts(recipient: string) {
+ const keys = JSON.parse(
+ fs.readFileSync('../../data/example/key-pairs.json', 'utf-8'),
+ ) as ExampleKey[];
+
+ const merkleTree = JSON.parse(
+ fs.readFileSync('../../data/example/merkle-tree-result-detailed.json', 'utf-8'),
+ ) as MerkleTree;
+ const signatures: Signature[] = [];
+
+ for (const leaf of merkleTree.leaves) {
+ const message =
+ keccak256(abiCoder.encode(['bytes32', 'address'], [leaf.hash, recipient])) + BYTES_9;
+
+ const sigs: SigPair[] = [];
+
+ // Regular Account
+ if (leaf.numberOfSignatures === 0) {
+ const key = keys.find(key => key.address === leaf.lskAddress)!;
+ const signature = signMessage(message, key);
+
+ sigs.push({
+ pubKey: append0x(key.publicKey),
+ r: append0x(signature.substring(0, 64)),
+ s: append0x(signature.substring(64)),
+ });
+ } else {
+ // Multisig Account
+ // Signing with all keys regardless of the required number of signatures
+ for (const pubKey of leaf.mandatoryKeys.concat(leaf.optionalKeys)) {
+ const key = keys.find(key => append0x(key.publicKey) === pubKey)!;
+ const signature = signMessage(message, key);
+
+ sigs.push({
+ pubKey: append0x(key.publicKey),
+ r: append0x(signature.substring(0, 64)),
+ s: append0x(signature.substring(64)),
+ });
+ }
+ }
+
+ signatures.push({
+ message,
+ sigs,
+ });
+ }
+
+ fs.writeFileSync('../../data/example/signatures.json', JSON.stringify(signatures), 'utf-8');
+}