@aztec-labs/world-state 6.0.0-nightly.20260829

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/README.md +40 -0
  2. package/dest/index.d.ts +6 -0
  3. package/dest/index.d.ts.map +1 -0
  4. package/dest/index.js +5 -0
  5. package/dest/instrumentation/instrumentation.d.ts +25 -0
  6. package/dest/instrumentation/instrumentation.d.ts.map +1 -0
  7. package/dest/instrumentation/instrumentation.js +96 -0
  8. package/dest/native/bench_metrics.d.ts +23 -0
  9. package/dest/native/bench_metrics.d.ts.map +1 -0
  10. package/dest/native/bench_metrics.js +81 -0
  11. package/dest/native/fork_checkpoint.d.ts +16 -0
  12. package/dest/native/fork_checkpoint.d.ts.map +1 -0
  13. package/dest/native/fork_checkpoint.js +38 -0
  14. package/dest/native/index.d.ts +4 -0
  15. package/dest/native/index.d.ts.map +1 -0
  16. package/dest/native/index.js +3 -0
  17. package/dest/native/ipc_world_state_instance.d.ts +91 -0
  18. package/dest/native/ipc_world_state_instance.d.ts.map +1 -0
  19. package/dest/native/ipc_world_state_instance.js +672 -0
  20. package/dest/native/merkle_trees_facade.d.ts +58 -0
  21. package/dest/native/merkle_trees_facade.d.ts.map +1 -0
  22. package/dest/native/merkle_trees_facade.js +250 -0
  23. package/dest/native/message.d.ts +145 -0
  24. package/dest/native/message.d.ts.map +1 -0
  25. package/dest/native/message.js +150 -0
  26. package/dest/native/native_world_state.d.ts +77 -0
  27. package/dest/native/native_world_state.d.ts.map +1 -0
  28. package/dest/native/native_world_state.js +350 -0
  29. package/dest/native/native_world_state_instance.d.ts +63 -0
  30. package/dest/native/native_world_state_instance.d.ts.map +1 -0
  31. package/dest/native/native_world_state_instance.js +1 -0
  32. package/dest/native/world_state_operation.d.ts +7 -0
  33. package/dest/native/world_state_operation.d.ts.map +1 -0
  34. package/dest/native/world_state_operation.js +5 -0
  35. package/dest/synchronizer/config.d.ts +31 -0
  36. package/dest/synchronizer/config.d.ts.map +1 -0
  37. package/dest/synchronizer/config.js +61 -0
  38. package/dest/synchronizer/errors.d.ts +11 -0
  39. package/dest/synchronizer/errors.d.ts.map +1 -0
  40. package/dest/synchronizer/errors.js +12 -0
  41. package/dest/synchronizer/factory.d.ts +20 -0
  42. package/dest/synchronizer/factory.d.ts.map +1 -0
  43. package/dest/synchronizer/factory.js +30 -0
  44. package/dest/synchronizer/index.d.ts +4 -0
  45. package/dest/synchronizer/index.d.ts.map +1 -0
  46. package/dest/synchronizer/index.js +3 -0
  47. package/dest/synchronizer/server_world_state_synchronizer.d.ts +83 -0
  48. package/dest/synchronizer/server_world_state_synchronizer.d.ts.map +1 -0
  49. package/dest/synchronizer/server_world_state_synchronizer.js +434 -0
  50. package/dest/test/index.d.ts +2 -0
  51. package/dest/test/index.d.ts.map +1 -0
  52. package/dest/test/index.js +1 -0
  53. package/dest/test/utils.d.ts +35 -0
  54. package/dest/test/utils.d.ts.map +1 -0
  55. package/dest/test/utils.js +118 -0
  56. package/dest/testing.d.ts +11 -0
  57. package/dest/testing.d.ts.map +1 -0
  58. package/dest/testing.js +48 -0
  59. package/dest/world-state-db/index.d.ts +3 -0
  60. package/dest/world-state-db/index.d.ts.map +1 -0
  61. package/dest/world-state-db/index.js +1 -0
  62. package/dest/world-state-db/merkle_tree_db.d.ts +65 -0
  63. package/dest/world-state-db/merkle_tree_db.d.ts.map +1 -0
  64. package/dest/world-state-db/merkle_tree_db.js +17 -0
  65. package/package.json +98 -0
  66. package/src/index.ts +5 -0
  67. package/src/instrumentation/instrumentation.ts +150 -0
  68. package/src/native/bench_metrics.ts +91 -0
  69. package/src/native/fork_checkpoint.ts +46 -0
  70. package/src/native/index.ts +3 -0
  71. package/src/native/ipc_world_state_instance.ts +849 -0
  72. package/src/native/merkle_trees_facade.ts +375 -0
  73. package/src/native/message.ts +287 -0
  74. package/src/native/native_world_state.ts +435 -0
  75. package/src/native/native_world_state_instance.ts +104 -0
  76. package/src/native/world_state_operation.ts +33 -0
  77. package/src/synchronizer/config.ts +106 -0
  78. package/src/synchronizer/errors.ts +13 -0
  79. package/src/synchronizer/factory.ts +83 -0
  80. package/src/synchronizer/index.ts +3 -0
  81. package/src/synchronizer/server_world_state_synchronizer.ts +525 -0
  82. package/src/test/index.ts +1 -0
  83. package/src/test/utils.ts +184 -0
  84. package/src/testing.ts +65 -0
  85. package/src/world-state-db/index.ts +3 -0
  86. package/src/world-state-db/merkle_tree_db.ts +80 -0
@@ -0,0 +1,48 @@
1
+ import { GENESIS_ARCHIVE_ROOT } from '@aztec-labs/constants';
2
+ import { Fr } from '@aztec-labs/foundation/curves/bn254';
3
+ import { computeFeePayerBalanceLeafSlot } from '@aztec-labs/protocol-contracts/fee-juice';
4
+ import { MerkleTreeId, PublicDataTreeLeaf } from '@aztec-labs/stdlib/trees';
5
+ import { NativeWorldStateService } from './native/index.js';
6
+ async function generateGenesisValues(genesis) {
7
+ // The GENESIS_ARCHIVE_ROOT constant reflects the canonical empty genesis (no public data, no prefilled nullifiers,
8
+ // timestamp 0), so we can only short-circuit when this genesis adds none of those on top.
9
+ if (!genesis.prefilledPublicData.length && genesis.genesisTimestamp === 0n && !genesis.prefilledNullifiers?.length) {
10
+ return {
11
+ genesisArchiveRoot: new Fr(GENESIS_ARCHIVE_ROOT)
12
+ };
13
+ }
14
+ // Compute the genesis values on a throwaway world state. The archive root derives deterministically from the
15
+ // prefilled public data, the prefilled nullifiers, and the genesis timestamp, so the fsync-off ephemeral store (no
16
+ // version manager, no crash-recoverability) produces an identical root while skipping the fsync overhead that `tmp`
17
+ // pays. close() removes the tmpdir.
18
+ const ws = await NativeWorldStateService.ephemeral(genesis);
19
+ const genesisArchiveRoot = new Fr((await ws.getCommitted().getTreeInfo(MerkleTreeId.ARCHIVE)).root);
20
+ await ws.close();
21
+ return {
22
+ genesisArchiveRoot
23
+ };
24
+ }
25
+ export const defaultInitialAccountFeeJuice = new Fr(10n ** 22n);
26
+ export async function getGenesisValues(initialAccounts, initialAccountFeeJuice = defaultInitialAccountFeeJuice, genesisPublicData = [], genesisTimestamp = 0n, prefilledNullifiers = []) {
27
+ // Top up the accounts with fee juice.
28
+ let prefilledPublicData = await Promise.all(initialAccounts.map(async (address)=>new PublicDataTreeLeaf(await computeFeePayerBalanceLeafSlot(address), initialAccountFeeJuice)));
29
+ // Add user-defined public data
30
+ prefilledPublicData = prefilledPublicData.concat(genesisPublicData);
31
+ prefilledPublicData.sort((a, b)=>b.slot.lt(a.slot) ? 1 : -1);
32
+ // The indexed nullifier tree requires its prefilled leaves to be unique and strictly increasing, so sort ascending
33
+ // here (a copy, to avoid mutating the caller's array) rather than relying on the caller's ordering.
34
+ const sortedNullifiers = [
35
+ ...prefilledNullifiers
36
+ ].sort((a, b)=>a.toBigInt() < b.toBigInt() ? -1 : 1);
37
+ const genesis = {
38
+ prefilledPublicData,
39
+ prefilledNullifiers: sortedNullifiers,
40
+ genesisTimestamp
41
+ };
42
+ const { genesisArchiveRoot } = await generateGenesisValues(genesis);
43
+ return {
44
+ genesisArchiveRoot,
45
+ genesis,
46
+ fundingNeeded: BigInt(initialAccounts.length) * initialAccountFeeJuice.toBigInt()
47
+ };
48
+ }
@@ -0,0 +1,3 @@
1
+ export * from './merkle_tree_db.js';
2
+ export type { MerkleTreeReadOperations } from '@aztec-labs/stdlib/interfaces/server';
3
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy93b3JsZC1zdGF0ZS1kYi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHFCQUFxQixDQUFDO0FBRXBDLFlBQVksRUFBRSx3QkFBd0IsRUFBRSxNQUFNLHNDQUFzQyxDQUFDIn0=
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/world-state-db/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AAEpC,YAAY,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC"}
@@ -0,0 +1 @@
1
+ export * from './merkle_tree_db.js';
@@ -0,0 +1,65 @@
1
+ import type { BlockNumber } from '@aztec-labs/foundation/branded-types';
2
+ import type { Fr } from '@aztec-labs/foundation/curves/bn254';
3
+ import type { L2Block } from '@aztec-labs/stdlib/block';
4
+ import type { ForkMerkleTreeOperations, MerkleTreeReadOperations, ReadonlyWorldStateAccess } from '@aztec-labs/stdlib/interfaces/server';
5
+ import type { WorldStateStatusFull, WorldStateStatusSummary } from '../native/message.js';
6
+ /**
7
+ *
8
+ * @remarks Short explanation:
9
+ * The nullifier tree must be initially padded as the pre-populated 0 index prevents efficient subtree insertion.
10
+ * Padding with some values solves this issue.
11
+ *
12
+ * @remarks Thorough explanation:
13
+ * There needs to be an initial (0,0,0) leaf in the tree, so that when we insert the first 'proper' leaf, we can
14
+ * prove that any value greater than 0 doesn't exist in the tree yet. We prefill/pad the tree with "the number of
15
+ * leaves that are added by one block" so that the first 'proper' block can insert a full subtree.
16
+ *
17
+ * Without this padding, there would be a leaf (0,0,0) at leaf index 0, making it really difficult to insert e.g.
18
+ * 1024 leaves for the first block, because there's only neat space for 1023 leaves after 0. By padding with 1023
19
+ * more leaves, we can then insert the first block of 1024 leaves into indices 1024:2047.
20
+ */
21
+ export declare const INITIAL_NULLIFIER_TREE_SIZE: number;
22
+ export declare const INITIAL_PUBLIC_DATA_TREE_SIZE: number;
23
+ export interface MerkleTreeAdminDatabase extends ForkMerkleTreeOperations, ReadonlyWorldStateAccess {
24
+ /**
25
+ * Handles a single L2 block: inserts its note hashes, nullifiers, public data writes, and the block's L1-to-L2
26
+ * message bundle into the merkle trees. Any block may carry a message bundle and transition the L1-to-L2 message
27
+ * tree, not just the first block of a checkpoint. The bundle's real (unpadded, compact) leaves are appended as
28
+ * given, matching how the circuits build the tree.
29
+ * @param block - The L2 block to handle.
30
+ * @param l1ToL2Messages - The L1 to L2 messages for the block.
31
+ */
32
+ handleL2BlockAndMessages(block: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatusFull>;
33
+ /**
34
+ * Gets a handle that allows reading the latest committed state
35
+ */
36
+ getCommitted(): MerkleTreeReadOperations;
37
+ /**
38
+ * Removes all historical snapshots up to but not including the given block number
39
+ * @param toBlockNumber The block number of the new oldest historical block
40
+ * @returns The new WorldStateStatus
41
+ */
42
+ removeHistoricalBlocks(toBlockNumber: BlockNumber): Promise<WorldStateStatusFull>;
43
+ /**
44
+ * Removes all pending blocks down to but not including the given block number
45
+ * @param toBlockNumber The block number of the new tip of the pending chain,
46
+ * @returns The new WorldStateStatus
47
+ */
48
+ unwindBlocks(toBlockNumber: BlockNumber): Promise<WorldStateStatusFull>;
49
+ /**
50
+ * Advances the finalized block number to be the number provided
51
+ * @param toBlockNumber The block number that is now the tip of the finalized chain
52
+ * @returns The new WorldStateStatus
53
+ */
54
+ setFinalized(toBlockNumber: BlockNumber): Promise<WorldStateStatusSummary>;
55
+ /**
56
+ * Gets the current status summary of the database.
57
+ * @returns The current WorldStateStatus.
58
+ */
59
+ getStatusSummary(): Promise<WorldStateStatusSummary>;
60
+ /** Stops the database */
61
+ close(): Promise<void>;
62
+ /** Deletes the db. */
63
+ clear(): Promise<void>;
64
+ }
65
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWVya2xlX3RyZWVfZGIuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy93b3JsZC1zdGF0ZS1kYi9tZXJrbGVfdHJlZV9kYi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSxzQ0FBc0MsQ0FBQztBQUN4RSxPQUFPLEtBQUssRUFBRSxFQUFFLEVBQUUsTUFBTSxxQ0FBcUMsQ0FBQztBQUM5RCxPQUFPLEtBQUssRUFBRSxPQUFPLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQUN4RCxPQUFPLEtBQUssRUFDVix3QkFBd0IsRUFDeEIsd0JBQXdCLEVBQ3hCLHdCQUF3QixFQUN6QixNQUFNLHNDQUFzQyxDQUFDO0FBRTlDLE9BQU8sS0FBSyxFQUFFLG9CQUFvQixFQUFFLHVCQUF1QixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFMUY7Ozs7Ozs7Ozs7Ozs7O0dBY0c7QUFDSCxlQUFPLE1BQU0sMkJBQTJCLFFBQTRCLENBQUM7QUFFckUsZUFBTyxNQUFNLDZCQUE2QixRQUFtRCxDQUFDO0FBRTlGLE1BQU0sV0FBVyx1QkFBd0IsU0FBUSx3QkFBd0IsRUFBRSx3QkFBd0I7SUFDakc7Ozs7Ozs7T0FPRztJQUNILHdCQUF3QixDQUFDLEtBQUssRUFBRSxPQUFPLEVBQUUsY0FBYyxFQUFFLEVBQUUsRUFBRSxHQUFHLE9BQU8sQ0FBQyxvQkFBb0IsQ0FBQyxDQUFDO0lBRTlGOztPQUVHO0lBQ0gsWUFBWSxJQUFJLHdCQUF3QixDQUFDO0lBRXpDOzs7O09BSUc7SUFDSCxzQkFBc0IsQ0FBQyxhQUFhLEVBQUUsV0FBVyxHQUFHLE9BQU8sQ0FBQyxvQkFBb0IsQ0FBQyxDQUFDO0lBRWxGOzs7O09BSUc7SUFDSCxZQUFZLENBQUMsYUFBYSxFQUFFLFdBQVcsR0FBRyxPQUFPLENBQUMsb0JBQW9CLENBQUMsQ0FBQztJQUV4RTs7OztPQUlHO0lBQ0gsWUFBWSxDQUFDLGFBQWEsRUFBRSxXQUFXLEdBQUcsT0FBTyxDQUFDLHVCQUF1QixDQUFDLENBQUM7SUFFM0U7OztPQUdHO0lBQ0gsZ0JBQWdCLElBQUksT0FBTyxDQUFDLHVCQUF1QixDQUFDLENBQUM7SUFFckQseUJBQXlCO0lBQ3pCLEtBQUssSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUM7SUFFdkIsc0JBQXNCO0lBQ3RCLEtBQUssSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUM7Q0FDeEIifQ==
@@ -0,0 +1 @@
1
+ {"version":3,"file":"merkle_tree_db.d.ts","sourceRoot":"","sources":["../../src/world-state-db/merkle_tree_db.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACxE,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qCAAqC,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACzB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE1F;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,QAA4B,CAAC;AAErE,eAAO,MAAM,6BAA6B,QAAmD,CAAC;AAE9F,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB,EAAE,wBAAwB;IACjG;;;;;;;OAOG;IACH,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAE9F;;OAEG;IACH,YAAY,IAAI,wBAAwB,CAAC;IAEzC;;;;OAIG;IACH,sBAAsB,CAAC,aAAa,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAElF;;;;OAIG;IACH,YAAY,CAAC,aAAa,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAExE;;;;OAIG;IACH,YAAY,CAAC,aAAa,EAAE,WAAW,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAE3E;;;OAGG;IACH,gBAAgB,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAErD,yBAAyB;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,sBAAsB;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}
@@ -0,0 +1,17 @@
1
+ import { MAX_NULLIFIERS_PER_TX, MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX } from '@aztec-labs/constants';
2
+ /**
3
+ *
4
+ * @remarks Short explanation:
5
+ * The nullifier tree must be initially padded as the pre-populated 0 index prevents efficient subtree insertion.
6
+ * Padding with some values solves this issue.
7
+ *
8
+ * @remarks Thorough explanation:
9
+ * There needs to be an initial (0,0,0) leaf in the tree, so that when we insert the first 'proper' leaf, we can
10
+ * prove that any value greater than 0 doesn't exist in the tree yet. We prefill/pad the tree with "the number of
11
+ * leaves that are added by one block" so that the first 'proper' block can insert a full subtree.
12
+ *
13
+ * Without this padding, there would be a leaf (0,0,0) at leaf index 0, making it really difficult to insert e.g.
14
+ * 1024 leaves for the first block, because there's only neat space for 1023 leaves after 0. By padding with 1023
15
+ * more leaves, we can then insert the first block of 1024 leaves into indices 1024:2047.
16
+ */ export const INITIAL_NULLIFIER_TREE_SIZE = 2 * MAX_NULLIFIERS_PER_TX;
17
+ export const INITIAL_PUBLIC_DATA_TREE_SIZE = 2 * MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX;
package/package.json ADDED
@@ -0,0 +1,98 @@
1
+ {
2
+ "name": "@aztec-labs/world-state",
3
+ "version": "6.0.0-nightly.20260829",
4
+ "type": "module",
5
+ "exports": {
6
+ ".": "./dest/index.js",
7
+ "./native": "./dest/native/index.js",
8
+ "./test": "./dest/test/index.js",
9
+ "./testing": "./dest/testing.js",
10
+ "./config": "./dest/synchronizer/config.js"
11
+ },
12
+ "typedocOptions": {
13
+ "entryPoints": [
14
+ "./src/index.ts",
15
+ "./src/testing.ts"
16
+ ],
17
+ "name": "World State",
18
+ "tsconfig": "./tsconfig.json"
19
+ },
20
+ "scripts": {
21
+ "build": "yarn clean && ../scripts/tsc.sh",
22
+ "build:dev": "../scripts/tsc.sh --watch",
23
+ "clean": "rm -rf ./dest .tsbuildinfo",
24
+ "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
25
+ },
26
+ "inherits": [
27
+ "../package.common.json"
28
+ ],
29
+ "jest": {
30
+ "moduleNameMapper": {
31
+ "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
32
+ },
33
+ "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
34
+ "rootDir": "./src",
35
+ "transform": {
36
+ "^.+\\.tsx?$": [
37
+ "@swc/jest",
38
+ {
39
+ "jsc": {
40
+ "parser": {
41
+ "syntax": "typescript",
42
+ "decorators": true
43
+ },
44
+ "transform": {
45
+ "decoratorVersion": "2022-03"
46
+ }
47
+ }
48
+ }
49
+ ]
50
+ },
51
+ "extensionsToTreatAsEsm": [
52
+ ".ts"
53
+ ],
54
+ "reporters": [
55
+ "default"
56
+ ],
57
+ "testTimeout": 120000,
58
+ "setupFiles": [
59
+ "../../foundation/src/jest/setup.mjs"
60
+ ],
61
+ "testEnvironment": "../../foundation/src/jest/env.mjs",
62
+ "setupFilesAfterEnv": [
63
+ "../../foundation/src/jest/setupAfterEnv.mjs"
64
+ ]
65
+ },
66
+ "dependencies": {
67
+ "@aztec-labs/constants": "6.0.0-nightly.20260829",
68
+ "@aztec-labs/foundation": "6.0.0-nightly.20260829",
69
+ "@aztec-labs/protocol-contracts": "6.0.0-nightly.20260829",
70
+ "@aztec-labs/stdlib": "6.0.0-nightly.20260829",
71
+ "@aztec-labs/telemetry-client": "6.0.0-nightly.20260829",
72
+ "@aztec/wsdb": "6.0.0-nightly.20260826",
73
+ "msgpackr": "^1.11.2",
74
+ "tslib": "^2.4.0",
75
+ "zod": "^4"
76
+ },
77
+ "devDependencies": {
78
+ "@aztec-labs/archiver": "6.0.0-nightly.20260829",
79
+ "@aztec/ipc-runtime": "6.0.0-nightly.20260826",
80
+ "@jest/globals": "^30.0.0",
81
+ "@types/jest": "^30.0.0",
82
+ "@types/node": "^22.15.17",
83
+ "@typescript/native-preview": "7.0.0-dev.20260113.1",
84
+ "jest": "^30.0.0",
85
+ "jest-mock-extended": "^4.0.0",
86
+ "ts-node": "^10.9.1",
87
+ "typescript": "^5.3.3"
88
+ },
89
+ "files": [
90
+ "dest",
91
+ "src",
92
+ "!*.test.*"
93
+ ],
94
+ "types": "./dest/index.d.ts",
95
+ "engines": {
96
+ "node": ">=20.10"
97
+ }
98
+ }
package/src/index.ts ADDED
@@ -0,0 +1,5 @@
1
+ export * from './synchronizer/index.js';
2
+ export * from './world-state-db/index.js';
3
+ export * from './synchronizer/config.js';
4
+ export * from './native/index.js';
5
+ export { WorldStateInstrumentation } from './instrumentation/instrumentation.js';
@@ -0,0 +1,150 @@
1
+ import { type Logger, createLogger } from '@aztec-labs/foundation/log';
2
+ import { MerkleTreeId } from '@aztec-labs/stdlib/trees';
3
+ import {
4
+ Attributes,
5
+ type Gauge,
6
+ type Histogram,
7
+ Metrics,
8
+ type TelemetryClient,
9
+ type UpDownCounter,
10
+ createUpDownCounterWithDefault,
11
+ } from '@aztec-labs/telemetry-client';
12
+
13
+ import type { DBStats, TreeDBStats, TreeMeta, WorldStateStatusFull } from '../native/message.js';
14
+ import type { WorldStateOperationName } from '../native/world_state_operation.js';
15
+
16
+ type DBTypeString = 'leaf_preimage' | 'leaf_indices' | 'nodes' | 'blocks' | 'block_indices';
17
+
18
+ const durationTrackDenylist = new Set<WorldStateOperationName>(['getInitialStateReference']);
19
+
20
+ export class WorldStateInstrumentation {
21
+ private dbMapSize: Gauge;
22
+ private dbPhysicalSize: Gauge;
23
+ private treeSize: Gauge;
24
+ private unfinalizedHeight: Gauge;
25
+ private finalizedHeight: Gauge;
26
+ private oldestBlock: Gauge;
27
+ private dbNumItems: Gauge;
28
+ private dbUsedSize: Gauge;
29
+ private requestHistogram: Histogram;
30
+ private criticalErrors: UpDownCounter;
31
+
32
+ constructor(
33
+ public readonly telemetry: TelemetryClient,
34
+ private log: Logger = createLogger('world-state:instrumentation'),
35
+ ) {
36
+ const meter = telemetry.getMeter('World State');
37
+ this.dbMapSize = meter.createGauge(Metrics.WORLD_STATE_DB_MAP_SIZE);
38
+
39
+ this.dbPhysicalSize = meter.createGauge(Metrics.WORLD_STATE_DB_PHYSICAL_SIZE);
40
+
41
+ this.treeSize = meter.createGauge(Metrics.WORLD_STATE_TREE_SIZE);
42
+
43
+ this.unfinalizedHeight = meter.createGauge(Metrics.WORLD_STATE_UNFINALIZED_HEIGHT);
44
+
45
+ this.finalizedHeight = meter.createGauge(Metrics.WORLD_STATE_FINALIZED_HEIGHT);
46
+
47
+ this.oldestBlock = meter.createGauge(Metrics.WORLD_STATE_OLDEST_BLOCK);
48
+
49
+ this.dbUsedSize = meter.createGauge(Metrics.WORLD_STATE_DB_USED_SIZE);
50
+
51
+ this.dbNumItems = meter.createGauge(Metrics.WORLD_STATE_DB_NUM_ITEMS);
52
+
53
+ this.requestHistogram = meter.createHistogram(Metrics.WORLD_STATE_REQUEST_TIME);
54
+
55
+ this.criticalErrors = createUpDownCounterWithDefault(meter, Metrics.WORLD_STATE_CRITICAL_ERROR_COUNT, {
56
+ [Attributes.ERROR_TYPE]: [
57
+ 'synch_pending_block',
58
+ 'finalize_block',
59
+ 'prune_pending_block',
60
+ 'prune_historical_block',
61
+ ],
62
+ });
63
+ }
64
+
65
+ private updateTreeStats(treeDbStats: TreeDBStats, treeMeta: TreeMeta, tree: MerkleTreeId) {
66
+ this.dbMapSize.record(Number(treeDbStats.mapSize), {
67
+ [Attributes.MERKLE_TREE_NAME]: MerkleTreeId[tree],
68
+ });
69
+ this.dbPhysicalSize.record(Number(treeDbStats.physicalFileSize), {
70
+ [Attributes.MERKLE_TREE_NAME]: MerkleTreeId[tree],
71
+ });
72
+ this.treeSize.record(Number(treeMeta.size), {
73
+ [Attributes.MERKLE_TREE_NAME]: MerkleTreeId[tree],
74
+ });
75
+ this.unfinalizedHeight.record(Number(treeMeta.unfinalizedBlockHeight), {
76
+ [Attributes.MERKLE_TREE_NAME]: MerkleTreeId[tree],
77
+ });
78
+ this.finalizedHeight.record(Number(treeMeta.finalizedBlockHeight), {
79
+ [Attributes.MERKLE_TREE_NAME]: MerkleTreeId[tree],
80
+ });
81
+ this.oldestBlock.record(Number(treeMeta.oldestHistoricBlock), {
82
+ [Attributes.MERKLE_TREE_NAME]: MerkleTreeId[tree],
83
+ });
84
+
85
+ this.updateTreeDBStats(treeDbStats.blockIndicesDBStats, 'block_indices', tree);
86
+ this.updateTreeDBStats(treeDbStats.blocksDBStats, 'blocks', tree);
87
+ this.updateTreeDBStats(treeDbStats.leafIndicesDBStats, 'leaf_indices', tree);
88
+ this.updateTreeDBStats(treeDbStats.leafPreimagesDBStats, 'leaf_preimage', tree);
89
+ this.updateTreeDBStats(treeDbStats.nodesDBStats, 'nodes', tree);
90
+ }
91
+
92
+ private updateTreeDBStats(dbStats: DBStats, dbType: DBTypeString, tree: MerkleTreeId) {
93
+ this.dbNumItems.record(Number(dbStats.numDataItems), {
94
+ [Attributes.WS_DB_DATA_TYPE]: dbType,
95
+ [Attributes.MERKLE_TREE_NAME]: MerkleTreeId[tree],
96
+ });
97
+ this.dbUsedSize.record(Number(dbStats.totalUsedSize), {
98
+ [Attributes.WS_DB_DATA_TYPE]: dbType,
99
+ [Attributes.MERKLE_TREE_NAME]: MerkleTreeId[tree],
100
+ });
101
+ }
102
+
103
+ public updateWorldStateMetrics(worldStateStatus: WorldStateStatusFull) {
104
+ this.updateTreeStats(
105
+ worldStateStatus.dbStats.archiveTreeStats,
106
+ worldStateStatus.meta.archiveTreeMeta,
107
+ MerkleTreeId.ARCHIVE,
108
+ );
109
+
110
+ this.updateTreeStats(
111
+ worldStateStatus.dbStats.messageTreeStats,
112
+ worldStateStatus.meta.messageTreeMeta,
113
+ MerkleTreeId.L1_TO_L2_MESSAGE_TREE,
114
+ );
115
+
116
+ this.updateTreeStats(
117
+ worldStateStatus.dbStats.noteHashTreeStats,
118
+ worldStateStatus.meta.noteHashTreeMeta,
119
+ MerkleTreeId.NOTE_HASH_TREE,
120
+ );
121
+
122
+ this.updateTreeStats(
123
+ worldStateStatus.dbStats.nullifierTreeStats,
124
+ worldStateStatus.meta.nullifierTreeMeta,
125
+ MerkleTreeId.NULLIFIER_TREE,
126
+ );
127
+
128
+ this.updateTreeStats(
129
+ worldStateStatus.dbStats.publicDataTreeStats,
130
+ worldStateStatus.meta.publicDataTreeMeta,
131
+ MerkleTreeId.PUBLIC_DATA_TREE,
132
+ );
133
+ }
134
+
135
+ public recordRoundTrip(timeUs: number, operation: WorldStateOperationName) {
136
+ if (!durationTrackDenylist.has(operation)) {
137
+ this.requestHistogram.record(Math.ceil(timeUs), {
138
+ [Attributes.WORLD_STATE_REQUEST_TYPE]: operation,
139
+ });
140
+ }
141
+ }
142
+
143
+ public incCriticalErrors(
144
+ errorType: 'synch_pending_block' | 'finalize_block' | 'prune_pending_block' | 'prune_historical_block',
145
+ ) {
146
+ this.criticalErrors.add(1, {
147
+ [Attributes.ERROR_TYPE]: errorType,
148
+ });
149
+ }
150
+ }
@@ -0,0 +1,91 @@
1
+ import { MerkleTreeId } from '@aztec-labs/stdlib/trees';
2
+
3
+ type BlockSyncMetrics = {
4
+ numTxs: number;
5
+ numLeaves: number;
6
+ value: number;
7
+ };
8
+
9
+ export enum InsertionType {
10
+ BATCH,
11
+ SEQUENTIAL,
12
+ }
13
+
14
+ type InsertionMetrics = {
15
+ treeType: MerkleTreeId;
16
+ insertionType: InsertionType;
17
+ numLeaves: number;
18
+ value: number;
19
+ };
20
+
21
+ export enum DataRetrievalType {
22
+ SIBLING_PATH,
23
+ LEAF_PREIMAGE,
24
+ LEAF_VALUE,
25
+ LEAF_INDICES,
26
+ LOW_LEAF,
27
+ }
28
+
29
+ type DataRetrievalMetrics = {
30
+ retrievalType: DataRetrievalType;
31
+ value: number;
32
+ };
33
+
34
+ export class NativeBenchMetics {
35
+ private blockSyncMetrics: BlockSyncMetrics[] = [];
36
+ private insertionMetrics: InsertionMetrics[] = [];
37
+ private dataRetrievalMetrics: DataRetrievalMetrics[] = [];
38
+
39
+ public toPrettyString() {
40
+ let pretty = '';
41
+ pretty += `Block sync metrics:\n`;
42
+ for (const metric of this.blockSyncMetrics) {
43
+ pretty += ` ${metric.numTxs} txs, ${metric.numLeaves} leaves: ${metric.value} ms\n`;
44
+ }
45
+ pretty += `Insertion metrics:\n`;
46
+ for (const metric of this.insertionMetrics) {
47
+ pretty += ` ${MerkleTreeId[metric.treeType]}: ${InsertionType[metric.insertionType]} (${metric.numLeaves} leaves): ${metric.value} ms\n`;
48
+ }
49
+ pretty += `Data retrieval metrics:\n`;
50
+ for (const metric of this.dataRetrievalMetrics) {
51
+ pretty += ` ${DataRetrievalType[metric.retrievalType]}: ${metric.value} us\n`;
52
+ }
53
+ return pretty;
54
+ }
55
+
56
+ public addBlockSyncMetric(numTxs: number, numLeaves: number, value: number) {
57
+ this.blockSyncMetrics.push({ numTxs, numLeaves, value });
58
+ }
59
+ public addInsertionMetric(treeId: MerkleTreeId, insertionType: InsertionType, numLeaves: number, value: number) {
60
+ this.insertionMetrics.push({ treeType: treeId, insertionType, numLeaves, value });
61
+ }
62
+ public addDataRetrievalMetric(retrievalType: DataRetrievalType, value: number) {
63
+ this.dataRetrievalMetrics.push({ retrievalType, value: value });
64
+ }
65
+
66
+ public toGithubActionBenchmarkJSON(indent = 2) {
67
+ const data = [];
68
+ for (const blockSync of this.blockSyncMetrics) {
69
+ data.push({
70
+ name: `Block Sync/${blockSync.numTxs} txs/${blockSync.numLeaves} leaves per tx`,
71
+ value: blockSync.value,
72
+ unit: 'ms',
73
+ });
74
+ }
75
+ for (const insertion of this.insertionMetrics) {
76
+ data.push({
77
+ name: `Tree Insertion/${MerkleTreeId[insertion.treeType]}/${InsertionType[insertion.insertionType]}/${insertion.numLeaves} leaves`,
78
+ value: insertion.value,
79
+ unit: 'ms',
80
+ });
81
+ }
82
+ for (const retrieval of this.dataRetrievalMetrics) {
83
+ data.push({
84
+ name: `Data Retrieval/${DataRetrievalType[retrieval.retrievalType]}`,
85
+ value: retrieval.value,
86
+ unit: 'us',
87
+ });
88
+ }
89
+ return JSON.stringify(data, null, indent);
90
+ }
91
+ }
@@ -0,0 +1,46 @@
1
+ import type { MerkleTreeCheckpointOperations } from '@aztec-labs/stdlib/interfaces/server';
2
+
3
+ export class ForkCheckpoint {
4
+ private completed = false;
5
+
6
+ private constructor(
7
+ private readonly fork: MerkleTreeCheckpointOperations,
8
+ public readonly depth: number,
9
+ ) {}
10
+
11
+ static async new(fork: MerkleTreeCheckpointOperations): Promise<ForkCheckpoint> {
12
+ const depth = await fork.createCheckpoint();
13
+ return new ForkCheckpoint(fork, depth);
14
+ }
15
+
16
+ async commit(): Promise<void> {
17
+ if (this.completed) {
18
+ return;
19
+ }
20
+
21
+ await this.fork.commitCheckpoint();
22
+ this.completed = true;
23
+ }
24
+
25
+ async revert(): Promise<void> {
26
+ if (this.completed) {
27
+ return;
28
+ }
29
+
30
+ await this.fork.revertCheckpoint();
31
+ this.completed = true;
32
+ }
33
+
34
+ /**
35
+ * Reverts this checkpoint and any nested checkpoints created on top of it,
36
+ * leaving the checkpoint depth at the level it was before this checkpoint was created.
37
+ */
38
+ async revertToCheckpoint(): Promise<void> {
39
+ if (this.completed) {
40
+ return;
41
+ }
42
+
43
+ await this.fork.revertAllCheckpointsTo(this.depth - 1);
44
+ this.completed = true;
45
+ }
46
+ }
@@ -0,0 +1,3 @@
1
+ export * from './native_world_state.js';
2
+ export * from './fork_checkpoint.js';
3
+ export { IpcWorldState, getWsdbOptions } from './ipc_world_state_instance.js';