feat: implement light client verification methods

.changeset/forty-pets-film.md

@@ -0,0 +1,7 @@
+---
+"@near-js/light-client": patch
+"near-api-js": patch
+"@near-js/types": patch
+---
+
+Implement light client block and execution validation

packages/accounts/package.json

@@ -32,6 +32,7 @@
   },
   "devDependencies": {
     "@near-js/keystores": "workspace:*",
+    "@near-js/light-client": "workspace:*",
     "@types/node": "18.11.18",
     "bs58": "4.0.0",
     "jest": "26.0.1",

packages/accounts/test/providers.test.js

@@ -1,3 +1,4 @@
+const { validateExecutionProof } = require('@near-js/light-client');
 const BN = require('bn.js');
 const base58 = require('bs58');
 
@@ -154,6 +155,7 @@ describe('providers', () => {
 
         const block = await provider.block({ blockId: finalizedStatus.sync_info.latest_block_hash });
         const lightClientHead = block.header.last_final_block;
+        const finalBlock = await provider.block({ blockId: lightClientHead });
         let lightClientRequest = {
             type: 'transaction',
             light_client_head: lightClientHead,
@@ -169,6 +171,9 @@ describe('providers', () => {
         expect('block_hash' in lightClientProof.outcome_proof).toBe(true);
         expect(lightClientProof.outcome_root_proof).toEqual([]);
         expect(lightClientProof.block_proof.length).toBeGreaterThan(0);
+
+        // Validate the proof against the finalized block
+        validateExecutionProof({ proof: lightClientProof, blockMerkleRoot: base58.decode(finalBlock.header.block_merkle_root) });
 
         // pass nonexistent hash for light client head will fail
         lightClientRequest = {

packages/light-client/README.md

@@ -0,0 +1,8 @@
+# @near-js/light-client
+
+NEAR light client verification utilities. Based on the [Light Client spec](https://github.com/near/NEPs/blob/master/specs/ChainSpec/LightClient.md)
+
+# License
+
+This repository is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
+See [LICENSE](https://github.com/near/near-api-js/blob/master/LICENSE) and [LICENSE-APACHE](https://github.com/near/near-api-js/blob/master/LICENSE-APACHE) for details.

packages/light-client/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    collectCoverage: true
+};

packages/light-client/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "@near-js/light-client",
+    "version": "0.0.1",
+    "description": "TypeScript API for NEAR light client verification",
+    "main": "lib/index.js",
+    "scripts": {
+        "build": "pnpm compile",
+        "compile": "tsc -p tsconfig.json",
+        "lint:js": "eslint -c ../../.eslintrc.js.yml test/**/*.js --no-eslintrc",
+        "lint:js:fix": "eslint -c ../../.eslintrc.js.yml test/**/*.js --no-eslintrc --fix",
+        "lint:ts": "eslint -c ../../.eslintrc.ts.yml src/**/*.ts --no-eslintrc",
+        "lint:ts:fix": "eslint -c ../../.eslintrc.ts.yml src/**/*.ts --no-eslintrc --fix",
+        "test": "jest test"
+    },
+    "keywords": [],
+    "author": "",
+    "license": "ISC",
+    "dependencies": {
+        "@near-js/crypto": "workspace:*",
+        "@near-js/types": "workspace:*",
+        "bn.js": "5.2.1",
+        "bs58": "4.0.0",
+        "borsh": "0.7.0",
+        "js-sha256": "0.9.0"
+    },
+    "devDependencies": {
+        "@near-js/providers": "workspace:*",
+        "@types/node": "18.11.18",
+        "jest": "26.0.1",
+        "ts-jest": "26.5.6",
+        "typescript": "4.9.4"
+    },
+    "files": [
+        "lib"
+    ]
+}

packages/light-client/src/block.ts

@@ -0,0 +1,162 @@
+import { computeBlockHash, combineHash } from './utils';
+import {
+    SCHEMA,
+    BorshApprovalInner,
+    BorshValidatorStakeView,
+    BorshValidatorStakeViewV1,
+    BorshValidatorStakeViewWrapper,
+} from './borsh';
+import bs58 from 'bs58';
+import { sha256 } from 'js-sha256';
+import {
+    LightClientBlockLiteView,
+    NextLightClientBlockResponse,
+    ValidatorStakeView,
+} from '@near-js/types';
+import { PublicKey } from '@near-js/crypto';
+import BN from 'bn.js';
+import { serialize } from 'borsh';
+
+export interface ValidateLightClientBlockParams {
+    lastKnownBlock: LightClientBlockLiteView;
+    currentBlockProducers: ValidatorStakeView[];
+    newBlock: NextLightClientBlockResponse;
+}
+
+/**
+ * Validates a light client block response from the RPC against the last known block and block
+ * producer set.
+ *
+ * @param lastKnownBlock The last light client block retrieved. This must be the block at the epoch before newBlock.
+ * @param currentBlockProducers The block producer set for the epoch of the last known block.
+ * @param newBlock The new block to validate.
+ */
+export function validateLightClientBlock({
+    lastKnownBlock,
+    currentBlockProducers,
+    newBlock,
+}: ValidateLightClientBlockParams) {
+    // Numbers for each step references the spec:
+    // https://github.com/near/NEPs/blob/c7d72138117ed0ab86629a27d1f84e9cce80848f/specs/ChainSpec/LightClient.md
+    // (1) Verify that the block height is greater than the last known block.
+    if (newBlock.inner_lite.height <= lastKnownBlock.inner_lite.height) {
+        throw new Error(
+            'New block must be at least the height of the last known block'
+        );
+    }
+
+    // (2) Verify that the new block is in the same epoch or in the next epoch known to the last
+    // known block.
+    if (
+        newBlock.inner_lite.epoch_id !== lastKnownBlock.inner_lite.epoch_id &&
+        newBlock.inner_lite.epoch_id !== lastKnownBlock.inner_lite.next_epoch_id
+    ) {
+        throw new Error(
+            'New block must either be in the same epoch or the next epoch from the last known block'
+        );
+    }
+
+    const blockProducers: ValidatorStakeView[] = currentBlockProducers;
+    if (newBlock.approvals_after_next.length < blockProducers.length) {
+        throw new Error(
+            'Number of approvals for next epoch must be at least the number of current block producers'
+        );
+    }
+
+    // (4) and (5)
+    // (4) `approvals_after_next` contains valid signatures on the block producer approval messages.
+    // (5) The signatures present represent more than 2/3 of the total stake.
+    const totalStake = new BN(0);
+    const approvedStake = new BN(0);
+
+    const currentBlockHash = computeBlockHash(newBlock);
+    const nextBlockHash = combineHash(
+        bs58.decode(newBlock.next_block_inner_hash),
+        currentBlockHash
+    );
+
+    for (let i = 0; i < blockProducers.length; i++) {
+        const approval = newBlock.approvals_after_next[i];
+        const stake = blockProducers[i].stake;
+
+        totalStake.iadd(new BN(stake));
+
+        if (approval === null) {
+            continue;
+        }
+
+        approvedStake.iadd(new BN(stake));
+
+        const publicKey = PublicKey.fromString(blockProducers[i].public_key);
+        const signature = bs58.decode(approval.split(':')[1]);
+
+        const approvalEndorsement = serialize(
+            SCHEMA,
+            new BorshApprovalInner({ endorsement: nextBlockHash })
+        );
+
+        const approvalHeight: BN = new BN(newBlock.inner_lite.height + 2);
+        const approvalHeightLe = approvalHeight.toArrayLike(Buffer, 'le', 8);
+        const approvalMessage = new Uint8Array([
+            ...approvalEndorsement,
+            ...approvalHeightLe,
+        ]);
+
+        if (!publicKey.verify(approvalMessage, signature)) {
+            throw new Error(
+                `Invalid approval message signature for validator ${blockProducers[i].account_id}`
+            );
+        }
+    }
+
+    // (5) Calculates the 2/3 threshold and checks that the approved stake accumulated above
+    // exceeds it.
+    const threshold = totalStake.mul(new BN(2)).div(new BN(3));
+    if (approvedStake.lte(threshold)) {
+        throw new Error('Approved stake does not exceed the 2/3 threshold');
+    }
+
+    // (6) Verify that if the new block is in the next epoch, the hash of the next block producers
+    // equals the `next_bp_hash` provided in that block.
+    if (
+        newBlock.inner_lite.epoch_id === lastKnownBlock.inner_lite.next_epoch_id
+    ) {
+        // (3) If the block is in a new epoch, then `next_bps` must be present.
+        if (!newBlock.next_bps) {
+            throw new Error(
+                'New block must include next block producers if a new epoch starts'
+            );
+        }
+
+        const bpsHash = hashBlockProducers(newBlock.next_bps);
+
+        if (!bpsHash.equals(bs58.decode(newBlock.inner_lite.next_bp_hash))) {
+            throw new Error('Next block producers hash doesn\'t match');
+        }
+    }
+}
+
+function hashBlockProducers(bps: ValidatorStakeView[]): Buffer {
+    const borshBps: BorshValidatorStakeView[] = bps.map((bp) => {
+        if (bp.validator_stake_struct_version) {
+            if (bp.validator_stake_struct_version !== 'V1') {
+                throw new Error(
+                    'Only version 1 of the validator stake struct is supported'
+                );
+            }
+        }
+        return new BorshValidatorStakeView({
+            v1: new BorshValidatorStakeViewV1({
+                account_id: bp.account_id,
+                public_key: PublicKey.fromString(bp.public_key),
+                stake: bp.stake,
+            }),
+        });
+    });
+    const serializedBps = serialize(
+        SCHEMA,
+        // NOTE: just wrapping because borsh-js requires this type to be in the schema for some reason
+        new BorshValidatorStakeViewWrapper({ bps: borshBps })
+    );
+    return Buffer.from(sha256.array(serializedBps));
+}