@feelyourprotocol/mpt 8141.0.0

package/src/node/branch.ts

@@ -0,0 +1,60 @@
+import { RLP } from '@feelyourprotocol/rlp'
+
+import type { BranchMPTNodeBranchValue, NodeReferenceOrRawMPTNode } from '../types.ts'
+
+export class BranchMPTNode {
+  _branches: BranchMPTNodeBranchValue[]
+  _value: Uint8Array | null
+
+  constructor() {
+    this._branches = new Array(16).fill(null)
+    this._value = null
+  }
+
+  static fromArray(arr: Uint8Array[]): BranchMPTNode {
+    const node = new BranchMPTNode()
+    node._branches = arr.slice(0, 16)
+    node._value = arr[16]
+    return node
+  }
+
+  value(v?: Uint8Array | null): Uint8Array | null {
+    if (v !== null && v !== undefined) {
+      this._value = v
+    }
+
+    return this._value && this._value.length > 0 ? this._value : null
+  }
+
+  setBranch(i: number, v: BranchMPTNodeBranchValue) {
+    this._branches[i] = v
+  }
+
+  raw(): BranchMPTNodeBranchValue[] {
+    return [...this._branches, this._value]
+  }
+
+  serialize(): Uint8Array {
+    return RLP.encode(this.raw())
+  }
+
+  getBranch(i: number): BranchMPTNodeBranchValue {
+    const b = this._branches[i]
+    if (b !== null && b.length > 0) {
+      return b
+    } else {
+      return null
+    }
+  }
+
+  getChildren(): [number, NodeReferenceOrRawMPTNode][] {
+    const children: [number, NodeReferenceOrRawMPTNode][] = []
+    for (let i = 0; i < 16; i++) {
+      const b = this._branches[i]
+      if (b !== null && b.length > 0) {
+        children.push([i, b])
+      }
+    }
+    return children
+  }
+}

package/src/node/extension.ts

@@ -0,0 +1,13 @@
+import { ExtensionOrLeafMPTNodeBase } from './extensionOrLeafNodeBase.ts'
+
+import type { Nibbles, RawExtensionMPTNode } from '../types.ts'
+
+export class ExtensionMPTNode extends ExtensionOrLeafMPTNodeBase {
+  constructor(nibbles: Nibbles, value: Uint8Array) {
+    super(nibbles, value, false)
+  }
+
+  raw(): RawExtensionMPTNode {
+    return super.raw()
+  }
+}

package/src/node/extensionOrLeafNodeBase.ts

@@ -0,0 +1,54 @@
+import { RLP } from '@feelyourprotocol/rlp'
+
+import { addHexPrefix, removeHexPrefix } from '../util/hex.ts'
+import { nibblesTypeToPackedBytes } from '../util/nibbles.ts'
+
+import type { Nibbles, RawExtensionMPTNode, RawLeafMPTNode } from '../types.ts'
+
+export abstract class ExtensionOrLeafMPTNodeBase {
+  _nibbles: Nibbles
+  _value: Uint8Array
+  _isLeaf: boolean
+
+  constructor(nibbles: Nibbles, value: Uint8Array, isLeaf: boolean) {
+    this._nibbles = nibbles
+    this._value = value
+    this._isLeaf = isLeaf
+  }
+
+  static decodeKey(key: Nibbles): Nibbles {
+    return removeHexPrefix(key)
+  }
+
+  encodedKey(): Nibbles {
+    return addHexPrefix(this._nibbles.slice(0), this._isLeaf)
+  }
+
+  key(k?: Nibbles): Nibbles {
+    if (k !== undefined) {
+      this._nibbles = k
+    }
+
+    return this._nibbles.slice(0)
+  }
+
+  keyLength() {
+    return this._nibbles.length
+  }
+
+  value(v?: Uint8Array) {
+    if (v !== undefined) {
+      this._value = v
+    }
+
+    return this._value
+  }
+
+  raw(): RawExtensionMPTNode | RawLeafMPTNode {
+    return [nibblesTypeToPackedBytes(this.encodedKey()), this._value]
+  }
+
+  serialize(): Uint8Array {
+    return RLP.encode(this.raw())
+  }
+}

package/src/node/index.ts

@@ -0,0 +1,4 @@
+export * from './branch.ts'
+export * from './extension.ts'
+export * from './leaf.ts'
+export * from './util.ts'

package/src/node/leaf.ts

@@ -0,0 +1,13 @@
+import { ExtensionOrLeafMPTNodeBase } from './extensionOrLeafNodeBase.ts'
+
+import type { Nibbles, RawLeafMPTNode } from '../types.ts'
+
+export class LeafMPTNode extends ExtensionOrLeafMPTNodeBase {
+  constructor(nibbles: Nibbles, value: Uint8Array) {
+    super(nibbles, value, true)
+  }
+
+  raw(): RawLeafMPTNode {
+    return super.raw()
+  }
+}

package/src/node/util.ts

@@ -0,0 +1,35 @@
+import { RLP } from '@feelyourprotocol/rlp'
+import { EthereumJSErrorWithoutCode, type NestedUint8Array } from '@feelyourprotocol/util'
+
+import { isTerminator } from '../util/hex.ts'
+import { bytesToNibbles } from '../util/nibbles.ts'
+
+import { BranchMPTNode } from './branch.ts'
+import { ExtensionMPTNode } from './extension.ts'
+import { LeafMPTNode } from './leaf.ts'
+
+export function decodeRawMPTNode(raw: Uint8Array[]) {
+  if (raw.length === 17) {
+    return BranchMPTNode.fromArray(raw)
+  } else if (raw.length === 2) {
+    const nibbles = bytesToNibbles(raw[0])
+    if (isTerminator(nibbles)) {
+      return new LeafMPTNode(LeafMPTNode.decodeKey(nibbles), raw[1])
+    }
+    return new ExtensionMPTNode(ExtensionMPTNode.decodeKey(nibbles), raw[1])
+  } else {
+    throw EthereumJSErrorWithoutCode('Invalid node')
+  }
+}
+
+export function isRawMPTNode(n: Uint8Array | NestedUint8Array): n is Uint8Array[] {
+  return Array.isArray(n) && !(n instanceof Uint8Array)
+}
+
+export function decodeMPTNode(node: Uint8Array) {
+  const decodedNode = RLP.decode(Uint8Array.from(node))
+  if (!isRawMPTNode(decodedNode)) {
+    throw EthereumJSErrorWithoutCode('Invalid node')
+  }
+  return decodeRawMPTNode(decodedNode)
+}

package/src/proof/index.ts

@@ -0,0 +1,2 @@
+export * from './proof.ts'
+export * from './range.ts'

package/src/proof/proof.ts

@@ -0,0 +1,135 @@
+import { EthereumJSErrorWithoutCode, bytesToHex, concatBytes, equalsBytes } from '@feelyourprotocol/util'
+
+import { type MPTOpts, MerklePatriciaTrie, type Proof, createMPTFromProof } from '../index.ts'
+
+import type { PutBatch } from '@feelyourprotocol/util'
+
+/**
+ * An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes
+ * from the root node to the leaf node storing state data.
+ * @param rootHash Root hash of the trie that this proof was created from and is being verified for
+ * @param key Key that is being verified and that the proof is created for
+ * @param proof An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data.
+ * @param opts optional, the opts may include a custom hashing function to use with the trie for proof verification
+ * @throws If proof is found to be invalid.
+ * @returns The value from the key, or null if valid proof of non-existence.
+ */
+export async function verifyMerkleProof(
+  key: Uint8Array,
+  proof: Proof,
+  opts?: MPTOpts,
+): Promise<Uint8Array | null> {
+  try {
+    const proofTrie = await createMPTFromProof(proof, opts)
+    const value = await proofTrie.get(key, true)
+    return value
+  } catch {
+    throw EthereumJSErrorWithoutCode('Invalid proof provided')
+  }
+}
+
+/**
+ * Creates a proof from a trie and key that can be verified using {@link verifyMPTWithMerkleProof}. An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains
+ * the encoded trie nodes from the root node to the leaf node storing state data. The returned proof will be in the format of an array that contains Uint8Arrays of
+ * serialized branch, extension, and/or leaf nodes.
+ * @param key key to create a proof for
+ */
+export async function createMerkleProof(trie: MerklePatriciaTrie, key: Uint8Array): Promise<Proof> {
+  trie['DEBUG'] && trie['debug'](`Creating Proof for Key: ${bytesToHex(key)}`, ['create_proof'])
+  const { stack } = await trie.findPath(trie['appliedKey'](key))
+  const p = stack.map((stackElem) => {
+    return stackElem.serialize()
+  })
+  trie['DEBUG'] && trie['debug'](`Proof created with (${stack.length}) nodes`, ['create_proof'])
+  return p
+}
+
+/**
+ * Updates a trie from a proof by putting all the nodes in the proof into the trie. Pass {@param shouldVerifyRoot} as true to check
+ * that root key of proof matches root of trie and throw if not.
+ * An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof contains the encoded trie nodes from the root node to the leaf node storing state data.
+ * @param trie The trie to update from the proof.
+ * @param proof An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof to update the trie from.
+ * @param shouldVerifyRoot - defaults to false. If `true`, verifies that the root key of the proof matches the trie root and throws if not (i.e invalid proof).
+ * @returns The root of the proof
+ */
+export async function updateMPTFromMerkleProof(
+  trie: MerklePatriciaTrie,
+  proof: Proof,
+  shouldVerifyRoot: boolean = false,
+) {
+  trie['DEBUG'] && trie['debug'](`Saving (${proof.length}) proof nodes in DB`, ['from_proof'])
+  const opStack = proof.map((nodeValue) => {
+    let key = Uint8Array.from(trie['hash'](nodeValue))
+    key = trie['_opts'].keyPrefix ? concatBytes(trie['_opts'].keyPrefix, key) : key
+    return {
+      type: 'put',
+      key,
+      value: nodeValue,
+    } as PutBatch
+  })
+
+  if (shouldVerifyRoot) {
+    if (opStack[0] !== undefined && opStack[0] !== null) {
+      if (!equalsBytes(trie.root(), opStack[0].key)) {
+        throw EthereumJSErrorWithoutCode('The provided proof does not have the expected trie root')
+      }
+    }
+  }
+
+  await trie['_db'].batch(opStack)
+  if (opStack[0] !== undefined) {
+    return opStack[0].key
+  }
+}
+
+/**
+ * Verifies a proof by putting all of its nodes into a trie and attempting to get the proven key. An (EIP-1186)[https://eips.ethereum.org/EIPS/eip-1186] proof
+ * contains the encoded trie nodes from the root node to the leaf node storing state data.
+ * @param trie The trie to verify the proof against
+ * @param rootHash Root hash of the trie that this proof was created from and is being verified for
+ * @param key Key that is being verified and that the proof is created for
+ * @param proof an EIP-1186 proof to verify the key against
+ * @throws If proof is found to be invalid.
+ * @returns The value from the key, or null if valid proof of non-existence.
+ */
+export async function verifyMPTWithMerkleProof(
+  trie: MerklePatriciaTrie,
+  rootHash: Uint8Array,
+  key: Uint8Array,
+  proof: Proof,
+): Promise<Uint8Array | null> {
+  trie['DEBUG'] &&
+    trie['debug'](
+      `Verifying Proof:\n|| Key: ${bytesToHex(key)}\n|| Root: ${bytesToHex(
+        rootHash,
+      )}\n|| Proof: (${proof.length}) nodes
+  `,
+      ['VERIFY_PROOF'],
+    )
+  const proofTrie = new MerklePatriciaTrie({
+    root: rootHash,
+    useKeyHashingFunction: trie['_opts'].useKeyHashingFunction,
+    common: trie['_opts'].common,
+  })
+  try {
+    await updateMPTFromMerkleProof(proofTrie, proof, true)
+  } catch {
+    throw EthereumJSErrorWithoutCode('Invalid proof nodes given')
+  }
+  try {
+    trie['DEBUG'] &&
+      trie['debug'](`Verifying proof by retrieving key: ${bytesToHex(key)} from proof trie`, [
+        'VERIFY_PROOF',
+      ])
+    const value = await proofTrie.get(trie['appliedKey'](key), true)
+    trie['DEBUG'] && trie['debug'](`PROOF VERIFIED`, ['VERIFY_PROOF'])
+    return value
+  } catch (err: any) {
+    if (err.message === 'Missing node in DB') {
+      throw EthereumJSErrorWithoutCode('Invalid proof provided')
+    } else {
+      throw err
+    }
+  }
+}