From 16cda7d48cebfa0f0fe3892459645838e8f7c17b Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Fri, 17 Apr 2020 12:11:54 -0700 Subject: [PATCH 01/17] Bump version and update CHANGELOG.md --- CHANGELOG.md | 32 ++++++++++++++++++++++++++++++++ package.json | 2 +- 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 481e076..31d69c5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,38 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) (modification: no type change headlines) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [4.0.0] - 2020-04-17 + +This release introduces a major API upgrade from callbacks to Promises. Behind the scenes the library and its tests have been refactored to TypeScript. + +See the items below for other various updates and fixes included in this release. + +- Move `failingRefactorTests` to `secure.spec.ts`, PR [#110](https://github.com/ethereumjs/merkle-patricia-tree/pull/110) +- Better document `_formatNode`, PR [#109](https://github.com/ethereumjs/merkle-patricia-tree/pull/109) +- Promisify rest of library, PR [#107](https://github.com/ethereumjs/merkle-patricia-tree/pull/107) +- Upgrade test suite to TS, PR [#106](https://github.com/ethereumjs/merkle-patricia-tree/pull/106) +- Upgrade from Travis to GH Actions, PR [#105](https://github.com/ethereumjs/merkle-patricia-tree/pull/105) +- Fix test cases and docs, PR [#104](https://github.com/ethereumjs/merkle-patricia-tree/pull/104) +- Refactor TrieNode, add levelup types, PR [#98](https://github.com/ethereumjs/merkle-patricia-tree/pull/98) +- Fix Travis's xvfb service, PR [#97](https://github.com/ethereumjs/merkle-patricia-tree/pull/97) +- Migrate to Typescript, PR [#96](https://github.com/ethereumjs/merkle-patricia-tree/pull/96) +- fixed src code links in docs, PR [#93](https://github.com/ethereumjs/merkle-patricia-tree/pull/93) +- Re-add raw methods, accept leveldb in constructor, minor fixes, PR [#92](https://github.com/ethereumjs/merkle-patricia-tree/pull/92) +- Rename deprecated sha3 consts and func to keccak256, PR [#91](https://github.com/ethereumjs/merkle-patricia-tree/pull/91) +- Use module.exports syntax in util files, PR [#90](https://github.com/ethereumjs/merkle-patricia-tree/pull/90) +- Add more Ethereum state DB focused example accessing account values, PR [#89](https://github.com/ethereumjs/merkle-patricia-tree/pull/89) +- Org links and git hooks, PR [#87](https://github.com/ethereumjs/merkle-patricia-tree/pull/87) +- \_lookupNode callback to use standard error, response pattern, PR [#83](https://github.com/ethereumjs/merkle-patricia-tree/pull/83) +- Support for proofs of null/absence. Dried up prove/verify. PR [#82](https://github.com/ethereumjs/merkle-patricia-tree/pull/82) +- Update tape to v4.10.1, PR [#81](https://github.com/ethereumjs/merkle-patricia-tree/pull/81) +- Fix prove and verifyProof in SecureTrie, PR [#79](https://github.com/ethereumjs/merkle-patricia-tree/pull/79) +- Extract db-related methods from baseTrie, PR [#74](https://github.com/ethereumjs/merkle-patricia-tree/pull/74) +- Merge checkpoint and secure interface with their ES6 classes, PR [#73](https://github.com/ethereumjs/merkle-patricia-tree/pull/73) +- Convert trieNode to ES6 class, PR [#71](https://github.com/ethereumjs/merkle-patricia-tree/pull/71) +- Drop ethereumjs-testing dep and fix bug in branch value update, PR [#69](https://github.com/ethereumjs/merkle-patricia-tree/pull/69) + +[4.0.0]: https://github.com/ethereumjs/merkle-patricia-tree/compare/v3.0.0...v4.0.0 + ## [3.0.0] - 2019-01-03 This release comes along with some major version bump of the underlying `level` diff --git a/package.json b/package.json index 5bdc6d3..68db553 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "merkle-patricia-tree", - "version": "3.0.0", + "version": "4.0.0", "description": "This is an implementation of the modified merkle patricia tree as specified in the Ethereum's yellow paper.", "main": "dist/index.js", "types": "dist/index.d.ts", From 413f53559445ea466633f8567ccac73a9e26b7de Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Mon, 4 May 2020 13:05:49 -0700 Subject: [PATCH 02/17] Update CHANGELOG --- CHANGELOG.md | 79 ++++++++++++++++++++++----------- docs/classes/_basetrie_.trie.md | 2 +- src/baseTrie.ts | 2 +- 3 files changed, 54 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 31d69c5..5426b1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,33 +8,58 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) ## [4.0.0] - 2020-04-17 -This release introduces a major API upgrade from callbacks to Promises. Behind the scenes the library and its tests have been refactored to TypeScript. - -See the items below for other various updates and fixes included in this release. - -- Move `failingRefactorTests` to `secure.spec.ts`, PR [#110](https://github.com/ethereumjs/merkle-patricia-tree/pull/110) -- Better document `_formatNode`, PR [#109](https://github.com/ethereumjs/merkle-patricia-tree/pull/109) -- Promisify rest of library, PR [#107](https://github.com/ethereumjs/merkle-patricia-tree/pull/107) -- Upgrade test suite to TS, PR [#106](https://github.com/ethereumjs/merkle-patricia-tree/pull/106) -- Upgrade from Travis to GH Actions, PR [#105](https://github.com/ethereumjs/merkle-patricia-tree/pull/105) -- Fix test cases and docs, PR [#104](https://github.com/ethereumjs/merkle-patricia-tree/pull/104) -- Refactor TrieNode, add levelup types, PR [#98](https://github.com/ethereumjs/merkle-patricia-tree/pull/98) -- Fix Travis's xvfb service, PR [#97](https://github.com/ethereumjs/merkle-patricia-tree/pull/97) -- Migrate to Typescript, PR [#96](https://github.com/ethereumjs/merkle-patricia-tree/pull/96) -- fixed src code links in docs, PR [#93](https://github.com/ethereumjs/merkle-patricia-tree/pull/93) -- Re-add raw methods, accept leveldb in constructor, minor fixes, PR [#92](https://github.com/ethereumjs/merkle-patricia-tree/pull/92) -- Rename deprecated sha3 consts and func to keccak256, PR [#91](https://github.com/ethereumjs/merkle-patricia-tree/pull/91) -- Use module.exports syntax in util files, PR [#90](https://github.com/ethereumjs/merkle-patricia-tree/pull/90) -- Add more Ethereum state DB focused example accessing account values, PR [#89](https://github.com/ethereumjs/merkle-patricia-tree/pull/89) -- Org links and git hooks, PR [#87](https://github.com/ethereumjs/merkle-patricia-tree/pull/87) -- \_lookupNode callback to use standard error, response pattern, PR [#83](https://github.com/ethereumjs/merkle-patricia-tree/pull/83) -- Support for proofs of null/absence. Dried up prove/verify. PR [#82](https://github.com/ethereumjs/merkle-patricia-tree/pull/82) -- Update tape to v4.10.1, PR [#81](https://github.com/ethereumjs/merkle-patricia-tree/pull/81) -- Fix prove and verifyProof in SecureTrie, PR [#79](https://github.com/ethereumjs/merkle-patricia-tree/pull/79) -- Extract db-related methods from baseTrie, PR [#74](https://github.com/ethereumjs/merkle-patricia-tree/pull/74) -- Merge checkpoint and secure interface with their ES6 classes, PR [#73](https://github.com/ethereumjs/merkle-patricia-tree/pull/73) -- Convert trieNode to ES6 class, PR [#71](https://github.com/ethereumjs/merkle-patricia-tree/pull/71) -- Drop ethereumjs-testing dep and fix bug in branch value update, PR [#69](https://github.com/ethereumjs/merkle-patricia-tree/pull/69) +This release introduces a major API upgrade from callbacks to Promises. + +See the [docs](https://github.com/ethereumjs/merkle-patricia-tree/tree/master/docs) for the latest method signatures. + +Example using async/await syntax: + +```typescript +import { BaseTrie as Trie } from 'merkle-patricia-tree' + +const trie = new Trie() +await trie.put(Buffer.from('test'), Buffer.from('one')) +const value = await trie.get(Buffer.from('test')) +``` + +### Changed + +- Convert trieNode to ES6 class ([#71](https://github.com/ethereumjs/merkle-patricia-tree/pull/71)) +- Merge checkpoint and secure interface with their ES6 classes ([#73](https://github.com/ethereumjs/merkle-patricia-tree/pull/73)) +- Extract db-related methods from baseTrie ([#74](https://github.com/ethereumjs/merkle-patricia-tree/pull/74)) +- \_lookupNode callback to use standard error, response pattern ([#83](https://github.com/ethereumjs/merkle-patricia-tree/pull/83)) +- Accept leveldb in constructor, minor fixes ([#92](https://github.com/ethereumjs/merkle-patricia-tree/pull/92)) +- Refactor TrieNode, add levelup types ([#98](https://github.com/ethereumjs/merkle-patricia-tree/pull/98)) +- Promisify rest of library ([#107](https://github.com/ethereumjs/merkle-patricia-tree/pull/107)) +- Use `Nibbles` type for `number[]` ([#115](https://github.com/ethereumjs/merkle-patricia-tree/pull/115)) +- Upgrade ethereumjs-util to 7.0.0 / Upgrade level-mem to 5.0.1 ([#116](https://github.com/ethereumjs/merkle-patricia-tree/pull/116)) +- Create dual ES5 and ES2017 builds ([#117](https://github.com/ethereumjs/merkle-patricia-tree/pull/117)) + +### Added + +- Support for proofs of null/absence. Dried up prove/verify. ([#82](https://github.com/ethereumjs/merkle-patricia-tree/pull/82)) +- Add more Ethereum state DB focused example accessing account values ([#89](https://github.com/ethereumjs/merkle-patricia-tree/pull/89)) + +### Fixed + +- Drop ethereumjs-testing dep and fix bug in branch value update ([#69](https://github.com/ethereumjs/merkle-patricia-tree/pull/69)) +- Fix prove and verifyProof in SecureTrie ([#79](https://github.com/ethereumjs/merkle-patricia-tree/pull/70)) +- Fixed src code links in docs ([#93](https://github.com/ethereumjs/merkle-patricia-tree/pull/93)) + +### Dev / Testing / CI + +- Update tape to v4.10.1 ([#81](https://github.com/ethereumjs/merkle-patricia-tree/pull/81)) +- Org links and git hooks ([#87](https://github.com/ethereumjs/merkle-patricia-tree/pull/87)) +- Use module.exports syntax in util files ([#90](https://github.com/ethereumjs/merkle-patricia-tree/pull/90)) +- Rename deprecated sha3 consts and func to keccak256 ([#91](https://github.com/ethereumjs/merkle-patricia-tree/pull/91)) +- Migrate to Typescript ([#96](https://github.com/ethereumjs/merkle-patricia-tree/pull/96)) +- Fix Travis's xvfb service ([#97](https://github.com/ethereumjs/merkle-patricia-tree/pull/97)) +- Fix test cases and docs ([#104](https://github.com/ethereumjs/merkle-patricia-tree/pull/104)) +- Upgrade CI Provider from Travis to GH Actions ([#105](https://github.com/ethereumjs/merkle-patricia-tree/pull/105)) +- Upgrade test suite to TS ([#106](https://github.com/ethereumjs/merkle-patricia-tree/pull/106)) +- Better document `_formatNode` ([#109](https://github.com/ethereumjs/merkle-patricia-tree/pull/109)) +- Move `failingRefactorTests` to `secure.spec.ts` ([#110](https://github.com/ethereumjs/merkle-patricia-tree/pull/110)) +- Fix test suite typos ([#114](https://github.com/ethereumjs/merkle-patricia-tree/pull/110)) [4.0.0]: https://github.com/ethereumjs/merkle-patricia-tree/compare/v3.0.0...v4.0.0 diff --git a/docs/classes/_basetrie_.trie.md b/docs/classes/_basetrie_.trie.md index 5bb9f22..310a4fe 100644 --- a/docs/classes/_basetrie_.trie.md +++ b/docs/classes/_basetrie_.trie.md @@ -3,7 +3,7 @@ # Class: Trie Use `import { BaseTrie as Trie } from 'merkle-patricia-tree'` for the base interface. -In Ethereum applications stick with the Secure Trie Overlay `import { SecureTrie } from 'merkle-patricia-tree'`. +In Ethereum applications stick with the Secure Trie Overlay `import { SecureTrie as Trie } from 'merkle-patricia-tree'`. The API for the base and the secure interface are about the same. **`param`** A [levelup](https://github.com/Level/levelup) instance. By default creates an in-memory [memdown](https://github.com/Level/memdown) instance. diff --git a/src/baseTrie.ts b/src/baseTrie.ts index d13490b..5145f39 100644 --- a/src/baseTrie.ts +++ b/src/baseTrie.ts @@ -28,7 +28,7 @@ type FoundNode = (nodeRef: Buffer, node: TrieNode, key: Nibbles, walkController: /** * Use `import { BaseTrie as Trie } from 'merkle-patricia-tree'` for the base interface. - * In Ethereum applications stick with the Secure Trie Overlay `import { SecureTrie } from 'merkle-patricia-tree'`. + * In Ethereum applications stick with the Secure Trie Overlay `import { SecureTrie as Trie } from 'merkle-patricia-tree'`. * The API for the base and the secure interface are about the same. * @param {Object} [db] - A [levelup](https://github.com/Level/levelup) instance. By default creates an in-memory [memdown](https://github.com/Level/memdown) instance. * If the db is `null` or left undefined, then the trie will be stored in memory via [memdown](https://github.com/Level/memdown) From afce5cbdf248b24e6b8db95082a1d79c6d39c2b9 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Tue, 12 May 2020 10:17:41 -0700 Subject: [PATCH 03/17] Update SecureTrie import reference --- src/secure.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/secure.ts b/src/secure.ts index 3a6c22f..5a47600 100644 --- a/src/secure.ts +++ b/src/secure.ts @@ -3,7 +3,7 @@ import { CheckpointTrie } from './checkpointTrie' /** * You can create a secure Trie where the keys are automatically hashed - * using **keccak256** by using `require('merkle-patricia-tree/secure')`. + * using **keccak256** by using `require('merkle-patricia-tree').SecureTrie`. * It has the same methods and constructor as `Trie`. * @class SecureTrie * @extends Trie From 6a09b6ed4e6dac4c4f8884a0ea2338952e3e7b7e Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Tue, 12 May 2020 10:19:44 -0700 Subject: [PATCH 04/17] Update docs for checkpointTrie db override --- src/checkpointTrie.ts | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/checkpointTrie.ts b/src/checkpointTrie.ts index a39d16d..5ee40e4 100644 --- a/src/checkpointTrie.ts +++ b/src/checkpointTrie.ts @@ -29,9 +29,8 @@ export class CheckpointTrie extends BaseTrie { /** * Creates a checkpoint that can later be reverted to or committed. - * After this is called, no changes to the trie will be permanently saved - * until `commit` is called. Calling `db.put` overrides the checkpointing - * mechanism and would directly write to db. + * After this is called, no changes to the trie will be permanently saved until `commit` is called. + * To override the checkpointing mechanism use `_maindb.put` to write directly write to db. */ checkpoint() { const wasCheckpoint = this.isCheckpoint From a68c1c931714553d9a4ba7fcf519a5dcb1c505e7 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Tue, 12 May 2020 10:20:04 -0700 Subject: [PATCH 05/17] Update changelog with trie raw method breaking changes --- CHANGELOG.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5426b1f..d99a82a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,8 +10,6 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) This release introduces a major API upgrade from callbacks to Promises. -See the [docs](https://github.com/ethereumjs/merkle-patricia-tree/tree/master/docs) for the latest method signatures. - Example using async/await syntax: ```typescript @@ -22,6 +20,16 @@ await trie.put(Buffer.from('test'), Buffer.from('one')) const value = await trie.get(Buffer.from('test')) ``` +### Breaking Changes + +#### Trie methods + +See the [docs](https://github.com/ethereumjs/merkle-patricia-tree/tree/master/docs) for the latest Promise-based method signatures. + +#### Trie raw methods + +`getRaw`, `putRaw` and `delRaw` were deprecated in `v3.0.0` and have been removed from this release. Instead, please use `trie.db.get`, `trie.db.put`, and `trie.db.del`. If using a `SecureTrie` or `CheckpointTrie`, use `trie._maindb` to override the checkpointing mechanism and interact directly with the db. + ### Changed - Convert trieNode to ES6 class ([#71](https://github.com/ethereumjs/merkle-patricia-tree/pull/71)) @@ -43,7 +51,7 @@ const value = await trie.get(Buffer.from('test')) ### Fixed - Drop ethereumjs-testing dep and fix bug in branch value update ([#69](https://github.com/ethereumjs/merkle-patricia-tree/pull/69)) -- Fix prove and verifyProof in SecureTrie ([#79](https://github.com/ethereumjs/merkle-patricia-tree/pull/70)) +- Fix prove and verifyProof in SecureTrie ([#79](https://github.com/ethereumjs/merkle-patricia-tree/pull/79)) - Fixed src code links in docs ([#93](https://github.com/ethereumjs/merkle-patricia-tree/pull/93)) ### Dev / Testing / CI From 8a84ed41302d02d9bc151114bdaf0919383a2303 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Tue, 19 May 2020 11:45:13 -0700 Subject: [PATCH 06/17] move `@types/levelup` from devDeps to deps --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 68db553..344bc8c 100644 --- a/package.json +++ b/package.json @@ -49,6 +49,7 @@ ], "license": "MPL-2.0", "dependencies": { + "@types/levelup": "^3.1.1", "ethereumjs-util": "^7.0.0", "level-mem": "^5.0.1", "level-ws": "^2.0.0", @@ -62,7 +63,6 @@ "@ethereumjs/config-tsc": "^1.1.1", "@ethereumjs/config-tslint": "^1.1.1", "@types/bn.js": "^4.11.5", - "@types/levelup": "^3.1.1", "@types/tape": "^4.2.34", "husky": "^4.2.3", "karma": "^4.4.1", From f710dce0a8e078c4b888a08d68cb2535798040c2 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Tue, 19 May 2020 11:46:12 -0700 Subject: [PATCH 07/17] update `ethereumjs-util` to `7.0.1` --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 344bc8c..07a4c59 100644 --- a/package.json +++ b/package.json @@ -50,7 +50,7 @@ "license": "MPL-2.0", "dependencies": { "@types/levelup": "^3.1.1", - "ethereumjs-util": "^7.0.0", + "ethereumjs-util": "^7.0.1", "level-mem": "^5.0.1", "level-ws": "^2.0.0", "readable-stream": "^3.6.0", From 57a55949024b4520dca7ed3896d0ba4c64b35706 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Wed, 20 May 2020 10:46:37 -0700 Subject: [PATCH 08/17] move tsconfig `target` and `lib` options to compilerOptions --- package.json | 2 +- tsconfig.browser.json | 8 ++++---- tsconfig.json | 8 -------- tsconfig.prod.json | 8 ++++++++ 4 files changed, 13 insertions(+), 13 deletions(-) delete mode 100644 tsconfig.json create mode 100644 tsconfig.prod.json diff --git a/package.json b/package.json index 07a4c59..658fd9b 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "browser": "dist.browser/index.js", "scripts": { "benchmarks": "npm run build && ts-node benchmarks/index.ts", - "build": "tsc -p tsconfig.json && tsc -p tsconfig.browser.json", + "build": "tsc -p tsconfig.prod.json && tsc -p tsconfig.browser.json", "prepublishOnly": "npm run test && npm run build", "coverage": "nyc --reporter=lcov npm run test:node", "docs:build": "typedoc", diff --git a/tsconfig.browser.json b/tsconfig.browser.json index a6e9b2c..b4895da 100644 --- a/tsconfig.browser.json +++ b/tsconfig.browser.json @@ -1,9 +1,9 @@ { - "extends": "./tsconfig.json", + "extends": "./tsconfig.prod.json", "compilerOptions": { "outDir": "./dist.browser", - }, - "target": "es5", - "lib": ["dom", "es5"] + "target": "es5", + "lib": ["dom", "es5"] + } } \ No newline at end of file diff --git a/tsconfig.json b/tsconfig.json deleted file mode 100644 index bf015d8..0000000 --- a/tsconfig.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "extends": "@ethereumjs/config-tsc", - "compilerOptions": { - "outDir": "./dist" - }, - "include": ["src/**/*.ts"], - "target": "ES2017" -} diff --git a/tsconfig.prod.json b/tsconfig.prod.json new file mode 100644 index 0000000..29b17bf --- /dev/null +++ b/tsconfig.prod.json @@ -0,0 +1,8 @@ +{ + "extends": "@ethereumjs/config-tsc", + "compilerOptions": { + "outDir": "./dist", + "target": "ES2017" + }, + "include": ["src/**/*.ts"] +} From ecd079290c9e6e96a01ddbf9b97f5d712c8ebef9 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Fri, 22 May 2020 11:46:15 -0700 Subject: [PATCH 09/17] Include checkpoints in SecureTrie.copy --- src/checkpointTrie.ts | 9 +++------ src/secure.ts | 8 ++++++-- test/secure.spec.ts | 26 ++++++++++++++++++++++++++ 3 files changed, 35 insertions(+), 8 deletions(-) diff --git a/src/checkpointTrie.ts b/src/checkpointTrie.ts index 5ee40e4..2a63f87 100644 --- a/src/checkpointTrie.ts +++ b/src/checkpointTrie.ts @@ -81,13 +81,10 @@ export class CheckpointTrie extends BaseTrie { } /** - * Returns a copy of the underlying trie with the interface - * of CheckpointTrie. If during a checkpoint, the copy will - * contain the checkpointing metadata (incl. reference to the same scratch). - * @param {boolean} includeCheckpoints - If true and during a checkpoint, the copy will - * contain the checkpointing metadata and will use the same scratch as underlying db. + * Returns a copy of the underlying trie with the interface of CheckpointTrie. + * @param {boolean} includeCheckpoints - If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db. */ - copy(includeCheckpoints: boolean = true): CheckpointTrie { + copy(includeCheckpoints = true): CheckpointTrie { const db = this._mainDB.copy() const trie = new CheckpointTrie(db._leveldb, this.root) if (includeCheckpoints && this.isCheckpoint) { diff --git a/src/secure.ts b/src/secure.ts index 5a47600..cfc4fdc 100644 --- a/src/secure.ts +++ b/src/secure.ts @@ -24,8 +24,12 @@ export class SecureTrie extends CheckpointTrie { return super.verifyProof(rootHash, hash, proof) } - copy(): SecureTrie { - const trie = super.copy(false) + /** + * Returns a copy of the underlying trie with the interface of SecureTrie. + * @param {boolean} includeCheckpoints - If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db. + */ + copy(includeCheckpoints = true): SecureTrie { + const trie = super.copy(includeCheckpoints) const db = trie.db.copy() return new SecureTrie(db._leveldb, this.root) } diff --git a/test/secure.spec.ts b/test/secure.spec.ts index 4f7bb0b..448612d 100644 --- a/test/secure.spec.ts +++ b/test/secure.spec.ts @@ -124,3 +124,29 @@ tape('secure tests should not crash', async function (t) { await trie.put(gk, g) t.end() }) + +tape('SecureTrie.copy', function (it) { + it.test('created copy includes values added after checkpoint', async function (t) { + const trie = new SecureTrie() + + await trie.put(Buffer.from('key1'), Buffer.from('value1')) + trie.checkpoint() + await trie.put(Buffer.from('key2'), Buffer.from('value2')) + const trieCopy = trie.copy() + const value = await trieCopy.get(Buffer.from('key2')) + t.equal(value.toString(), 'value2') + t.end() + }) + + it.test('created copy includes values added before checkpoint', async function (t) { + const trie = new SecureTrie() + + await trie.put(Buffer.from('key1'), Buffer.from('value1')) + trie.checkpoint() + await trie.put(Buffer.from('key2'), Buffer.from('value2')) + const trieCopy = trie.copy() + const value = await trieCopy.get(Buffer.from('key1')) + t.equal(value.toString(), 'value1') + t.end() + }) +}) From 5f61cb2fb2ff06174a43c8fdd6dd09d7f623ab02 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Fri, 22 May 2020 12:03:09 -0700 Subject: [PATCH 10/17] Update changelog --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d99a82a..91720c5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,10 @@ See the [docs](https://github.com/ethereumjs/merkle-patricia-tree/tree/master/do `getRaw`, `putRaw` and `delRaw` were deprecated in `v3.0.0` and have been removed from this release. Instead, please use `trie.db.get`, `trie.db.put`, and `trie.db.del`. If using a `SecureTrie` or `CheckpointTrie`, use `trie._maindb` to override the checkpointing mechanism and interact directly with the db. +#### SecureTrie.copy + +`SecureTrie.copy` now includes checkpoint metadata by default. To maintain original behavior of _not_ copying checkpoint state, pass `false` to param `includeCheckpoints`. + ### Changed - Convert trieNode to ES6 class ([#71](https://github.com/ethereumjs/merkle-patricia-tree/pull/71)) @@ -42,6 +46,7 @@ See the [docs](https://github.com/ethereumjs/merkle-patricia-tree/tree/master/do - Use `Nibbles` type for `number[]` ([#115](https://github.com/ethereumjs/merkle-patricia-tree/pull/115)) - Upgrade ethereumjs-util to 7.0.0 / Upgrade level-mem to 5.0.1 ([#116](https://github.com/ethereumjs/merkle-patricia-tree/pull/116)) - Create dual ES5 and ES2017 builds ([#117](https://github.com/ethereumjs/merkle-patricia-tree/pull/117)) +- Include checkpoints by default in SecureTrie.copy ([#119](https://github.com/ethereumjs/merkle-patricia-tree/pull/119)) ### Added From c349e93daf0d8b842edc2b48ab217f417303a718 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Mon, 25 May 2020 12:42:33 -0700 Subject: [PATCH 11/17] upgrade ethereumjs-util to 7.0.2 --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 658fd9b..bb910cb 100644 --- a/package.json +++ b/package.json @@ -50,7 +50,7 @@ "license": "MPL-2.0", "dependencies": { "@types/levelup": "^3.1.1", - "ethereumjs-util": "^7.0.1", + "ethereumjs-util": "^7.0.2", "level-mem": "^5.0.1", "level-ws": "^2.0.0", "readable-stream": "^3.6.0", @@ -62,7 +62,7 @@ "@ethereumjs/config-prettier": "^1.1.1", "@ethereumjs/config-tsc": "^1.1.1", "@ethereumjs/config-tslint": "^1.1.1", - "@types/bn.js": "^4.11.5", + "@types/bn.js": "^4.11.6", "@types/tape": "^4.2.34", "husky": "^4.2.3", "karma": "^4.4.1", From 6462b31c539286dfc75d15f7ca0de49cd5eabb00 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Wed, 27 May 2020 10:17:31 -0700 Subject: [PATCH 12/17] Update CHANGELOG.md wrap example in function Co-authored-by: gabrocheleau --- CHANGELOG.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 91720c5..8eb9ec7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,8 +16,11 @@ Example using async/await syntax: import { BaseTrie as Trie } from 'merkle-patricia-tree' const trie = new Trie() -await trie.put(Buffer.from('test'), Buffer.from('one')) -const value = await trie.get(Buffer.from('test')) +async function test() { + await trie.put(Buffer.from('test'), Buffer.from('one')) + const value = await trie.get(Buffer.from('test')) + console.log(value) // 'one' +} ``` ### Breaking Changes From 9c137ad4ab05a87c9a5e4804871f645418729648 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Wed, 27 May 2020 10:27:55 -0700 Subject: [PATCH 13/17] add async function wrappers around examples --- CHANGELOG.md | 8 +++---- README.md | 68 ++++++++++++++++++++++++++++++---------------------- 2 files changed, 44 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8eb9ec7..6e2c1ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,13 +14,13 @@ Example using async/await syntax: ```typescript import { BaseTrie as Trie } from 'merkle-patricia-tree' - const trie = new Trie() async function test() { - await trie.put(Buffer.from('test'), Buffer.from('one')) - const value = await trie.get(Buffer.from('test')) - console.log(value) // 'one' + await trie.put(Buffer.from('test'), Buffer.from('one')) + const value = await trie.get(Buffer.from('test')) + console.log(value.toString()) // 'one' } +await test() ``` ### Breaking Changes diff --git a/README.md b/README.md index 1aa6c38..7f9ede6 100644 --- a/README.md +++ b/README.md @@ -30,17 +30,25 @@ import { BaseTrie as Trie } from 'merkle-patricia-tree' const db = level('./testdb') const trie = new Trie(db) -await trie.put(Buffer.from('test'), Buffer.from('one')) -const value = await trie.get(Buffer.from('test')) -console.log(value.toString()) +async function test() { + await trie.put(Buffer.from('test'), Buffer.from('one')) + const value = await trie.get(Buffer.from('test')) + console.log(value.toString()) // 'one' +} + +await test() ``` ## Merkle Proofs ```typescript -const prove = await Trie.prove(trie, Buffer.from('test')) -const value = await Trie.verifyProof(trie.root, Buffer.from('test'), prove) -console.log(value.toString()) +async function test() { + const prove = await Trie.prove(trie, Buffer.from('test')) + const value = await Trie.verifyProof(trie.root, Buffer.from('test'), prove) + console.log(value.toString()) +} + +await test() ``` ## Read stream on Geth DB @@ -79,28 +87,32 @@ const trie = new Trie(db, stateRoot) const address = 'AN_ETHEREUM_ACCOUNT_ADDRESS' -const data = await trie.get(address) -const acc = new Account(data) - -console.log('-------State-------') -console.log(`nonce: ${new BN(acc.nonce)}`) -console.log(`balance in wei: ${new BN(acc.balance)}`) -console.log(`storageRoot: ${bufferToHex(acc.stateRoot)}`) -console.log(`codeHash: ${bufferToHex(acc.codeHash)}`) - -let storageTrie = trie.copy() -storageTrie.root = acc.stateRoot - -console.log('------Storage------') -const stream = storageTrie.createReadStream() -stream - .on('data', (data) => { - console.log(`key: ${bufferToHex(data.key)}`) - console.log(`Value: ${bufferToHex(rlp.decode(data.value))}`) - }) - .on('end', () => { - console.log('Finished reading storage.') - }) +async function test() { + const data = await trie.get(address) + const acc = new Account(data) + + console.log('-------State-------') + console.log(`nonce: ${new BN(acc.nonce)}`) + console.log(`balance in wei: ${new BN(acc.balance)}`) + console.log(`storageRoot: ${bufferToHex(acc.stateRoot)}`) + console.log(`codeHash: ${bufferToHex(acc.codeHash)}`) + + let storageTrie = trie.copy() + storageTrie.root = acc.stateRoot + + console.log('------Storage------') + const stream = storageTrie.createReadStream() + stream + .on('data', (data) => { + console.log(`key: ${bufferToHex(data.key)}`) + console.log(`Value: ${bufferToHex(rlp.decode(data.value))}`) + }) + .on('end', () => { + console.log('Finished reading storage.') + }) +} + +await test() ``` # API From 0a6a2ca33d87589cd435c67c5056e33fa9648a0b Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Wed, 27 May 2020 10:39:40 -0700 Subject: [PATCH 14/17] remove unneeded await from examples --- CHANGELOG.md | 2 +- README.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e2c1ad..4d419f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ async function test() { const value = await trie.get(Buffer.from('test')) console.log(value.toString()) // 'one' } -await test() +test() ``` ### Breaking Changes diff --git a/README.md b/README.md index 7f9ede6..1ed1797 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ async function test() { console.log(value.toString()) // 'one' } -await test() +test() ``` ## Merkle Proofs @@ -48,7 +48,7 @@ async function test() { console.log(value.toString()) } -await test() +test() ``` ## Read stream on Geth DB @@ -112,7 +112,7 @@ async function test() { }) } -await test() +test() ``` # API From 3ed946a3f3aa2d7a962bfdb616421bbda589f1a4 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Mon, 1 Jun 2020 10:01:25 -0700 Subject: [PATCH 15/17] Rename Trie.prove to Trie.createProof (#122) * rename Trie.prove to Trie.createProof tidy up typedoc * regen docs * add pr to changelog * move export type up --- CHANGELOG.md | 5 + README.md | 11 +- docs/classes/_basetrie_.trie.md | 238 ++++++++------- .../_checkpointtrie_.checkpointtrie.md | 275 +++++++++--------- docs/classes/_secure_.securetrie.md | 275 ++++++++++-------- docs/modules/_basetrie_.md | 12 + package.json | 2 +- src/baseTrie.ts | 131 +++++---- src/checkpointTrie.ts | 20 +- src/db.ts | 2 +- src/secure.ts | 45 ++- src/util/hex.ts | 3 - src/util/nibbles.ts | 9 +- test/proof.spec.ts | 28 +- test/secure.spec.ts | 6 +- tsconfig.json | 5 + typedoc.json | 2 +- 17 files changed, 594 insertions(+), 475 deletions(-) create mode 100644 tsconfig.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d419f5..ee6e437 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,10 @@ test() See the [docs](https://github.com/ethereumjs/merkle-patricia-tree/tree/master/docs) for the latest Promise-based method signatures. +#### Trie.prove renamed to Trie.createProof + +To clarify the method's purpose `Trie.prove` has been renamed to `Trie.createProof`. `Trie.prove` has been deprecated but will remain as an alias for `Trie.createProof` until removed. + #### Trie raw methods `getRaw`, `putRaw` and `delRaw` were deprecated in `v3.0.0` and have been removed from this release. Instead, please use `trie.db.get`, `trie.db.put`, and `trie.db.del`. If using a `SecureTrie` or `CheckpointTrie`, use `trie._maindb` to override the checkpointing mechanism and interact directly with the db. @@ -50,6 +54,7 @@ See the [docs](https://github.com/ethereumjs/merkle-patricia-tree/tree/master/do - Upgrade ethereumjs-util to 7.0.0 / Upgrade level-mem to 5.0.1 ([#116](https://github.com/ethereumjs/merkle-patricia-tree/pull/116)) - Create dual ES5 and ES2017 builds ([#117](https://github.com/ethereumjs/merkle-patricia-tree/pull/117)) - Include checkpoints by default in SecureTrie.copy ([#119](https://github.com/ethereumjs/merkle-patricia-tree/pull/119)) +- Rename Trie.prove to Trie.createProof ([#122](https://github.com/ethereumjs/merkle-patricia-tree/pull/122)) ### Added diff --git a/README.md b/README.md index 1ed1797..aa05df1 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard) -This is an implementation of the modified merkle patricia tree as specified in the [Ethereum's Yellow Paper](http://gavwood.com/Paper.pdf): +This is an implementation of the modified merkle patricia tree as specified in the [Ethereum Yellow Paper](http://gavwood.com/Paper.pdf): > The modified Merkle Patricia tree (trie) provides a persistent data structure to map between arbitrary-length binary data (byte arrays). It is defined in terms of a mutable data structure to map between 256-bit binary fragments and arbitrary-length binary data. The core of the trie, and its sole requirement in terms of the protocol specification is to provide a single 32-byte value that identifies a given set of key-value pairs. @@ -42,10 +42,13 @@ test() ## Merkle Proofs ```typescript +const trie = new Trie() + async function test() { - const prove = await Trie.prove(trie, Buffer.from('test')) - const value = await Trie.verifyProof(trie.root, Buffer.from('test'), prove) - console.log(value.toString()) + await trie.put(Buffer.from('test'), Buffer.from('one')) + const proof = await Trie.createProof(trie, Buffer.from('test')) + const value = await Trie.verifyProof(trie.root, Buffer.from('test'), proof) + console.log(value.toString()) // 'one' } test() diff --git a/docs/classes/_basetrie_.trie.md b/docs/classes/_basetrie_.trie.md index 310a4fe..fbf014e 100644 --- a/docs/classes/_basetrie_.trie.md +++ b/docs/classes/_basetrie_.trie.md @@ -38,13 +38,13 @@ If the db is `null` or left undefined, then the trie will be stored in memory vi ### Methods -* [_createInitialNode](_basetrie_.trie.md#_createinitialnode) -* [_deleteNode](_basetrie_.trie.md#_deletenode) +* [_createInitialNode](_basetrie_.trie.md#private-_createinitialnode) +* [_deleteNode](_basetrie_.trie.md#private-_deletenode) * [_findDbNodes](_basetrie_.trie.md#_finddbnodes) -* [_findValueNodes](_basetrie_.trie.md#_findvaluenodes) +* [_findValueNodes](_basetrie_.trie.md#private-_findvaluenodes) * [_formatNode](_basetrie_.trie.md#private-_formatnode) -* [_lookupNode](_basetrie_.trie.md#_lookupnode) -* [_putNode](_basetrie_.trie.md#_putnode) +* [_lookupNode](_basetrie_.trie.md#private-_lookupnode) +* [_putNode](_basetrie_.trie.md#private-_putnode) * [_saveStack](_basetrie_.trie.md#private-_savestack) * [_updateNode](_basetrie_.trie.md#private-_updatenode) * [_walkTrie](_basetrie_.trie.md#private-_walktrie) @@ -57,6 +57,7 @@ If the db is `null` or left undefined, then the trie will be stored in memory vi * [get](_basetrie_.trie.md#get) * [put](_basetrie_.trie.md#put) * [setRoot](_basetrie_.trie.md#setroot) +* [createProof](_basetrie_.trie.md#static-createproof) * [fromProof](_basetrie_.trie.md#static-fromproof) * [prove](_basetrie_.trie.md#static-prove) * [verifyProof](_basetrie_.trie.md#static-verifyproof) @@ -67,7 +68,7 @@ If the db is `null` or left undefined, then the trie will be stored in memory vi \+ **new Trie**(`db?`: LevelUp | null, `root?`: Buffer): *[Trie](_basetrie_.trie.md)* -*Defined in [baseTrie.ts:43](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L43)* +*Defined in [baseTrie.ts:45](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L45)* **Parameters:** @@ -84,7 +85,7 @@ Name | Type | • **EMPTY_TRIE_ROOT**: *Buffer* -*Defined in [baseTrie.ts:40](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L40)* +*Defined in [baseTrie.ts:42](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L42)* ___ @@ -92,7 +93,7 @@ ___ • **db**: *DB* -*Defined in [baseTrie.ts:41](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L41)* +*Defined in [baseTrie.ts:43](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L43)* ## Accessors @@ -100,13 +101,13 @@ ___ • **get root**(): *Buffer* -*Defined in [baseTrie.ts:101](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L101)* +*Defined in [baseTrie.ts:127](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L127)* **Returns:** *Buffer* • **set root**(`value`: Buffer): *void* -*Defined in [baseTrie.ts:97](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L97)* +*Defined in [baseTrie.ts:123](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L123)* **Parameters:** @@ -118,11 +119,13 @@ Name | Type | ## Methods -### _createInitialNode +### `Private` _createInitialNode ▸ **_createInitialNode**(`key`: Buffer, `value`: Buffer): *Promise‹void›* -*Defined in [baseTrie.ts:659](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L659)* +*Defined in [baseTrie.ts:683](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L683)* + +Creates the initial node from an empty tree. **Parameters:** @@ -135,11 +138,13 @@ Name | Type | ___ -### _deleteNode +### `Private` _deleteNode ▸ **_deleteNode**(`k`: Buffer, `stack`: TrieNode[]): *Promise‹void›* -*Defined in [baseTrie.ts:537](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L537)* +*Defined in [baseTrie.ts:558](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L558)* + +Deletes a node. **Parameters:** @@ -156,7 +161,7 @@ ___ ▸ **_findDbNodes**(`onFound`: FoundNode): *Promise‹void›* -*Defined in [baseTrie.ts:280](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L280)* +*Defined in [baseTrie.ts:302](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L302)* **Parameters:** @@ -168,11 +173,13 @@ Name | Type | ___ -### _findValueNodes +### `Private` _findValueNodes ▸ **_findValueNodes**(`onFound`: FoundNode): *Promise‹void›* -*Defined in [baseTrie.ts:258](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L258)* +*Defined in [baseTrie.ts:280](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L280)* + +Finds all nodes that store k,v values. **Parameters:** @@ -188,32 +195,32 @@ ___ ▸ **_formatNode**(`node`: TrieNode, `topLevel`: boolean, `opStack`: BatchDBOp[], `remove`: boolean): *Buffer | null | Buffer‹› | Buffer‹›[][]* -*Defined in [baseTrie.ts:675](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L675)* +*Defined in [baseTrie.ts:698](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L698)* -Formats node to be saved by levelup.batch. - -**`method`** _formatNode +Formats node to be saved by `levelup.batch`. **Parameters:** Name | Type | Default | Description | ------ | ------ | ------ | ------ | -`node` | TrieNode | - | the node to format | -`topLevel` | boolean | - | if the node is at the top level | -`opStack` | BatchDBOp[] | - | the opStack to push the node's data | -`remove` | boolean | false | whether to remove the node (only used for CheckpointTrie) | +`node` | TrieNode | - | the node to format. | +`topLevel` | boolean | - | if the node is at the top level. | +`opStack` | BatchDBOp[] | - | the opStack to push the node's data. | +`remove` | boolean | false | whether to remove the node (only used for CheckpointTrie). | **Returns:** *Buffer | null | Buffer‹› | Buffer‹›[][]* -- the node's hash used as the key or the rawNode +The node's hash used as the key or the rawNode. ___ -### _lookupNode +### `Private` _lookupNode ▸ **_lookupNode**(`node`: Buffer | Buffer[]): *Promise‹TrieNode | null›* -*Defined in [baseTrie.ts:173](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L173)* +*Defined in [baseTrie.ts:194](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L194)* + +Retrieves a node from db by hash. **Parameters:** @@ -225,11 +232,13 @@ Name | Type | ___ -### _putNode +### `Private` _putNode ▸ **_putNode**(`node`: TrieNode): *Promise‹void›* -*Defined in [baseTrie.ts:191](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L191)* +*Defined in [baseTrie.ts:215](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L215)* + +Writes a single node to db. **Parameters:** @@ -245,11 +254,9 @@ ___ ▸ **_saveStack**(`key`: Nibbles, `stack`: TrieNode[], `opStack`: BatchDBOp[]): *Promise‹void›* -*Defined in [baseTrie.ts:508](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L508)* - -saves a stack +*Defined in [baseTrie.ts:525](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L525)* -**`method`** _saveStack +Saves a stack. **Parameters:** @@ -257,7 +264,7 @@ Name | Type | Description | ------ | ------ | ------ | `key` | Nibbles | the key. Should follow the stack | `stack` | TrieNode[] | a stack of nodes to the value given by the key | -`opStack` | BatchDBOp[] | a stack of levelup operations to commit at the end of this funciton | +`opStack` | BatchDBOp[] | a stack of levelup operations to commit at the end of this funciton | **Returns:** *Promise‹void›* @@ -267,20 +274,18 @@ ___ ▸ **_updateNode**(`k`: Buffer, `value`: Buffer, `keyRemainder`: Nibbles, `stack`: TrieNode[]): *Promise‹void›* -*Defined in [baseTrie.ts:300](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L300)* - -Updates a node +*Defined in [baseTrie.ts:320](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L320)* -**`method`** _updateNode +Updates a node. **Parameters:** -Name | Type | ------- | ------ | -`k` | Buffer | -`value` | Buffer | -`keyRemainder` | Nibbles | -`stack` | TrieNode[] | +Name | Type | Description | +------ | ------ | ------ | +`k` | Buffer | - | +`value` | Buffer | - | +`keyRemainder` | Nibbles | - | +`stack` | TrieNode[] | | **Returns:** *Promise‹void›* @@ -290,12 +295,10 @@ ___ ▸ **_walkTrie**(`root`: Buffer, `onNode`: FoundNode): *Promise‹void›* -*Defined in [baseTrie.ts:407](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L407)* +*Defined in [baseTrie.ts:426](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L426)* Walks a trie until finished. -**`method`** _walkTrie - **Parameters:** Name | Type | Description | @@ -305,7 +308,7 @@ Name | Type | Description | **Returns:** *Promise‹void›* -- returns when finished walking trie +Returns when finished walking trie. ___ @@ -313,14 +316,10 @@ ___ ▸ **batch**(`ops`: BatchDBOp[]): *Promise‹void›* -*Defined in [baseTrie.ts:729](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L729)* +*Defined in [baseTrie.ts:748](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L748)* The given hash of operations (key additions or deletions) are executed on the DB -**`method`** batch - -**`memberof`** Trie - **`example`** const ops = [ { type: 'del', key: Buffer.from('father') } @@ -333,9 +332,9 @@ await trie.batch(ops) **Parameters:** -Name | Type | ------- | ------ | -`ops` | BatchDBOp[] | +Name | Type | Description | +------ | ------ | ------ | +`ops` | BatchDBOp[] | | **Returns:** *Promise‹void›* @@ -345,7 +344,7 @@ ___ ▸ **checkRoot**(`root`: Buffer): *Promise‹boolean›* -*Defined in [baseTrie.ts:745](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L745)* +*Defined in [baseTrie.ts:764](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L764)* Checks if a given root exists. @@ -363,7 +362,9 @@ ___ ▸ **copy**(): *[Trie](_basetrie_.trie.md)* -*Defined in [baseTrie.ts:708](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L708)* +*Defined in [baseTrie.ts:730](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L730)* + +Creates a new trie backed by the same db. **Returns:** *[Trie](_basetrie_.trie.md)* @@ -373,17 +374,13 @@ ___ ▸ **createReadStream**(): *ReadStream* -*Defined in [baseTrie.ts:702](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L702)* +*Defined in [baseTrie.ts:723](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L723)* The `data` event is given an `Object` that has two properties; the `key` and the `value`. Both should be Buffers. -**`method`** createReadStream - -**`memberof`** Trie - **Returns:** *ReadStream* -Returns a [stream](https://nodejs.org/dist/latest-v5.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie` +Returns a [stream](https://nodejs.org/dist/latest-v12.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie` ___ @@ -391,19 +388,15 @@ ___ ▸ **del**(`key`: Buffer): *Promise‹void›* -*Defined in [baseTrie.ts:163](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L163)* +*Defined in [baseTrie.ts:181](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L181)* -deletes a value given a `key` - -**`method`** del - -**`memberof`** Trie +Deletes a value given a `key`. **Parameters:** -Name | Type | ------- | ------ | -`key` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`key` | Buffer | | **Returns:** *Promise‹void›* @@ -413,20 +406,16 @@ ___ ▸ **findPath**(`key`: Buffer): *Promise‹Path›* -*Defined in [baseTrie.ts:205](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L205)* +*Defined in [baseTrie.ts:226](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L226)* Tries to find a path to the node for the given key. It returns a `stack` of nodes to the closet node. -**`method`** findPath - -**`memberof`** Trie - **Parameters:** Name | Type | Description | ------ | ------ | ------ | -`key` | Buffer | the search key | +`key` | Buffer | the search key | **Returns:** *Promise‹Path›* @@ -436,14 +425,10 @@ ___ ▸ **get**(`key`: Buffer): *Promise‹Buffer | null›* -*Defined in [baseTrie.ts:120](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L120)* +*Defined in [baseTrie.ts:144](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L144)* Gets a value given a `key` -**`method`** get - -**`memberof`** Trie - **Parameters:** Name | Type | Description | @@ -452,7 +437,7 @@ Name | Type | Description | **Returns:** *Promise‹Buffer | null›* -- Returns a promise that resolves to `Buffer` if a value was found or `null` if no value was found. +A Promise that resolves to `Buffer` if a value was found or `null` if no value was found. ___ @@ -460,20 +445,16 @@ ___ ▸ **put**(`key`: Buffer, `value`: Buffer): *Promise‹void›* -*Defined in [baseTrie.ts:137](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L137)* - -Stores a given `value` at the given `key` +*Defined in [baseTrie.ts:158](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L158)* -**`method`** put - -**`memberof`** Trie +Stores a given `value` at the given `key`. **Parameters:** -Name | Type | ------- | ------ | -`key` | Buffer | -`value` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`key` | Buffer | - | +`value` | Buffer | | **Returns:** *Promise‹void›* @@ -483,7 +464,7 @@ ___ ▸ **setRoot**(`value?`: Buffer): *void* -*Defined in [baseTrie.ts:105](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L105)* +*Defined in [baseTrie.ts:131](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L131)* **Parameters:** @@ -495,18 +476,39 @@ Name | Type | ___ +### `Static` createProof + +▸ **createProof**(`trie`: [Trie](_basetrie_.trie.md), `key`: Buffer): *Promise‹[Proof](../modules/_basetrie_.md#proof)›* + +*Defined in [baseTrie.ts:97](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L97)* + +Creates a proof from a trie and key that can be verified using [Trie.verifyProof](_basetrie_.trie.md#static-verifyproof). + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`trie` | [Trie](_basetrie_.trie.md) | - | +`key` | Buffer | | + +**Returns:** *Promise‹[Proof](../modules/_basetrie_.md#proof)›* + +___ + ### `Static` fromProof -▸ **fromProof**(`proofNodes`: Buffer[], `proofTrie?`: [Trie](_basetrie_.trie.md)): *Promise‹[Trie](_basetrie_.trie.md)›* +▸ **fromProof**(`proof`: [Proof](../modules/_basetrie_.md#proof), `trie?`: [Trie](_basetrie_.trie.md)): *Promise‹[Trie](_basetrie_.trie.md)›* + +*Defined in [baseTrie.ts:62](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L62)* -*Defined in [baseTrie.ts:55](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L55)* +Saves the nodes from a proof into the trie. If no trie is provided a new one wil be instantiated. **Parameters:** -Name | Type | ------- | ------ | -`proofNodes` | Buffer[] | -`proofTrie?` | [Trie](_basetrie_.trie.md) | +Name | Type | Description | +------ | ------ | ------ | +`proof` | [Proof](../modules/_basetrie_.md#proof) | - | +`trie?` | [Trie](_basetrie_.trie.md) | | **Returns:** *Promise‹[Trie](_basetrie_.trie.md)›* @@ -514,26 +516,34 @@ ___ ### `Static` prove -▸ **prove**(`trie`: [Trie](_basetrie_.trie.md), `key`: Buffer): *Promise‹Buffer[]›* +▸ **prove**(`trie`: [Trie](_basetrie_.trie.md), `key`: Buffer): *Promise‹[Proof](../modules/_basetrie_.md#proof)›* + +*Defined in [baseTrie.ts:88](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L88)* -*Defined in [baseTrie.ts:75](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L75)* +prove has been renamed to [Trie.createProof](_basetrie_.trie.md#static-createproof). + +**`deprecated`** **Parameters:** -Name | Type | ------- | ------ | -`trie` | [Trie](_basetrie_.trie.md) | -`key` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`trie` | [Trie](_basetrie_.trie.md) | - | +`key` | Buffer | | -**Returns:** *Promise‹Buffer[]›* +**Returns:** *Promise‹[Proof](../modules/_basetrie_.md#proof)›* ___ ### `Static` verifyProof -▸ **verifyProof**(`rootHash`: Buffer, `key`: Buffer, `proofNodes`: Buffer[]): *Promise‹Buffer | null›* +▸ **verifyProof**(`rootHash`: Buffer, `key`: Buffer, `proof`: [Proof](../modules/_basetrie_.md#proof)): *Promise‹Buffer | null›* + +*Defined in [baseTrie.ts:113](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L113)* -*Defined in [baseTrie.ts:83](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L83)* +Verifies a proof. + +**`throws`** If proof is found to be invalid. **Parameters:** @@ -541,6 +551,8 @@ Name | Type | ------ | ------ | `rootHash` | Buffer | `key` | Buffer | -`proofNodes` | Buffer[] | +`proof` | [Proof](../modules/_basetrie_.md#proof) | **Returns:** *Promise‹Buffer | null›* + +The value from the key. diff --git a/docs/classes/_checkpointtrie_.checkpointtrie.md b/docs/classes/_checkpointtrie_.checkpointtrie.md index a2f7e5e..09b404f 100644 --- a/docs/classes/_checkpointtrie_.checkpointtrie.md +++ b/docs/classes/_checkpointtrie_.checkpointtrie.md @@ -31,16 +31,16 @@ ### Methods -* [_createInitialNode](_checkpointtrie_.checkpointtrie.md#_createinitialnode) +* [_createInitialNode](_checkpointtrie_.checkpointtrie.md#private-_createinitialnode) * [_createScratchReadStream](_checkpointtrie_.checkpointtrie.md#private-_createscratchreadstream) -* [_deleteNode](_checkpointtrie_.checkpointtrie.md#_deletenode) +* [_deleteNode](_checkpointtrie_.checkpointtrie.md#private-_deletenode) * [_enterCpMode](_checkpointtrie_.checkpointtrie.md#private-_entercpmode) * [_exitCpMode](_checkpointtrie_.checkpointtrie.md#private-_exitcpmode) * [_findDbNodes](_checkpointtrie_.checkpointtrie.md#_finddbnodes) -* [_findValueNodes](_checkpointtrie_.checkpointtrie.md#_findvaluenodes) +* [_findValueNodes](_checkpointtrie_.checkpointtrie.md#private-_findvaluenodes) * [_formatNode](_checkpointtrie_.checkpointtrie.md#private-_formatnode) -* [_lookupNode](_checkpointtrie_.checkpointtrie.md#_lookupnode) -* [_putNode](_checkpointtrie_.checkpointtrie.md#_putnode) +* [_lookupNode](_checkpointtrie_.checkpointtrie.md#private-_lookupnode) +* [_putNode](_checkpointtrie_.checkpointtrie.md#private-_putnode) * [_saveStack](_checkpointtrie_.checkpointtrie.md#private-_savestack) * [_updateNode](_checkpointtrie_.checkpointtrie.md#private-_updatenode) * [_walkTrie](_checkpointtrie_.checkpointtrie.md#private-_walktrie) @@ -56,6 +56,7 @@ * [put](_checkpointtrie_.checkpointtrie.md#put) * [revert](_checkpointtrie_.checkpointtrie.md#revert) * [setRoot](_checkpointtrie_.checkpointtrie.md#setroot) +* [createProof](_checkpointtrie_.checkpointtrie.md#static-createproof) * [fromProof](_checkpointtrie_.checkpointtrie.md#static-fromproof) * [prove](_checkpointtrie_.checkpointtrie.md#static-prove) * [verifyProof](_checkpointtrie_.checkpointtrie.md#static-verifyproof) @@ -86,7 +87,7 @@ Name | Type | *Inherited from [Trie](_basetrie_.trie.md).[EMPTY_TRIE_ROOT](_basetrie_.trie.md#empty_trie_root)* -*Defined in [baseTrie.ts:40](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L40)* +*Defined in [baseTrie.ts:42](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L42)* ___ @@ -120,7 +121,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[db](_basetrie_.trie.md#db)* -*Defined in [baseTrie.ts:41](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L41)* +*Defined in [baseTrie.ts:43](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L43)* ## Accessors @@ -142,7 +143,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[root](_basetrie_.trie.md#root)* -*Defined in [baseTrie.ts:101](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L101)* +*Defined in [baseTrie.ts:127](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L127)* **Returns:** *Buffer* @@ -150,7 +151,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[root](_basetrie_.trie.md#root)* -*Defined in [baseTrie.ts:97](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L97)* +*Defined in [baseTrie.ts:123](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L123)* **Parameters:** @@ -162,13 +163,15 @@ Name | Type | ## Methods -### _createInitialNode +### `Private` _createInitialNode ▸ **_createInitialNode**(`key`: Buffer, `value`: Buffer): *Promise‹void›* -*Inherited from [Trie](_basetrie_.trie.md).[_createInitialNode](_basetrie_.trie.md#_createinitialnode)* +*Inherited from [Trie](_basetrie_.trie.md).[_createInitialNode](_basetrie_.trie.md#private-_createinitialnode)* + +*Defined in [baseTrie.ts:683](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L683)* -*Defined in [baseTrie.ts:659](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L659)* +Creates the initial node from an empty tree. **Parameters:** @@ -185,13 +188,11 @@ ___ ▸ **_createScratchReadStream**(`scratchDb?`: ScratchDB): *ScratchReadStream‹›* -*Defined in [checkpointTrie.ts:137](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L137)* +*Defined in [checkpointTrie.ts:130](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L130)* Returns a `ScratchReadStream` based on the state updates since checkpoint. -**`method`** createScratchReadStream - **Parameters:** Name | Type | @@ -202,13 +203,15 @@ Name | Type | ___ -### _deleteNode +### `Private` _deleteNode ▸ **_deleteNode**(`k`: Buffer, `stack`: TrieNode[]): *Promise‹void›* -*Inherited from [Trie](_basetrie_.trie.md).[_deleteNode](_basetrie_.trie.md#_deletenode)* +*Inherited from [Trie](_basetrie_.trie.md).[_deleteNode](_basetrie_.trie.md#private-_deletenode)* -*Defined in [baseTrie.ts:537](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L537)* +*Defined in [baseTrie.ts:558](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L558)* + +Deletes a node. **Parameters:** @@ -225,7 +228,7 @@ ___ ▸ **_enterCpMode**(): *void* -*Defined in [checkpointTrie.ts:106](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L106)* +*Defined in [checkpointTrie.ts:100](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L100)* Enter into checkpoint mode. @@ -237,7 +240,7 @@ ___ ▸ **_exitCpMode**(`commitState`: boolean): *Promise‹void›* -*Defined in [checkpointTrie.ts:115](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L115)* +*Defined in [checkpointTrie.ts:109](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L109)* Exit from checkpoint mode. @@ -257,7 +260,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[_findDbNodes](_basetrie_.trie.md#_finddbnodes)* -*Defined in [baseTrie.ts:280](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L280)* +*Defined in [baseTrie.ts:302](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L302)* **Parameters:** @@ -269,13 +272,15 @@ Name | Type | ___ -### _findValueNodes +### `Private` _findValueNodes ▸ **_findValueNodes**(`onFound`: FoundNode): *Promise‹void›* -*Inherited from [Trie](_basetrie_.trie.md).[_findValueNodes](_basetrie_.trie.md#_findvaluenodes)* +*Inherited from [Trie](_basetrie_.trie.md).[_findValueNodes](_basetrie_.trie.md#private-_findvaluenodes)* -*Defined in [baseTrie.ts:258](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L258)* +*Defined in [baseTrie.ts:280](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L280)* + +Finds all nodes that store k,v values. **Parameters:** @@ -293,34 +298,34 @@ ___ *Overrides [Trie](_basetrie_.trie.md).[_formatNode](_basetrie_.trie.md#private-_formatnode)* -*Defined in [checkpointTrie.ts:157](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L157)* - -Formats node to be saved by levelup.batch. +*Defined in [checkpointTrie.ts:149](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L149)* -**`method`** _formatNode +Formats node to be saved by `levelup.batch`. **Parameters:** Name | Type | Default | Description | ------ | ------ | ------ | ------ | -`node` | TrieNode | - | the node to format | -`topLevel` | boolean | - | if the node is at the top level | -`opStack` | BatchDBOp[] | - | the opStack to push the node's data | -`remove` | boolean | false | whether to remove the node (only used for CheckpointTrie) | +`node` | TrieNode | - | the node to format. | +`topLevel` | boolean | - | if the node is at the top level. | +`opStack` | BatchDBOp[] | - | the opStack to push the node's data. | +`remove` | boolean | false | whether to remove the node (only used for CheckpointTrie). | **Returns:** *Buffer‹› | null | Buffer‹› | Buffer‹›[][]* -- the node's hash used as the key or the rawNode +The node's hash used as the key or the rawNode. ___ -### _lookupNode +### `Private` _lookupNode ▸ **_lookupNode**(`node`: Buffer | Buffer[]): *Promise‹TrieNode | null›* -*Inherited from [Trie](_basetrie_.trie.md).[_lookupNode](_basetrie_.trie.md#_lookupnode)* +*Inherited from [Trie](_basetrie_.trie.md).[_lookupNode](_basetrie_.trie.md#private-_lookupnode)* -*Defined in [baseTrie.ts:173](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L173)* +*Defined in [baseTrie.ts:194](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L194)* + +Retrieves a node from db by hash. **Parameters:** @@ -332,13 +337,15 @@ Name | Type | ___ -### _putNode +### `Private` _putNode ▸ **_putNode**(`node`: TrieNode): *Promise‹void›* -*Inherited from [Trie](_basetrie_.trie.md).[_putNode](_basetrie_.trie.md#_putnode)* +*Inherited from [Trie](_basetrie_.trie.md).[_putNode](_basetrie_.trie.md#private-_putnode)* + +*Defined in [baseTrie.ts:215](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L215)* -*Defined in [baseTrie.ts:191](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L191)* +Writes a single node to db. **Parameters:** @@ -356,11 +363,9 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[_saveStack](_basetrie_.trie.md#private-_savestack)* -*Defined in [baseTrie.ts:508](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L508)* +*Defined in [baseTrie.ts:525](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L525)* -saves a stack - -**`method`** _saveStack +Saves a stack. **Parameters:** @@ -368,7 +373,7 @@ Name | Type | Description | ------ | ------ | ------ | `key` | Nibbles | the key. Should follow the stack | `stack` | TrieNode[] | a stack of nodes to the value given by the key | -`opStack` | BatchDBOp[] | a stack of levelup operations to commit at the end of this funciton | +`opStack` | BatchDBOp[] | a stack of levelup operations to commit at the end of this funciton | **Returns:** *Promise‹void›* @@ -380,20 +385,18 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[_updateNode](_basetrie_.trie.md#private-_updatenode)* -*Defined in [baseTrie.ts:300](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L300)* - -Updates a node +*Defined in [baseTrie.ts:320](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L320)* -**`method`** _updateNode +Updates a node. **Parameters:** -Name | Type | ------- | ------ | -`k` | Buffer | -`value` | Buffer | -`keyRemainder` | Nibbles | -`stack` | TrieNode[] | +Name | Type | Description | +------ | ------ | ------ | +`k` | Buffer | - | +`value` | Buffer | - | +`keyRemainder` | Nibbles | - | +`stack` | TrieNode[] | | **Returns:** *Promise‹void›* @@ -405,12 +408,10 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[_walkTrie](_basetrie_.trie.md#private-_walktrie)* -*Defined in [baseTrie.ts:407](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L407)* +*Defined in [baseTrie.ts:426](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L426)* Walks a trie until finished. -**`method`** _walkTrie - **Parameters:** Name | Type | Description | @@ -420,7 +421,7 @@ Name | Type | Description | **Returns:** *Promise‹void›* -- returns when finished walking trie +Returns when finished walking trie. ___ @@ -430,14 +431,10 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[batch](_basetrie_.trie.md#batch)* -*Defined in [baseTrie.ts:729](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L729)* +*Defined in [baseTrie.ts:748](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L748)* The given hash of operations (key additions or deletions) are executed on the DB -**`method`** batch - -**`memberof`** Trie - **`example`** const ops = [ { type: 'del', key: Buffer.from('father') } @@ -450,9 +447,9 @@ await trie.batch(ops) **Parameters:** -Name | Type | ------- | ------ | -`ops` | BatchDBOp[] | +Name | Type | Description | +------ | ------ | ------ | +`ops` | BatchDBOp[] | | **Returns:** *Promise‹void›* @@ -464,7 +461,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[checkRoot](_basetrie_.trie.md#checkroot)* -*Defined in [baseTrie.ts:745](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L745)* +*Defined in [baseTrie.ts:764](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L764)* Checks if a given root exists. @@ -482,12 +479,11 @@ ___ ▸ **checkpoint**(): *void* -*Defined in [checkpointTrie.ts:36](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L36)* +*Defined in [checkpointTrie.ts:35](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L35)* Creates a checkpoint that can later be reverted to or committed. -After this is called, no changes to the trie will be permanently saved -until `commit` is called. Calling `db.put` overrides the checkpointing -mechanism and would directly write to db. +After this is called, no changes to the trie will be permanently saved until `commit` is called. +To override the checkpointing mechanism use `_maindb.put` to write directly write to db. **Returns:** *void* @@ -497,12 +493,10 @@ ___ ▸ **commit**(): *Promise‹void›* -*Defined in [checkpointTrie.ts:53](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L53)* - -Commits a checkpoint to disk, if current checkpoint is not nested. If -nested, only sets the parent checkpoint as current checkpoint. +*Defined in [checkpointTrie.ts:50](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L50)* -**`method`** commit +Commits a checkpoint to disk, if current checkpoint is not nested. +If nested, only sets the parent checkpoint as current checkpoint. **`throws`** If not during a checkpoint phase @@ -516,11 +510,9 @@ ___ *Overrides [Trie](_basetrie_.trie.md).[copy](_basetrie_.trie.md#copy)* -*Defined in [checkpointTrie.ts:91](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L91)* +*Defined in [checkpointTrie.ts:85](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L85)* -Returns a copy of the underlying trie with the interface -of CheckpointTrie. If during a checkpoint, the copy will -contain the checkpointing metadata (incl. reference to the same scratch). +Returns a copy of the underlying trie with the interface of CheckpointTrie. **Parameters:** @@ -538,17 +530,13 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[createReadStream](_basetrie_.trie.md#createreadstream)* -*Defined in [baseTrie.ts:702](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L702)* +*Defined in [baseTrie.ts:723](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L723)* The `data` event is given an `Object` that has two properties; the `key` and the `value`. Both should be Buffers. -**`method`** createReadStream - -**`memberof`** Trie - **Returns:** *ReadStream* -Returns a [stream](https://nodejs.org/dist/latest-v5.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie` +Returns a [stream](https://nodejs.org/dist/latest-v12.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie` ___ @@ -558,19 +546,15 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[del](_basetrie_.trie.md#del)* -*Defined in [baseTrie.ts:163](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L163)* - -deletes a value given a `key` +*Defined in [baseTrie.ts:181](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L181)* -**`method`** del - -**`memberof`** Trie +Deletes a value given a `key`. **Parameters:** -Name | Type | ------- | ------ | -`key` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`key` | Buffer | | **Returns:** *Promise‹void›* @@ -582,20 +566,16 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[findPath](_basetrie_.trie.md#findpath)* -*Defined in [baseTrie.ts:205](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L205)* +*Defined in [baseTrie.ts:226](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L226)* Tries to find a path to the node for the given key. It returns a `stack` of nodes to the closet node. -**`method`** findPath - -**`memberof`** Trie - **Parameters:** Name | Type | Description | ------ | ------ | ------ | -`key` | Buffer | the search key | +`key` | Buffer | the search key | **Returns:** *Promise‹Path›* @@ -607,14 +587,10 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[get](_basetrie_.trie.md#get)* -*Defined in [baseTrie.ts:120](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L120)* +*Defined in [baseTrie.ts:144](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L144)* Gets a value given a `key` -**`method`** get - -**`memberof`** Trie - **Parameters:** Name | Type | Description | @@ -623,7 +599,7 @@ Name | Type | Description | **Returns:** *Promise‹Buffer | null›* -- Returns a promise that resolves to `Buffer` if a value was found or `null` if no value was found. +A Promise that resolves to `Buffer` if a value was found or `null` if no value was found. ___ @@ -633,20 +609,16 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[put](_basetrie_.trie.md#put)* -*Defined in [baseTrie.ts:137](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L137)* - -Stores a given `value` at the given `key` - -**`method`** put +*Defined in [baseTrie.ts:158](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L158)* -**`memberof`** Trie +Stores a given `value` at the given `key`. **Parameters:** -Name | Type | ------- | ------ | -`key` | Buffer | -`value` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`key` | Buffer | - | +`value` | Buffer | | **Returns:** *Promise‹void›* @@ -656,7 +628,7 @@ ___ ▸ **revert**(): *Promise‹void›* -*Defined in [checkpointTrie.ts:73](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L73)* +*Defined in [checkpointTrie.ts:70](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L70)* Reverts the trie to the state it was at when `checkpoint` was first called. If during a nested checkpoint, sets root to most recent checkpoint, and sets @@ -672,7 +644,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[setRoot](_basetrie_.trie.md#setroot)* -*Defined in [baseTrie.ts:105](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L105)* +*Defined in [baseTrie.ts:131](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L131)* **Parameters:** @@ -684,20 +656,43 @@ Name | Type | ___ +### `Static` createProof + +▸ **createProof**(`trie`: [Trie](_basetrie_.trie.md), `key`: Buffer): *Promise‹[Proof](../modules/_basetrie_.md#proof)›* + +*Inherited from [Trie](_basetrie_.trie.md).[createProof](_basetrie_.trie.md#static-createproof)* + +*Defined in [baseTrie.ts:97](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L97)* + +Creates a proof from a trie and key that can be verified using [Trie.verifyProof](_basetrie_.trie.md#static-verifyproof). + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`trie` | [Trie](_basetrie_.trie.md) | - | +`key` | Buffer | | + +**Returns:** *Promise‹[Proof](../modules/_basetrie_.md#proof)›* + +___ + ### `Static` fromProof -▸ **fromProof**(`proofNodes`: Buffer[], `proofTrie?`: [Trie](_basetrie_.trie.md)): *Promise‹[Trie](_basetrie_.trie.md)›* +▸ **fromProof**(`proof`: [Proof](../modules/_basetrie_.md#proof), `trie?`: [Trie](_basetrie_.trie.md)): *Promise‹[Trie](_basetrie_.trie.md)›* *Inherited from [Trie](_basetrie_.trie.md).[fromProof](_basetrie_.trie.md#static-fromproof)* -*Defined in [baseTrie.ts:55](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L55)* +*Defined in [baseTrie.ts:62](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L62)* + +Saves the nodes from a proof into the trie. If no trie is provided a new one wil be instantiated. **Parameters:** -Name | Type | ------- | ------ | -`proofNodes` | Buffer[] | -`proofTrie?` | [Trie](_basetrie_.trie.md) | +Name | Type | Description | +------ | ------ | ------ | +`proof` | [Proof](../modules/_basetrie_.md#proof) | - | +`trie?` | [Trie](_basetrie_.trie.md) | | **Returns:** *Promise‹[Trie](_basetrie_.trie.md)›* @@ -705,30 +700,38 @@ ___ ### `Static` prove -▸ **prove**(`trie`: [Trie](_basetrie_.trie.md), `key`: Buffer): *Promise‹Buffer[]›* +▸ **prove**(`trie`: [Trie](_basetrie_.trie.md), `key`: Buffer): *Promise‹[Proof](../modules/_basetrie_.md#proof)›* *Inherited from [Trie](_basetrie_.trie.md).[prove](_basetrie_.trie.md#static-prove)* -*Defined in [baseTrie.ts:75](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L75)* +*Defined in [baseTrie.ts:88](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L88)* + +prove has been renamed to [Trie.createProof](_basetrie_.trie.md#static-createproof). + +**`deprecated`** **Parameters:** -Name | Type | ------- | ------ | -`trie` | [Trie](_basetrie_.trie.md) | -`key` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`trie` | [Trie](_basetrie_.trie.md) | - | +`key` | Buffer | | -**Returns:** *Promise‹Buffer[]›* +**Returns:** *Promise‹[Proof](../modules/_basetrie_.md#proof)›* ___ ### `Static` verifyProof -▸ **verifyProof**(`rootHash`: Buffer, `key`: Buffer, `proofNodes`: Buffer[]): *Promise‹Buffer | null›* +▸ **verifyProof**(`rootHash`: Buffer, `key`: Buffer, `proof`: [Proof](../modules/_basetrie_.md#proof)): *Promise‹Buffer | null›* *Inherited from [Trie](_basetrie_.trie.md).[verifyProof](_basetrie_.trie.md#static-verifyproof)* -*Defined in [baseTrie.ts:83](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L83)* +*Defined in [baseTrie.ts:113](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L113)* + +Verifies a proof. + +**`throws`** If proof is found to be invalid. **Parameters:** @@ -736,6 +739,8 @@ Name | Type | ------ | ------ | `rootHash` | Buffer | `key` | Buffer | -`proofNodes` | Buffer[] | +`proof` | [Proof](../modules/_basetrie_.md#proof) | **Returns:** *Promise‹Buffer | null›* + +The value from the key. diff --git a/docs/classes/_secure_.securetrie.md b/docs/classes/_secure_.securetrie.md index d96a0d3..e5bb1ab 100644 --- a/docs/classes/_secure_.securetrie.md +++ b/docs/classes/_secure_.securetrie.md @@ -3,7 +3,7 @@ # Class: SecureTrie You can create a secure Trie where the keys are automatically hashed -using **keccak256** by using `require('merkle-patricia-tree/secure')`. +using **keccak256** by using `require('merkle-patricia-tree').SecureTrie`. It has the same methods and constructor as `Trie`. **`class`** SecureTrie @@ -37,16 +37,16 @@ It has the same methods and constructor as `Trie`. ### Methods -* [_createInitialNode](_secure_.securetrie.md#_createinitialnode) +* [_createInitialNode](_secure_.securetrie.md#private-_createinitialnode) * [_createScratchReadStream](_secure_.securetrie.md#private-_createscratchreadstream) -* [_deleteNode](_secure_.securetrie.md#_deletenode) +* [_deleteNode](_secure_.securetrie.md#private-_deletenode) * [_enterCpMode](_secure_.securetrie.md#private-_entercpmode) * [_exitCpMode](_secure_.securetrie.md#private-_exitcpmode) * [_findDbNodes](_secure_.securetrie.md#_finddbnodes) -* [_findValueNodes](_secure_.securetrie.md#_findvaluenodes) +* [_findValueNodes](_secure_.securetrie.md#private-_findvaluenodes) * [_formatNode](_secure_.securetrie.md#private-_formatnode) -* [_lookupNode](_secure_.securetrie.md#_lookupnode) -* [_putNode](_secure_.securetrie.md#_putnode) +* [_lookupNode](_secure_.securetrie.md#private-_lookupnode) +* [_putNode](_secure_.securetrie.md#private-_putnode) * [_saveStack](_secure_.securetrie.md#private-_savestack) * [_updateNode](_secure_.securetrie.md#private-_updatenode) * [_walkTrie](_secure_.securetrie.md#private-_walktrie) @@ -62,6 +62,7 @@ It has the same methods and constructor as `Trie`. * [put](_secure_.securetrie.md#put) * [revert](_secure_.securetrie.md#revert) * [setRoot](_secure_.securetrie.md#setroot) +* [createProof](_secure_.securetrie.md#static-createproof) * [fromProof](_secure_.securetrie.md#static-fromproof) * [prove](_secure_.securetrie.md#static-prove) * [verifyProof](_secure_.securetrie.md#static-verifyproof) @@ -74,7 +75,7 @@ It has the same methods and constructor as `Trie`. *Overrides [CheckpointTrie](_checkpointtrie_.checkpointtrie.md).[constructor](_checkpointtrie_.checkpointtrie.md#constructor)* -*Defined in [secure.ts:12](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L12)* +*Defined in [secure.ts:13](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L13)* **Parameters:** @@ -92,7 +93,7 @@ Name | Type | *Inherited from [Trie](_basetrie_.trie.md).[EMPTY_TRIE_ROOT](_basetrie_.trie.md#empty_trie_root)* -*Defined in [baseTrie.ts:40](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L40)* +*Defined in [baseTrie.ts:42](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L42)* ___ @@ -132,7 +133,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[db](_basetrie_.trie.md#db)* -*Defined in [baseTrie.ts:41](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L41)* +*Defined in [baseTrie.ts:43](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L43)* ## Accessors @@ -156,7 +157,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[root](_basetrie_.trie.md#root)* -*Defined in [baseTrie.ts:101](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L101)* +*Defined in [baseTrie.ts:127](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L127)* **Returns:** *Buffer* @@ -164,7 +165,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[root](_basetrie_.trie.md#root)* -*Defined in [baseTrie.ts:97](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L97)* +*Defined in [baseTrie.ts:123](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L123)* **Parameters:** @@ -176,13 +177,15 @@ Name | Type | ## Methods -### _createInitialNode +### `Private` _createInitialNode ▸ **_createInitialNode**(`key`: Buffer, `value`: Buffer): *Promise‹void›* -*Inherited from [Trie](_basetrie_.trie.md).[_createInitialNode](_basetrie_.trie.md#_createinitialnode)* +*Inherited from [Trie](_basetrie_.trie.md).[_createInitialNode](_basetrie_.trie.md#private-_createinitialnode)* -*Defined in [baseTrie.ts:659](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L659)* +*Defined in [baseTrie.ts:683](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L683)* + +Creates the initial node from an empty tree. **Parameters:** @@ -201,13 +204,11 @@ ___ *Inherited from [CheckpointTrie](_checkpointtrie_.checkpointtrie.md).[_createScratchReadStream](_checkpointtrie_.checkpointtrie.md#private-_createscratchreadstream)* -*Defined in [checkpointTrie.ts:137](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L137)* +*Defined in [checkpointTrie.ts:130](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L130)* Returns a `ScratchReadStream` based on the state updates since checkpoint. -**`method`** createScratchReadStream - **Parameters:** Name | Type | @@ -218,13 +219,15 @@ Name | Type | ___ -### _deleteNode +### `Private` _deleteNode ▸ **_deleteNode**(`k`: Buffer, `stack`: TrieNode[]): *Promise‹void›* -*Inherited from [Trie](_basetrie_.trie.md).[_deleteNode](_basetrie_.trie.md#_deletenode)* +*Inherited from [Trie](_basetrie_.trie.md).[_deleteNode](_basetrie_.trie.md#private-_deletenode)* + +*Defined in [baseTrie.ts:558](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L558)* -*Defined in [baseTrie.ts:537](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L537)* +Deletes a node. **Parameters:** @@ -243,7 +246,7 @@ ___ *Inherited from [CheckpointTrie](_checkpointtrie_.checkpointtrie.md).[_enterCpMode](_checkpointtrie_.checkpointtrie.md#private-_entercpmode)* -*Defined in [checkpointTrie.ts:106](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L106)* +*Defined in [checkpointTrie.ts:100](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L100)* Enter into checkpoint mode. @@ -257,7 +260,7 @@ ___ *Inherited from [CheckpointTrie](_checkpointtrie_.checkpointtrie.md).[_exitCpMode](_checkpointtrie_.checkpointtrie.md#private-_exitcpmode)* -*Defined in [checkpointTrie.ts:115](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L115)* +*Defined in [checkpointTrie.ts:109](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L109)* Exit from checkpoint mode. @@ -277,7 +280,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[_findDbNodes](_basetrie_.trie.md#_finddbnodes)* -*Defined in [baseTrie.ts:280](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L280)* +*Defined in [baseTrie.ts:302](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L302)* **Parameters:** @@ -289,13 +292,15 @@ Name | Type | ___ -### _findValueNodes +### `Private` _findValueNodes ▸ **_findValueNodes**(`onFound`: FoundNode): *Promise‹void›* -*Inherited from [Trie](_basetrie_.trie.md).[_findValueNodes](_basetrie_.trie.md#_findvaluenodes)* +*Inherited from [Trie](_basetrie_.trie.md).[_findValueNodes](_basetrie_.trie.md#private-_findvaluenodes)* + +*Defined in [baseTrie.ts:280](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L280)* -*Defined in [baseTrie.ts:258](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L258)* +Finds all nodes that store k,v values. **Parameters:** @@ -315,34 +320,34 @@ ___ *Overrides [Trie](_basetrie_.trie.md).[_formatNode](_basetrie_.trie.md#private-_formatnode)* -*Defined in [checkpointTrie.ts:157](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L157)* - -Formats node to be saved by levelup.batch. +*Defined in [checkpointTrie.ts:149](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L149)* -**`method`** _formatNode +Formats node to be saved by `levelup.batch`. **Parameters:** Name | Type | Default | Description | ------ | ------ | ------ | ------ | -`node` | TrieNode | - | the node to format | -`topLevel` | boolean | - | if the node is at the top level | -`opStack` | BatchDBOp[] | - | the opStack to push the node's data | -`remove` | boolean | false | whether to remove the node (only used for CheckpointTrie) | +`node` | TrieNode | - | the node to format. | +`topLevel` | boolean | - | if the node is at the top level. | +`opStack` | BatchDBOp[] | - | the opStack to push the node's data. | +`remove` | boolean | false | whether to remove the node (only used for CheckpointTrie). | **Returns:** *Buffer‹› | null | Buffer‹› | Buffer‹›[][]* -- the node's hash used as the key or the rawNode +The node's hash used as the key or the rawNode. ___ -### _lookupNode +### `Private` _lookupNode ▸ **_lookupNode**(`node`: Buffer | Buffer[]): *Promise‹TrieNode | null›* -*Inherited from [Trie](_basetrie_.trie.md).[_lookupNode](_basetrie_.trie.md#_lookupnode)* +*Inherited from [Trie](_basetrie_.trie.md).[_lookupNode](_basetrie_.trie.md#private-_lookupnode)* + +*Defined in [baseTrie.ts:194](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L194)* -*Defined in [baseTrie.ts:173](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L173)* +Retrieves a node from db by hash. **Parameters:** @@ -354,13 +359,15 @@ Name | Type | ___ -### _putNode +### `Private` _putNode ▸ **_putNode**(`node`: TrieNode): *Promise‹void›* -*Inherited from [Trie](_basetrie_.trie.md).[_putNode](_basetrie_.trie.md#_putnode)* +*Inherited from [Trie](_basetrie_.trie.md).[_putNode](_basetrie_.trie.md#private-_putnode)* -*Defined in [baseTrie.ts:191](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L191)* +*Defined in [baseTrie.ts:215](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L215)* + +Writes a single node to db. **Parameters:** @@ -378,11 +385,9 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[_saveStack](_basetrie_.trie.md#private-_savestack)* -*Defined in [baseTrie.ts:508](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L508)* - -saves a stack +*Defined in [baseTrie.ts:525](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L525)* -**`method`** _saveStack +Saves a stack. **Parameters:** @@ -390,7 +395,7 @@ Name | Type | Description | ------ | ------ | ------ | `key` | Nibbles | the key. Should follow the stack | `stack` | TrieNode[] | a stack of nodes to the value given by the key | -`opStack` | BatchDBOp[] | a stack of levelup operations to commit at the end of this funciton | +`opStack` | BatchDBOp[] | a stack of levelup operations to commit at the end of this funciton | **Returns:** *Promise‹void›* @@ -402,20 +407,18 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[_updateNode](_basetrie_.trie.md#private-_updatenode)* -*Defined in [baseTrie.ts:300](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L300)* +*Defined in [baseTrie.ts:320](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L320)* -Updates a node - -**`method`** _updateNode +Updates a node. **Parameters:** -Name | Type | ------- | ------ | -`k` | Buffer | -`value` | Buffer | -`keyRemainder` | Nibbles | -`stack` | TrieNode[] | +Name | Type | Description | +------ | ------ | ------ | +`k` | Buffer | - | +`value` | Buffer | - | +`keyRemainder` | Nibbles | - | +`stack` | TrieNode[] | | **Returns:** *Promise‹void›* @@ -427,12 +430,10 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[_walkTrie](_basetrie_.trie.md#private-_walktrie)* -*Defined in [baseTrie.ts:407](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L407)* +*Defined in [baseTrie.ts:426](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L426)* Walks a trie until finished. -**`method`** _walkTrie - **Parameters:** Name | Type | Description | @@ -442,7 +443,7 @@ Name | Type | Description | **Returns:** *Promise‹void›* -- returns when finished walking trie +Returns when finished walking trie. ___ @@ -452,14 +453,10 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[batch](_basetrie_.trie.md#batch)* -*Defined in [baseTrie.ts:729](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L729)* +*Defined in [baseTrie.ts:748](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L748)* The given hash of operations (key additions or deletions) are executed on the DB -**`method`** batch - -**`memberof`** Trie - **`example`** const ops = [ { type: 'del', key: Buffer.from('father') } @@ -472,9 +469,9 @@ await trie.batch(ops) **Parameters:** -Name | Type | ------- | ------ | -`ops` | BatchDBOp[] | +Name | Type | Description | +------ | ------ | ------ | +`ops` | BatchDBOp[] | | **Returns:** *Promise‹void›* @@ -486,7 +483,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[checkRoot](_basetrie_.trie.md#checkroot)* -*Defined in [baseTrie.ts:745](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L745)* +*Defined in [baseTrie.ts:764](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L764)* Checks if a given root exists. @@ -506,12 +503,11 @@ ___ *Inherited from [CheckpointTrie](_checkpointtrie_.checkpointtrie.md).[checkpoint](_checkpointtrie_.checkpointtrie.md#checkpoint)* -*Defined in [checkpointTrie.ts:36](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L36)* +*Defined in [checkpointTrie.ts:35](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L35)* Creates a checkpoint that can later be reverted to or committed. -After this is called, no changes to the trie will be permanently saved -until `commit` is called. Calling `db.put` overrides the checkpointing -mechanism and would directly write to db. +After this is called, no changes to the trie will be permanently saved until `commit` is called. +To override the checkpointing mechanism use `_maindb.put` to write directly write to db. **Returns:** *void* @@ -523,12 +519,10 @@ ___ *Inherited from [CheckpointTrie](_checkpointtrie_.checkpointtrie.md).[commit](_checkpointtrie_.checkpointtrie.md#commit)* -*Defined in [checkpointTrie.ts:53](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L53)* +*Defined in [checkpointTrie.ts:50](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L50)* -Commits a checkpoint to disk, if current checkpoint is not nested. If -nested, only sets the parent checkpoint as current checkpoint. - -**`method`** commit +Commits a checkpoint to disk, if current checkpoint is not nested. +If nested, only sets the parent checkpoint as current checkpoint. **`throws`** If not during a checkpoint phase @@ -538,11 +532,19 @@ ___ ### copy -▸ **copy**(): *[SecureTrie](_secure_.securetrie.md)* +▸ **copy**(`includeCheckpoints`: boolean): *[SecureTrie](_secure_.securetrie.md)* *Overrides [CheckpointTrie](_checkpointtrie_.checkpointtrie.md).[copy](_checkpointtrie_.checkpointtrie.md#copy)* -*Defined in [secure.ts:27](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L27)* +*Defined in [secure.ts:55](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L55)* + +Returns a copy of the underlying trie with the interface of SecureTrie. + +**Parameters:** + +Name | Type | Default | Description | +------ | ------ | ------ | ------ | +`includeCheckpoints` | boolean | true | If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db. | **Returns:** *[SecureTrie](_secure_.securetrie.md)* @@ -554,17 +556,13 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[createReadStream](_basetrie_.trie.md#createreadstream)* -*Defined in [baseTrie.ts:702](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L702)* +*Defined in [baseTrie.ts:723](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L723)* The `data` event is given an `Object` that has two properties; the `key` and the `value`. Both should be Buffers. -**`method`** createReadStream - -**`memberof`** Trie - **Returns:** *ReadStream* -Returns a [stream](https://nodejs.org/dist/latest-v5.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie` +Returns a [stream](https://nodejs.org/dist/latest-v12.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie` ___ @@ -574,13 +572,15 @@ ___ *Overrides [Trie](_basetrie_.trie.md).[del](_basetrie_.trie.md#del)* -*Defined in [secure.ts:52](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L52)* +*Defined in [secure.ts:91](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L91)* + +Deletes a value given a `key`. **Parameters:** -Name | Type | ------- | ------ | -`key` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`key` | Buffer | | **Returns:** *Promise‹void›* @@ -592,20 +592,16 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[findPath](_basetrie_.trie.md#findpath)* -*Defined in [baseTrie.ts:205](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L205)* +*Defined in [baseTrie.ts:226](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L226)* Tries to find a path to the node for the given key. It returns a `stack` of nodes to the closet node. -**`method`** findPath - -**`memberof`** Trie - **Parameters:** Name | Type | Description | ------ | ------ | ------ | -`key` | Buffer | the search key | +`key` | Buffer | the search key | **Returns:** *Promise‹Path›* @@ -617,16 +613,20 @@ ___ *Overrides [Trie](_basetrie_.trie.md).[get](_basetrie_.trie.md#get)* -*Defined in [secure.ts:33](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L33)* +*Defined in [secure.ts:66](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L66)* + +Gets a value given a `key` **Parameters:** -Name | Type | ------- | ------ | -`key` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`key` | Buffer | the key to search for | **Returns:** *Promise‹Buffer | null›* +A Promise that resolves to `Buffer` if a value was found or `null` if no value was found. + ___ ### put @@ -635,10 +635,10 @@ ___ *Overrides [Trie](_basetrie_.trie.md).[put](_basetrie_.trie.md#put)* -*Defined in [secure.ts:43](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L43)* +*Defined in [secure.ts:78](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L78)* -For a falsey value, use the original key -to avoid double hashing the key. +Stores a given `value` at the given `key`. +For a falsey value, use the original key to avoid double hashing the key. **Parameters:** @@ -657,7 +657,7 @@ ___ *Inherited from [CheckpointTrie](_checkpointtrie_.checkpointtrie.md).[revert](_checkpointtrie_.checkpointtrie.md#revert)* -*Defined in [checkpointTrie.ts:73](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L73)* +*Defined in [checkpointTrie.ts:70](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/checkpointTrie.ts#L70)* Reverts the trie to the state it was at when `checkpoint` was first called. If during a nested checkpoint, sets root to most recent checkpoint, and sets @@ -673,7 +673,7 @@ ___ *Inherited from [Trie](_basetrie_.trie.md).[setRoot](_basetrie_.trie.md#setroot)* -*Defined in [baseTrie.ts:105](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L105)* +*Defined in [baseTrie.ts:131](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L131)* **Parameters:** @@ -685,20 +685,43 @@ Name | Type | ___ +### `Static` createProof + +▸ **createProof**(`trie`: [SecureTrie](_secure_.securetrie.md), `key`: Buffer): *Promise‹[Proof](../modules/_basetrie_.md#proof)›* + +*Overrides [Trie](_basetrie_.trie.md).[createProof](_basetrie_.trie.md#static-createproof)* + +*Defined in [secure.ts:33](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L33)* + +Creates a proof that can be verified using [SecureTrie.verifyProof](_secure_.securetrie.md#static-verifyproof). + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`trie` | [SecureTrie](_secure_.securetrie.md) | - | +`key` | Buffer | | + +**Returns:** *Promise‹[Proof](../modules/_basetrie_.md#proof)›* + +___ + ### `Static` fromProof -▸ **fromProof**(`proofNodes`: Buffer[], `proofTrie?`: [Trie](_basetrie_.trie.md)): *Promise‹[Trie](_basetrie_.trie.md)›* +▸ **fromProof**(`proof`: [Proof](../modules/_basetrie_.md#proof), `trie?`: [Trie](_basetrie_.trie.md)): *Promise‹[Trie](_basetrie_.trie.md)›* *Inherited from [Trie](_basetrie_.trie.md).[fromProof](_basetrie_.trie.md#static-fromproof)* -*Defined in [baseTrie.ts:55](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L55)* +*Defined in [baseTrie.ts:62](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L62)* + +Saves the nodes from a proof into the trie. If no trie is provided a new one wil be instantiated. **Parameters:** -Name | Type | ------- | ------ | -`proofNodes` | Buffer[] | -`proofTrie?` | [Trie](_basetrie_.trie.md) | +Name | Type | Description | +------ | ------ | ------ | +`proof` | [Proof](../modules/_basetrie_.md#proof) | - | +`trie?` | [Trie](_basetrie_.trie.md) | | **Returns:** *Promise‹[Trie](_basetrie_.trie.md)›* @@ -706,30 +729,38 @@ ___ ### `Static` prove -▸ **prove**(`trie`: [SecureTrie](_secure_.securetrie.md), `key`: Buffer): *Promise‹Buffer[]›* +▸ **prove**(`trie`: [SecureTrie](_secure_.securetrie.md), `key`: Buffer): *Promise‹[Proof](../modules/_basetrie_.md#proof)›* *Overrides [Trie](_basetrie_.trie.md).[prove](_basetrie_.trie.md#static-prove)* -*Defined in [secure.ts:17](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L17)* +*Defined in [secure.ts:24](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L24)* + +prove has been renamed to [SecureTrie.createProof](_secure_.securetrie.md#static-createproof). + +**`deprecated`** **Parameters:** -Name | Type | ------- | ------ | -`trie` | [SecureTrie](_secure_.securetrie.md) | -`key` | Buffer | +Name | Type | Description | +------ | ------ | ------ | +`trie` | [SecureTrie](_secure_.securetrie.md) | - | +`key` | Buffer | | -**Returns:** *Promise‹Buffer[]›* +**Returns:** *Promise‹[Proof](../modules/_basetrie_.md#proof)›* ___ ### `Static` verifyProof -▸ **verifyProof**(`rootHash`: Buffer, `key`: Buffer, `proof`: Buffer[]): *Promise‹Buffer | null›* +▸ **verifyProof**(`rootHash`: Buffer, `key`: Buffer, `proof`: [Proof](../modules/_basetrie_.md#proof)): *Promise‹Buffer | null›* *Overrides [Trie](_basetrie_.trie.md).[verifyProof](_basetrie_.trie.md#static-verifyproof)* -*Defined in [secure.ts:22](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L22)* +*Defined in [secure.ts:46](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/secure.ts#L46)* + +Verifies a proof. + +**`throws`** If proof is found to be invalid. **Parameters:** @@ -737,6 +768,8 @@ Name | Type | ------ | ------ | `rootHash` | Buffer | `key` | Buffer | -`proof` | Buffer[] | +`proof` | [Proof](../modules/_basetrie_.md#proof) | **Returns:** *Promise‹Buffer | null›* + +The value from the key. diff --git a/docs/modules/_basetrie_.md b/docs/modules/_basetrie_.md index dcd7e84..5384aa8 100644 --- a/docs/modules/_basetrie_.md +++ b/docs/modules/_basetrie_.md @@ -7,3 +7,15 @@ ### Classes * [Trie](../classes/_basetrie_.trie.md) + +### Type aliases + +* [Proof](_basetrie_.md#proof) + +## Type aliases + +### Proof + +Ƭ **Proof**: *Buffer[]* + +*Defined in [baseTrie.ts:29](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L29)* diff --git a/package.json b/package.json index bb910cb..a273d01 100644 --- a/package.json +++ b/package.json @@ -76,7 +76,7 @@ "ts-node": "^8.8.1", "tslint": "^5.18.0", "typedoc": "next", - "typedoc-plugin-markdown": "^2.2.16", + "typedoc-plugin-markdown": "^2.2.17", "typescript": "^3.7.5", "typestrict": "^1.0.2" }, diff --git a/src/baseTrie.ts b/src/baseTrie.ts index 5145f39..2c74152 100644 --- a/src/baseTrie.ts +++ b/src/baseTrie.ts @@ -18,6 +18,8 @@ import { } from './trieNode' const assert = require('assert') +export type Proof = Buffer[] + interface Path { node: TrieNode | null remaining: Nibbles @@ -52,8 +54,13 @@ export class Trie { } } - static async fromProof(proofNodes: Buffer[], proofTrie?: Trie): Promise { - let opStack = proofNodes.map((nodeValue) => { + /** + * Saves the nodes from a proof into the trie. If no trie is provided a new one wil be instantiated. + * @param {Proof} proof + * @param {Trie} trie + */ + static async fromProof(proof: Proof, trie?: Trie): Promise { + let opStack = proof.map((nodeValue) => { return { type: 'put', key: keccak(nodeValue), @@ -61,18 +68,33 @@ export class Trie { } as PutBatch }) - if (!proofTrie) { - proofTrie = new Trie() + if (!trie) { + trie = new Trie() if (opStack[0]) { - proofTrie.root = opStack[0].key + trie.root = opStack[0].key } } - await proofTrie.db.batch(opStack) - return proofTrie + await trie.db.batch(opStack) + return trie + } + + /** + * prove has been renamed to [[Trie.createProof]]. + * @deprecated + * @param {Trie} trie + * @param {Buffer} key + */ + static async prove(trie: Trie, key: Buffer): Promise { + return this.createProof(trie, key) } - static async prove(trie: Trie, key: Buffer): Promise { + /** + * Creates a proof from a trie and key that can be verified using [[Trie.verifyProof]]. + * @param {Trie} trie + * @param {Buffer} key + */ + static async createProof(trie: Trie, key: Buffer): Promise { const { stack } = await trie.findPath(key) const p = stack.map((stackElem) => { return stackElem.serialize() @@ -80,14 +102,18 @@ export class Trie { return p } - static async verifyProof( - rootHash: Buffer, - key: Buffer, - proofNodes: Buffer[], - ): Promise { + /** + * Verifies a proof. + * @param {Buffer} rootHash + * @param {Buffer} key + * @param {Proof} proof + * @throws If proof is found to be invalid. + * @returns The value from the key. + */ + static async verifyProof(rootHash: Buffer, key: Buffer, proof: Proof): Promise { let proofTrie = new Trie(null, rootHash) try { - proofTrie = await Trie.fromProof(proofNodes, proofTrie) + proofTrie = await Trie.fromProof(proof, proofTrie) } catch (e) { throw new Error('Invalid proof nodes given') } @@ -112,10 +138,8 @@ export class Trie { /** * Gets a value given a `key` - * @method get - * @memberof Trie * @param {Buffer} key - the key to search for - * @returns {Promise} - Returns a promise that resolves to `Buffer` if a value was found or `null` if no value was found. + * @returns A Promise that resolves to `Buffer` if a value was found or `null` if no value was found. */ async get(key: Buffer): Promise { const { node, remaining } = await this.findPath(key) @@ -127,12 +151,9 @@ export class Trie { } /** - * Stores a given `value` at the given `key` - * @method put - * @memberof Trie + * Stores a given `value` at the given `key`. * @param {Buffer} key * @param {Buffer} value - * @returns {Promise} */ async put(key: Buffer, value: Buffer): Promise { // If value is empty, delete @@ -154,11 +175,8 @@ export class Trie { } /** - * deletes a value given a `key` - * @method del - * @memberof Trie + * Deletes a value given a `key`. * @param {Buffer} key - * @returns {Promise} */ async del(key: Buffer): Promise { await this.lock.wait() @@ -169,7 +187,10 @@ export class Trie { this.lock.signal() } - // retrieves a node from dbs by hash + /** + * Retrieves a node from db by hash. + * @private + */ async _lookupNode(node: Buffer | Buffer[]): Promise { if (isRawNode(node)) { return decodeRawNode(node as Buffer[]) @@ -187,7 +208,10 @@ export class Trie { return foundNode } - // writes a single node to dbs + /** + * Writes a single node to db. + * @private + */ async _putNode(node: TrieNode): Promise { const hash = node.hash() const serialized = node.serialize() @@ -197,10 +221,7 @@ export class Trie { /** * Tries to find a path to the node for the given key. * It returns a `stack` of nodes to the closet node. - * @method findPath - * @memberof Trie * @param {Buffer} key - the search key - * @returns {Promise} */ async findPath(key: Buffer): Promise { return new Promise(async (resolve) => { @@ -252,8 +273,9 @@ export class Trie { }) } - /* - * Finds all nodes that store k,v values + /** + * Finds all nodes that store k,v values. + * @private */ async _findValueNodes(onFound: FoundNode): Promise { await this._walkTrie(this.root, async (nodeRef, node, key, walkController) => { @@ -288,14 +310,12 @@ export class Trie { } /** - * Updates a node - * @method _updateNode + * Updates a node. * @private * @param {Buffer} key * @param {Buffer} value * @param {Nibbles} keyRemainder * @param {TrieNode[]} stack - * @returns {Promise} */ async _updateNode( k: Buffer, @@ -398,11 +418,10 @@ export class Trie { /** * Walks a trie until finished. - * @method _walkTrie * @private * @param {Buffer} root * @param {Function} onNode - callback to call when a node is found - * @returns {Promise} - returns when finished walking trie + * @returns Returns when finished walking trie. */ async _walkTrie(root: Buffer, onNode: FoundNode): Promise { return new Promise(async (resolve) => { @@ -497,13 +516,11 @@ export class Trie { } /** - * saves a stack - * @method _saveStack + * Saves a stack. * @private * @param {Nibbles} key - the key. Should follow the stack * @param {Array} stack - a stack of nodes to the value given by the key * @param {Array} opStack - a stack of levelup operations to commit at the end of this funciton - * @returns {Promise} */ async _saveStack(key: Nibbles, stack: TrieNode[], opStack: BatchDBOp[]): Promise { let lastRoot @@ -534,6 +551,10 @@ export class Trie { await this.db.batch(opStack) } + /** + * Deletes a node. + * @private + */ async _deleteNode(k: Buffer, stack: TrieNode[]): Promise { const processBranchNode = ( key: Nibbles, @@ -655,7 +676,10 @@ export class Trie { } } - // Creates the initial node from an empty tree + /** + * Creates the initial node from an empty tree. + * @private + */ async _createInitialNode(key: Buffer, value: Buffer): Promise { const newNode = new LeafNode(bufferToNibbles(key), value) this.root = newNode.hash() @@ -663,14 +687,13 @@ export class Trie { } /** - * Formats node to be saved by levelup.batch. - * @method _formatNode + * Formats node to be saved by `levelup.batch`. * @private - * @param {TrieNode} node - the node to format - * @param {Boolean} topLevel - if the node is at the top level - * @param {BatchDBOp[]} opStack - the opStack to push the node's data - * @param {Boolean} remove - whether to remove the node (only used for CheckpointTrie) - * @returns {Buffer | (EmbeddedNode | null)[]} - the node's hash used as the key or the rawNode + * @param {TrieNode} node - the node to format. + * @param {Boolean} topLevel - if the node is at the top level. + * @param {BatchDBOp[]} opStack - the opStack to push the node's data. + * @param {Boolean} remove - whether to remove the node (only used for CheckpointTrie). + * @returns The node's hash used as the key or the rawNode. */ _formatNode( node: TrieNode, @@ -695,16 +718,15 @@ export class Trie { /** * The `data` event is given an `Object` that has two properties; the `key` and the `value`. Both should be Buffers. - * @method createReadStream - * @memberof Trie - * @return {stream.Readable} Returns a [stream](https://nodejs.org/dist/latest-v5.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie` + * @return {stream.Readable} Returns a [stream](https://nodejs.org/dist/latest-v12.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `trie` */ createReadStream(): ReadStream { return new ReadStream(this) } - // creates a new trie backed by the same db - // and starting at the same root + /** + * Creates a new trie backed by the same db. + */ copy(): Trie { const db = this.db.copy() return new Trie(db._leveldb, this.root) @@ -712,8 +734,6 @@ export class Trie { /** * The given hash of operations (key additions or deletions) are executed on the DB - * @method batch - * @memberof Trie * @example * const ops = [ * { type: 'del', key: Buffer.from('father') } @@ -724,7 +744,6 @@ export class Trie { * ] * await trie.batch(ops) * @param {Array} ops - * @returns {Promise} */ async batch(ops: BatchDBOp[]): Promise { for (const op of ops) { diff --git a/src/checkpointTrie.ts b/src/checkpointTrie.ts index 2a63f87..98c2f0b 100644 --- a/src/checkpointTrie.ts +++ b/src/checkpointTrie.ts @@ -43,10 +43,8 @@ export class CheckpointTrie extends BaseTrie { } /** - * Commits a checkpoint to disk, if current checkpoint is not nested. If - * nested, only sets the parent checkpoint as current checkpoint. - * @method commit - * @returns {Promise} + * Commits a checkpoint to disk, if current checkpoint is not nested. + * If nested, only sets the parent checkpoint as current checkpoint. * @throws If not during a checkpoint phase */ async commit(): Promise { @@ -127,7 +125,6 @@ export class CheckpointTrie extends BaseTrie { /** * Returns a `ScratchReadStream` based on the state updates * since checkpoint. - * @method createScratchReadStream * @private */ _createScratchReadStream(scratchDb?: ScratchDB) { @@ -141,14 +138,13 @@ export class CheckpointTrie extends BaseTrie { } /** - * Formats node to be saved by levelup.batch. - * @method _formatNode + * Formats node to be saved by `levelup.batch`. * @private - * @param {TrieNode} node - the node to format - * @param {Boolean} topLevel - if the node is at the top level - * @param {BatchDBOp[]} opStack - the opStack to push the node's data - * @param {Boolean} remove - whether to remove the node (only used for CheckpointTrie) - * @returns {Buffer | (EmbeddedNode | null)[]} - the node's hash used as the key or the rawNode + * @param {TrieNode} node - the node to format. + * @param {Boolean} topLevel - if the node is at the top level. + * @param {BatchDBOp[]} opStack - the opStack to push the node's data. + * @param {Boolean} remove - whether to remove the node (only used for CheckpointTrie). + * @returns The node's hash used as the key or the rawNode. */ _formatNode(node: TrieNode, topLevel: boolean, opStack: BatchDBOp[], remove: boolean = false) { const rlpNode = node.serialize() diff --git a/src/db.ts b/src/db.ts index 659cc32..a233ef2 100644 --- a/src/db.ts +++ b/src/db.ts @@ -33,7 +33,7 @@ export class DB { /** * Retrieves a raw value from leveldb. * @param {Buffer} key - * @returns {Promise} - Promise resolves with `Buffer` if a value is found or `null` if no value is found. + * @returns A Promise that resolves to `Buffer` if a value is found or `null` if no value is found. */ async get(key: Buffer): Promise { let value = null diff --git a/src/secure.ts b/src/secure.ts index cfc4fdc..0af77e6 100644 --- a/src/secure.ts +++ b/src/secure.ts @@ -1,5 +1,6 @@ import { keccak256 } from 'ethereumjs-util' import { CheckpointTrie } from './checkpointTrie' +import { Proof } from './baseTrie' /** * You can create a secure Trie where the keys are automatically hashed @@ -14,12 +15,35 @@ export class SecureTrie extends CheckpointTrie { super(...args) } - static prove(trie: SecureTrie, key: Buffer): Promise { + /** + * prove has been renamed to [[SecureTrie.createProof]]. + * @deprecated + * @param {Trie} trie + * @param {Buffer} key + */ + static async prove(trie: SecureTrie, key: Buffer): Promise { + return this.createProof(trie, key) + } + + /** + * Creates a proof that can be verified using [[SecureTrie.verifyProof]]. + * @param {Trie} trie + * @param {Buffer} key + */ + static createProof(trie: SecureTrie, key: Buffer): Promise { const hash = keccak256(key) - return super.prove(trie, hash) + return super.createProof(trie, hash) } - static async verifyProof(rootHash: Buffer, key: Buffer, proof: Buffer[]): Promise { + /** + * Verifies a proof. + * @param {Buffer} rootHash + * @param {Buffer} key + * @param {Proof} proof + * @throws If proof is found to be invalid. + * @returns The value from the key. + */ + static async verifyProof(rootHash: Buffer, key: Buffer, proof: Proof): Promise { const hash = keccak256(key) return super.verifyProof(rootHash, hash, proof) } @@ -34,6 +58,11 @@ export class SecureTrie extends CheckpointTrie { return new SecureTrie(db._leveldb, this.root) } + /** + * Gets a value given a `key` + * @param {Buffer} key - the key to search for + * @returns A Promise that resolves to `Buffer` if a value was found or `null` if no value was found. + */ async get(key: Buffer): Promise { const hash = keccak256(key) const value = await super.get(hash) @@ -41,8 +70,10 @@ export class SecureTrie extends CheckpointTrie { } /** - * For a falsey value, use the original key - * to avoid double hashing the key. + * Stores a given `value` at the given `key`. + * For a falsey value, use the original key to avoid double hashing the key. + * @param {Buffer} key + * @param {Buffer} value */ async put(key: Buffer, val: Buffer): Promise { if (!val || val.toString() === '') { @@ -53,6 +84,10 @@ export class SecureTrie extends CheckpointTrie { } } + /** + * Deletes a value given a `key`. + * @param {Buffer} key + */ async del(key: Buffer): Promise { const hash = keccak256(key) await super.del(hash) diff --git a/src/util/hex.ts b/src/util/hex.ts index 22b11e1..f64f404 100644 --- a/src/util/hex.ts +++ b/src/util/hex.ts @@ -2,7 +2,6 @@ import { Nibbles } from '../trieNode' /** * Prepends hex prefix to an array of nibbles. - * @method addHexPrefix * @param {Nibbles} key - Array of nibbles * @returns {Nibbles} - returns buffer of encoded data **/ @@ -25,7 +24,6 @@ export function addHexPrefix(key: Nibbles, terminator: boolean): Nibbles { /** * Removes hex prefix of an array of nibbles. - * @method removeHexPrefix * @param {Nibbles} val - Array of nibbles * @private */ @@ -41,7 +39,6 @@ export function removeHexPrefix(val: Nibbles): Nibbles { /** * Returns true if hex-prefixed path is for a terminating (leaf) node. - * @method isTerminator * @param {Nibbles} key - a hex-prefixed array of nibbles * @private */ diff --git a/src/util/nibbles.ts b/src/util/nibbles.ts index ad72a5e..04fb484 100644 --- a/src/util/nibbles.ts +++ b/src/util/nibbles.ts @@ -2,9 +2,8 @@ import { Nibbles } from '../trieNode' /** * Converts a buffer to a nibble array. - * @method bufferToNibbles - * @param {Buffer} key * @private + * @param {Buffer} key */ export function bufferToNibbles(key: Buffer): Nibbles { const bkey = Buffer.from(key) @@ -22,9 +21,8 @@ export function bufferToNibbles(key: Buffer): Nibbles { /** * Converts a nibble array into a buffer. - * @method nibblesToBuffer - * @param {Nibbles} arr - Nibble array * @private + * @param {Nibbles} arr - Nibble array */ export function nibblesToBuffer(arr: Nibbles): Buffer { let buf = Buffer.alloc(arr.length / 2) @@ -37,10 +35,9 @@ export function nibblesToBuffer(arr: Nibbles): Buffer { /** * Returns the number of in order matching nibbles of two give nibble arrays. - * @method matchingNibbleLength + * @private * @param {Nibbles} nib1 * @param {Nibbles} nib2 - * @private */ export function matchingNibbleLength(nib1: Nibbles, nib2: Nibbles): number { let i = 0 diff --git a/test/proof.spec.ts b/test/proof.spec.ts index cc7a32d..ec11c99 100644 --- a/test/proof.spec.ts +++ b/test/proof.spec.ts @@ -11,27 +11,27 @@ tape('simple merkle proofs generation and verification', function (tester) { await trie.put(Buffer.from('key2bb'), Buffer.from('aval2')) await trie.put(Buffer.from('key3cc'), Buffer.from('aval3')) - let proof = await CheckpointTrie.prove(trie, Buffer.from('key2bb')) + let proof = await CheckpointTrie.createProof(trie, Buffer.from('key2bb')) let val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key2bb'), proof) t.equal(val!.toString('utf8'), 'aval2') - proof = await CheckpointTrie.prove(trie, Buffer.from('key1aa')) + proof = await CheckpointTrie.createProof(trie, Buffer.from('key1aa')) val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key1aa'), proof) t.equal(val!.toString('utf8'), '0123456789012345678901234567890123456789xx') - proof = await CheckpointTrie.prove(trie, Buffer.from('key2bb')) + proof = await CheckpointTrie.createProof(trie, Buffer.from('key2bb')) val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key2'), proof) // In this case, the proof _happens_ to contain enough nodes to prove `key2` because // traversing into `key22` would touch all the same nodes as traversing into `key2` t.equal(val, null, 'Expected value at a random key to be null') let myKey = Buffer.from('anyrandomkey') - proof = await CheckpointTrie.prove(trie, myKey) + proof = await CheckpointTrie.createProof(trie, myKey) val = await CheckpointTrie.verifyProof(trie.root, myKey, proof) t.equal(val, null, 'Expected value to be null') myKey = Buffer.from('anothergarbagekey') // should generate a valid proof of null - proof = await CheckpointTrie.prove(trie, myKey) + proof = await CheckpointTrie.createProof(trie, myKey) proof.push(Buffer.from('123456')) // extra nodes are just ignored val = await CheckpointTrie.verifyProof(trie.root, myKey, proof) t.equal(val, null, 'Expected value to be null') @@ -39,7 +39,7 @@ tape('simple merkle proofs generation and verification', function (tester) { await trie.put(Buffer.from('another'), Buffer.from('3498h4riuhgwe')) // to fail our proof we can request a proof for one key - proof = await CheckpointTrie.prove(trie, Buffer.from('another')) + proof = await CheckpointTrie.createProof(trie, Buffer.from('another')) // and use that proof on another key const result = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key1aa'), proof) t.equal(result, null) @@ -51,7 +51,7 @@ tape('simple merkle proofs generation and verification', function (tester) { await trie.put(Buffer.from('key1aa'), Buffer.from('0123456789012345678901234567890123456789xx')) - const proof = await CheckpointTrie.prove(trie, Buffer.from('key1aa')) + const proof = await CheckpointTrie.createProof(trie, Buffer.from('key1aa')) const val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key1aa'), proof) t.equal(val!.toString('utf8'), '0123456789012345678901234567890123456789xx') @@ -63,7 +63,7 @@ tape('simple merkle proofs generation and verification', function (tester) { await trie.put(Buffer.from('key1aa'), Buffer.from('01234')) - const proof = await CheckpointTrie.prove(trie, Buffer.from('key1aa')) + const proof = await CheckpointTrie.createProof(trie, Buffer.from('key1aa')) const val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key1aa'), proof) t.equal(val!.toString('utf8'), '01234') @@ -86,15 +86,15 @@ tape('simple merkle proofs generation and verification', function (tester) { await trie.put(Buffer.from('key3cc'), Buffer.from('aval3')) await trie.put(Buffer.from('key3'), Buffer.from('1234567890123456789012345678901')) - let proof = await CheckpointTrie.prove(trie, Buffer.from('key1')) + let proof = await CheckpointTrie.createProof(trie, Buffer.from('key1')) let val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key1'), proof) t.equal(val!.toString('utf8'), '0123456789012345678901234567890123456789Very_Long') - proof = await CheckpointTrie.prove(trie, Buffer.from('key2')) + proof = await CheckpointTrie.createProof(trie, Buffer.from('key2')) val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key2'), proof) t.equal(val!.toString('utf8'), 'short') - proof = await CheckpointTrie.prove(trie, Buffer.from('key3')) + proof = await CheckpointTrie.createProof(trie, Buffer.from('key3')) val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('key3'), proof) t.equal(val!.toString('utf8'), '1234567890123456789012345678901') @@ -108,15 +108,15 @@ tape('simple merkle proofs generation and verification', function (tester) { await trie.put(Buffer.from('b'), Buffer.from('b')) await trie.put(Buffer.from('c'), Buffer.from('c')) - let proof = await CheckpointTrie.prove(trie, Buffer.from('a')) + let proof = await CheckpointTrie.createProof(trie, Buffer.from('a')) let val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('a'), proof) t.equal(val!.toString('utf8'), 'a') - proof = await CheckpointTrie.prove(trie, Buffer.from('b')) + proof = await CheckpointTrie.createProof(trie, Buffer.from('b')) val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('b'), proof) t.equal(val!.toString('utf8'), 'b') - proof = await CheckpointTrie.prove(trie, Buffer.from('c')) + proof = await CheckpointTrie.createProof(trie, Buffer.from('c')) val = await CheckpointTrie.verifyProof(trie.root, Buffer.from('c'), proof) t.equal(val!.toString('utf8'), 'c') diff --git a/test/secure.spec.ts b/test/secure.spec.ts index 448612d..72b6d2f 100644 --- a/test/secure.spec.ts +++ b/test/secure.spec.ts @@ -25,7 +25,7 @@ tape('SecureTrie', function (t) { const trie = new SecureTrie() await trie.put(Buffer.from('key1aa'), Buffer.from('01234')) - const proof = await SecureTrie.prove(trie, Buffer.from('key1aa')) + const proof = await SecureTrie.createProof(trie, Buffer.from('key1aa')) const val = await SecureTrie.verifyProof(trie.root, Buffer.from('key1aa'), proof) st.equal(val!.toString('utf8'), '01234') st.end() @@ -134,7 +134,7 @@ tape('SecureTrie.copy', function (it) { await trie.put(Buffer.from('key2'), Buffer.from('value2')) const trieCopy = trie.copy() const value = await trieCopy.get(Buffer.from('key2')) - t.equal(value.toString(), 'value2') + t.equal(value!.toString(), 'value2') t.end() }) @@ -146,7 +146,7 @@ tape('SecureTrie.copy', function (it) { await trie.put(Buffer.from('key2'), Buffer.from('value2')) const trieCopy = trie.copy() const value = await trieCopy.get(Buffer.from('key1')) - t.equal(value.toString(), 'value1') + t.equal(value!.toString(), 'value1') t.end() }) }) diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..e88e376 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,5 @@ +{ + "extends": "@ethereumjs/config-tsc", + "include": ["src/**/*.ts", "test/*.spec.ts"] +} + \ No newline at end of file diff --git a/typedoc.json b/typedoc.json index 09d7f85..d89f0db 100644 --- a/typedoc.json +++ b/typedoc.json @@ -5,7 +5,7 @@ "plugin": "typedoc-plugin-markdown", "readme": "none", "gitRevision": "master", - "exclude": "src/**/!(secure|checkpointTrie|baseTrie).ts", + "exclude": ["src/**/!(secure|checkpointTrie|baseTrie).ts", "test/**/*.ts"], "excludeNotExported": true, "excludeExternals": true, "excludePrivate": true, From efe43aa6b2cb6769d9d6801632282fadb47c34ce Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Tue, 16 Jun 2020 22:36:19 -0700 Subject: [PATCH 16/17] Clarify _walkTrie @returns statement --- src/baseTrie.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/baseTrie.ts b/src/baseTrie.ts index 2c74152..425ab32 100644 --- a/src/baseTrie.ts +++ b/src/baseTrie.ts @@ -421,7 +421,7 @@ export class Trie { * @private * @param {Buffer} root * @param {Function} onNode - callback to call when a node is found - * @returns Returns when finished walking trie. + * @returns Resolves when finished walking trie. */ async _walkTrie(root: Buffer, onNode: FoundNode): Promise { return new Promise(async (resolve) => { From 44033e477f1fb9c8898bfa4f179e07ebaddbe006 Mon Sep 17 00:00:00 2001 From: Ryan Ghods Date: Wed, 17 Jun 2020 13:35:22 -0700 Subject: [PATCH 17/17] rebuild docs --- docs/classes/_basetrie_.trie.md | 2 +- docs/classes/_checkpointtrie_.checkpointtrie.md | 2 +- docs/classes/_secure_.securetrie.md | 2 +- docs/modules/_basetrie_.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/classes/_basetrie_.trie.md b/docs/classes/_basetrie_.trie.md index fbf014e..7c13749 100644 --- a/docs/classes/_basetrie_.trie.md +++ b/docs/classes/_basetrie_.trie.md @@ -308,7 +308,7 @@ Name | Type | Description | **Returns:** *Promise‹void›* -Returns when finished walking trie. +Resolves when finished walking trie. ___ diff --git a/docs/classes/_checkpointtrie_.checkpointtrie.md b/docs/classes/_checkpointtrie_.checkpointtrie.md index 09b404f..1eda836 100644 --- a/docs/classes/_checkpointtrie_.checkpointtrie.md +++ b/docs/classes/_checkpointtrie_.checkpointtrie.md @@ -421,7 +421,7 @@ Name | Type | Description | **Returns:** *Promise‹void›* -Returns when finished walking trie. +Resolves when finished walking trie. ___ diff --git a/docs/classes/_secure_.securetrie.md b/docs/classes/_secure_.securetrie.md index e5bb1ab..e827cc3 100644 --- a/docs/classes/_secure_.securetrie.md +++ b/docs/classes/_secure_.securetrie.md @@ -443,7 +443,7 @@ Name | Type | Description | **Returns:** *Promise‹void›* -Returns when finished walking trie. +Resolves when finished walking trie. ___ diff --git a/docs/modules/_basetrie_.md b/docs/modules/_basetrie_.md index 5384aa8..fba7679 100644 --- a/docs/modules/_basetrie_.md +++ b/docs/modules/_basetrie_.md @@ -18,4 +18,4 @@ Ƭ **Proof**: *Buffer[]* -*Defined in [baseTrie.ts:29](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L29)* +*Defined in [baseTrie.ts:21](https://github.com/ethereumjs/merkle-patricia-tree/blob/master/src/baseTrie.ts#L21)*