@ton/sandbox 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.31.0] - 2025-05-20
+
+### Added
+
+- Added methods to collect metrics of contracts
+- Added `@ton/sandbox/jest-environment` and `@ton/sandbox/jest-reporter` to write metric snapshots from test run results
+- Added contract method ABI auto-mapping mechanism for detailed benchmark metrics
+- Added methods to generate delta reports from metrics of contracts
+
 ## [0.30.0] - 2025-05-12
 
 ### Changed
@@ -383,4 +392,4 @@ type LogsVerbosity = {
 
 ### Removed
 
-- Changed `blockchain.pushMessage`, `blockchain.processQueue`, `blockchain.runQueue` to be private
+- Changed `blockchain.pushMessage`, `blockchain.processQueue`, `blockchain.runQueue` to be private

package/README.md

@@ -15,6 +15,7 @@ The key difference of this package from [ton-contract-executor](https://github.c
   * [Cross contract tests](#cross-contract-tests)
   * [Testing key points](#testing-key-points)
   * [Test examples](#test-examples)
+* [Benchmark contracts](#benchmark-contracts)
 * [Sandbox pitfalls](#sandbox-pitfalls)
 * [Viewing logs](#viewing-logs)
 * [Setting smart contract state directly](#setting-smart-contract-state-directly)
@@ -290,6 +291,109 @@ Learn more from examples:
 * [FunC Test Examples](https://docs.ton.org/develop/smart-contracts/examples#examples-of-tests-for-smart-contracts)
 * [Tact Test Examples](docs/tact-testing-examples.md) 
 
+## Benchmark contracts
+
+The `@ton/sandbox` package provides `@ton/sandbox/jest-environment` and `@ton/sandbox/jest-reporter` built-in support for benchmarking smart contract behavior during tests, including tracking gas usage, cell size, opcode execution, and action phases.
+This is especially useful for performance analysis, gas optimization, and regression checks on contract logic.
+
+> ℹ️ See also: [Collect metric API](docs/collect-metric-api.md) for low-level control and manual snapshots.
+
+### Features
+
+* Automatic metric collection from all transactions triggered during tests
+* Snapshot reporting with contract-level filters
+* Integration with [blueprint](https://github.com/ton-org/blueprint#benchmark-contracts)
+
+### Setup in `jest.config.ts`
+
+```ts
+import type { Config } from 'jest';
+
+const config: Config = {
+    preset: 'ts-jest',
+    testEnvironment: '@ton/sandbox/jest-environment',
+    globalSetup: './jest.setup.ts',
+    testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+    reporters: [
+        'default',
+        ['@ton/sandbox/jest-reporter', {
+            // options
+            snapshotDir: '.snapshot',              // output folder for benchmark reports, default: '.snapshot'
+            contractDatabase: 'contract.abi.json', // path or json a map of known contracts, see Collect metric API, default: 'contract.abi.json'
+            reportName: 'gas-report',              // report name, default: 'gas-report'
+            depthCompare: 2,                       // comparison depth, default: 2
+            removeRawResult: true,                 // remove raw metric file, default: true
+            contractExcludes: [                    // exclude specific contracts from snapshot, default: []
+                'TreasuryContract',
+            ],
+        }],
+    ],
+};
+
+export default config;
+```
+
+### How to run benchmarks
+
+To collect and save snapshot metrics:
+
+```bash
+BENCH_NEW="some" npx jest
+# or
+npx blueprint snapshot --label "some" 
+```
+
+This will:
+
+* Run your tests
+* Collect contract execution metrics
+* Save a snapshot in `.snapshot/<timestamp>.json`
+
+To compare with a previous snapshot:
+
+```bash
+BENCH_DIFF=true npx jest
+# or
+npx blueprint test --gas-report
+```
+
+### Or setup in `gas-report.config.ts`
+
+```ts
+import config from './jest.config';
+
+config.testNamePattern = '^DescribeName .* - test name$'
+config.testEnvironment = '@ton/sandbox/jest-environment'
+config.reporters = [
+    ['@ton/sandbox/jest-reporter', {
+        contractDatabase: 'abi.json',
+        contractExcludes: [
+            'TreasuryContract',
+        ],
+    }],
+]
+export default config;
+```
+
+**Collect metric and get report:**
+
+```bash
+npx blueprint snapshot --label "some label" -- --config gas-report.config.ts
+npx blueprint test --gas-report -- --config gas-report.config.ts
+```
+
+### Output structure
+
+By default, the reporter generates:
+
+```
+.project-root/
+├── .snapshot/
+│   └── 4200000000000.json    // timestamped snapshot file
+├── .sandbox-metric-raw.jsonl // raw metric log (auto-deleted by default)
+├── contract.abi.json         // map of known contracts, see Collect metric API
+└── gas-report.json           // aggregate report in json format
+```
 
 ## Sandbox pitfalls
 

package/dist/blockchain/Blockchain.js

@@ -13,6 +13,7 @@ const AsyncLock_1 = require("../utils/AsyncLock");
 const message_1 = require("../utils/message");
 const slimConfig_1 = require("../config/slimConfig");
 const testTreasurySubwalletId_1 = require("../utils/testTreasurySubwalletId");
+const collectMetric_1 = require("../metric/collectMetric");
 const CREATE_WALLETS_PREFIX = 'CREATE_WALLETS';
 function createWalletsSeed(idx) {
     return `${CREATE_WALLETS_PREFIX}${idx}`;
@@ -452,25 +453,25 @@ class Blockchain {
                 }
                 const value = target[prop];
                 if (typeof prop === 'string' && typeof value === 'function') {
+                    const ctx = {
+                        contract,
+                        methodName: prop,
+                    };
                     if (prop.startsWith('get')) {
                         return (...args) => value.apply(target, [provider, ...args]);
                     }
                     else if (prop.startsWith('send')) {
                         return async (...args) => {
-                            const ret = value.apply(target, [provider, ...args]);
+                            let ret = value.apply(target, [provider, ...args]);
                             if (ret instanceof Promise) {
-                                const r = await ret;
-                                return {
-                                    ...await blkch.runQueue(),
-                                    result: r,
-                                };
-                            }
-                            else {
-                                return {
-                                    ...await blkch.runQueue(),
-                                    result: ret,
-                                };
+                                ret = await ret;
                             }
+                            const out = {
+                                ...await blkch.runQueue(),
+                                result: ret,
+                            };
+                            await (0, collectMetric_1.collectMetric)(blkch, ctx, out);
+                            return out;
                         };
                     }
                 }

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export { prettyLogTransaction, prettyLogTransactions, } from './utils/prettyLogT
 export { printTransactionFees, } from './utils/printTransactionFees';
 export { internal, } from './utils/message';
 export { ExtraCurrency, } from './utils/ec';
+export * from './metric';

package/dist/index.js

@@ -1,4 +1,18 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.internal = exports.printTransactionFees = exports.prettyLogTransactions = exports.prettyLogTransaction = exports.TreasuryContract = exports.Executor = exports.EmulationError = exports.TimeError = exports.GetMethodError = exports.createShardAccount = exports.createEmptyShardAccount = exports.SmartContract = exports.wrapTonClient4ForRemote = exports.RemoteBlockchainStorage = exports.LocalBlockchainStorage = exports.BlockchainSender = exports.BlockchainContractProvider = exports.toSandboxContract = exports.Blockchain = exports.defaultConfigSeqno = exports.defaultConfig = void 0;
 var defaultConfig_1 = require("./config/defaultConfig");
@@ -33,3 +47,4 @@ var printTransactionFees_1 = require("./utils/printTransactionFees");
 Object.defineProperty(exports, "printTransactionFees", { enumerable: true, get: function () { return printTransactionFees_1.printTransactionFees; } });
 var message_1 = require("./utils/message");
 Object.defineProperty(exports, "internal", { enumerable: true, get: function () { return message_1.internal; } });
+__exportStar(require("./metric"), exports);

package/dist/jest/BenchmarkCommand.d.ts

@@ -0,0 +1,10 @@
+export interface BenchmarkCommandOption {
+    label: string;
+    doDiff: boolean;
+}
+export declare class BenchmarkCommand {
+    readonly label?: string;
+    readonly doDiff: boolean;
+    constructor(option?: Partial<BenchmarkCommandOption>);
+    get doBenchmark(): boolean;
+}

package/dist/jest/BenchmarkCommand.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenchmarkCommand = void 0;
+class BenchmarkCommand {
+    constructor(option) {
+        option = option || {};
+        this.label = option?.label ?? process.env?.BENCH_NEW;
+        this.doDiff = option?.doDiff ?? process.env?.BENCH_DIFF === 'true' ?? false;
+    }
+    get doBenchmark() {
+        return this.doDiff || typeof this.label !== 'undefined';
+    }
+}
+exports.BenchmarkCommand = BenchmarkCommand;

package/dist/jest/BenchmarkEnvironment.d.ts

@@ -0,0 +1,19 @@
+import type { EnvironmentContext } from '@jest/environment';
+import NodeEnvironment from 'jest-environment-node';
+import { Config } from '@jest/types';
+import { BenchmarkCommand, BenchmarkCommandOption } from './BenchmarkCommand';
+export declare const sandboxMetricRawFile = ".sandbox-metric-raw.jsonl";
+export type BenchmarkEnvironmentConfig = {
+    projectConfig: Config.ProjectConfig & {
+        testEnvironmentCommand?: Partial<BenchmarkCommandOption>;
+    };
+    globalConfig: Config.GlobalConfig;
+};
+export default class BenchmarkEnvironment extends NodeEnvironment {
+    protected command: BenchmarkCommand;
+    protected rootDir: string;
+    constructor(config: BenchmarkEnvironmentConfig, context: EnvironmentContext);
+    setup(): Promise<void>;
+    get resultFile(): string;
+    teardown(): Promise<void>;
+}

package/dist/jest/BenchmarkEnvironment.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sandboxMetricRawFile = void 0;
+const path_1 = require("path");
+const node_fs_1 = require("node:fs");
+const jest_environment_node_1 = __importDefault(require("jest-environment-node"));
+const BenchmarkCommand_1 = require("./BenchmarkCommand");
+const metric_1 = require("../metric");
+exports.sandboxMetricRawFile = '.sandbox-metric-raw.jsonl';
+class BenchmarkEnvironment extends jest_environment_node_1.default {
+    constructor(config, context) {
+        super(config, context);
+        this.command = new BenchmarkCommand_1.BenchmarkCommand(config.projectConfig.testEnvironmentCommand);
+        this.rootDir = config.globalConfig.rootDir;
+    }
+    async setup() {
+        if (this.command.doBenchmark) {
+            (0, metric_1.createMetricStore)(this.global);
+        }
+    }
+    get resultFile() {
+        return (0, path_1.join)(this.rootDir, exports.sandboxMetricRawFile);
+    }
+    async teardown() {
+        if (this.command.doBenchmark) {
+            const store = (0, metric_1.getMetricStore)(this.global) || [];
+            const fileName = this.resultFile;
+            const folder = (0, path_1.dirname)(fileName);
+            if (!(0, node_fs_1.existsSync)(folder)) {
+                (0, node_fs_1.mkdirSync)(folder, { recursive: true });
+            }
+            if (!(0, node_fs_1.existsSync)(fileName)) {
+                (0, node_fs_1.writeFileSync)(fileName, '');
+            }
+            for (const item of store) {
+                (0, node_fs_1.appendFileSync)(fileName, JSON.stringify(item) + '\n');
+            }
+            (0, metric_1.resetMetricStore)(this.global);
+        }
+        await super.teardown();
+    }
+}
+exports.default = BenchmarkEnvironment;

package/dist/jest/BenchmarkReporter.d.ts

@@ -0,0 +1,45 @@
+import { BaseReporter } from '@jest/reporters';
+import type { Config } from '@jest/types';
+import { ContractABI } from '@ton/core';
+import { BenchmarkCommand } from './BenchmarkCommand';
+import { Metric, CodeHash, SnapshotMetric, ContractDatabase } from '../metric';
+export declare const defaultSnapshotDir = ".snapshot";
+export declare const defaultReportName = "gas-report";
+export declare const defaultContractDatabaseName = "contract.abi.json";
+export declare const defaultDepthCompare = 2;
+export declare const minComparisonDepth = 1;
+type ReportMode = 'gas' | 'average';
+export interface Options {
+    reportMode?: ReportMode;
+    reportName?: string;
+    snapshotDir?: string;
+    depthCompare?: number;
+    contractExcludes?: string[];
+    removeRawResult?: boolean;
+    contractDatabase?: Record<CodeHash, ContractABI> | string;
+}
+export default class BenchmarkReporter extends BaseReporter {
+    protected rootDirPath: string;
+    protected options: Options;
+    protected command: BenchmarkCommand;
+    contractDatabase: ContractDatabase;
+    constructor(globalConfig: Config.GlobalConfig, options?: Options);
+    get reportMode(): ReportMode;
+    get reportName(): string;
+    get snapshotDir(): string;
+    get snapshotDirPath(): string;
+    get depthCompare(): number;
+    get snapshotFiles(): Promise<import("../metric").SnapshotMetricList>;
+    get snapshots(): Promise<SnapshotMetric[]>;
+    get snapshotCurrent(): Promise<SnapshotMetric>;
+    get removeRawResult(): true;
+    get contractExcludes(): string[];
+    get sandboxMetricRawFile(): string;
+    get metricStore(): Promise<Metric[]>;
+    readContractDatabase(): ContractDatabase;
+    saveContractDatabase(): void;
+    onRunComplete(): Promise<void>;
+    gasReportReport(data: SnapshotMetric[], benchmarkDepth: number): string[];
+    saveSnapshot(label: string): Promise<string>;
+}
+export {};

package/dist/jest/BenchmarkReporter.js

@@ -0,0 +1,207 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.minComparisonDepth = exports.defaultDepthCompare = exports.defaultContractDatabaseName = exports.defaultReportName = exports.defaultSnapshotDir = void 0;
+const path_1 = require("path");
+const fs_1 = require("fs");
+const chalk_1 = __importStar(require("chalk"));
+const reporters_1 = require("@jest/reporters");
+const BenchmarkCommand_1 = require("./BenchmarkCommand");
+const BenchmarkEnvironment_1 = require("./BenchmarkEnvironment");
+const readJsonl_1 = require("../utils/readJsonl");
+const metric_1 = require("../metric");
+exports.defaultSnapshotDir = '.snapshot';
+exports.defaultReportName = 'gas-report';
+exports.defaultContractDatabaseName = 'contract.abi.json';
+exports.defaultDepthCompare = 2;
+exports.minComparisonDepth = 1;
+const PASS_TEXT = 'PASS';
+const PASS = chalk_1.supportsColor ? chalk_1.default.reset.inverse.bold.green(` ${PASS_TEXT} `) : PASS_TEXT;
+const SKIP_TEXT = 'SKIP';
+const SKIP = chalk_1.supportsColor ? chalk_1.default.reset.inverse.bold.yellow(` ${SKIP_TEXT} `) : SKIP_TEXT;
+class BenchmarkReporter extends reporters_1.BaseReporter {
+    constructor(globalConfig, options = {}) {
+        super();
+        this.rootDirPath = globalConfig.rootDir;
+        this.options = options;
+        this.command = new BenchmarkCommand_1.BenchmarkCommand();
+        if (this.depthCompare < exports.minComparisonDepth) {
+            throw new Error(`The minimum depth compare must be greater than or equal to ${exports.minComparisonDepth}`);
+        }
+        this.contractDatabase = this.readContractDatabase();
+    }
+    get reportMode() {
+        return this.options.reportMode || 'gas';
+    }
+    get reportName() {
+        return this.options.reportName || exports.defaultReportName;
+    }
+    get snapshotDir() {
+        return this.options.snapshotDir || exports.defaultSnapshotDir;
+    }
+    get snapshotDirPath() {
+        const dirPath = (0, path_1.join)(this.rootDirPath, this.snapshotDir);
+        try {
+            if (!(0, fs_1.existsSync)(dirPath)) {
+                (0, fs_1.mkdirSync)(dirPath, { recursive: true });
+            }
+        }
+        catch (_) {
+            throw new Error(`Can not create directory: ${dirPath}`);
+        }
+        return dirPath;
+    }
+    get depthCompare() {
+        return this.options.depthCompare || exports.defaultDepthCompare;
+    }
+    get snapshotFiles() {
+        return (0, metric_1.readSnapshots)(this.snapshotDirPath);
+    }
+    get snapshots() {
+        return this.snapshotFiles.then((list) => Object.values(list).map((item) => item.content));
+    }
+    get snapshotCurrent() {
+        return this.metricStore.then((store) => (0, metric_1.makeSnapshotMetric)(store, {
+            contractDatabase: this.contractDatabase,
+            contractExcludes: this.contractExcludes,
+        }));
+    }
+    get removeRawResult() {
+        return this.options.removeRawResult || true;
+    }
+    get contractExcludes() {
+        return this.options.contractExcludes || [];
+    }
+    get sandboxMetricRawFile() {
+        return (0, path_1.join)(this.rootDirPath, BenchmarkEnvironment_1.sandboxMetricRawFile);
+    }
+    get metricStore() {
+        if ((0, fs_1.existsSync)(this.sandboxMetricRawFile)) {
+            return (0, readJsonl_1.readJsonl)(this.sandboxMetricRawFile);
+        }
+        return new Promise((resolve) => resolve([]));
+    }
+    readContractDatabase() {
+        let data = {};
+        const filePath = this.options.contractDatabase || exports.defaultContractDatabaseName;
+        if (typeof filePath === 'string') {
+            try {
+                if ((0, fs_1.existsSync)((0, path_1.join)(this.rootDirPath, filePath))) {
+                    data = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(this.rootDirPath, filePath), 'utf-8'));
+                }
+            }
+            catch (error) {
+                throw new Error(`Could not parse contract database: ${filePath}`);
+            }
+        }
+        return metric_1.ContractDatabase.from(data);
+    }
+    saveContractDatabase() {
+        const contractDatabase = this.options.contractDatabase;
+        let filePath = typeof contractDatabase === 'string' ? contractDatabase : exports.defaultContractDatabaseName;
+        try {
+            const content = JSON.stringify(this.contractDatabase.data, null, 2) + '\n';
+            (0, fs_1.writeFileSync)((0, path_1.join)(this.rootDirPath, filePath), content, {
+                encoding: 'utf8',
+            });
+        }
+        catch (_) {
+            throw new Error(`Can not write: ${filePath}`);
+        }
+    }
+    async onRunComplete() {
+        const log = [];
+        let status = SKIP;
+        if (this.command.doBenchmark) {
+            const list = await this.snapshots;
+            const snapshots = [await this.snapshotCurrent, ...list];
+            let doDiff = this.command.doDiff;
+            const depthCompare = Math.min(snapshots.length, this.depthCompare);
+            if (doDiff) {
+                log.push(`Comparison metric mode: ${this.reportMode} depth: ${depthCompare}`);
+                switch (this.reportMode) {
+                    case 'gas':
+                        log.push(...this.gasReportReport(snapshots, depthCompare));
+                        status = PASS;
+                        break;
+                    default:
+                        throw new Error(`Report mode ${this.reportMode} not supported`);
+                }
+            }
+            else if (this.command.label) {
+                log.push(`Collect metric mode: "${this.reportMode}"`);
+                const file = await this.saveSnapshot(this.command.label);
+                log.push(`Report write in '${file}'`);
+                status = PASS;
+            }
+            if (this.removeRawResult) {
+                (0, fs_1.unlinkSync)(this.sandboxMetricRawFile);
+            }
+            this.saveContractDatabase();
+        }
+        else {
+            log.push(`Reporter mode: ${this.reportMode}`);
+        }
+        this.log(`${status} ${log.join('\n')}`);
+    }
+    gasReportReport(data, benchmarkDepth) {
+        const log = [];
+        const reportFile = `${this.reportName}.json`;
+        const report = (0, metric_1.makeGasReport)(data);
+        try {
+            const reportFilePath = (0, path_1.join)(this.rootDirPath, reportFile);
+            (0, fs_1.writeFileSync)(reportFilePath, JSON.stringify(report, null, 2) + '\n', {
+                encoding: 'utf8',
+            });
+            log.push(`Gas report write in '${reportFile}'`);
+        }
+        catch (_) {
+            throw new Error(`Can not write: ${reportFile}`);
+        }
+        const list = report.sort((0, metric_1.sortByCreatedAt)(true)).slice(0, benchmarkDepth);
+        log.push((0, metric_1.gasReportTable)(list, metric_1.defaultColor));
+        return log;
+    }
+    async saveSnapshot(label) {
+        const snapshot = await this.snapshotCurrent;
+        snapshot.label = label;
+        const list = await this.snapshotFiles;
+        let snapshotFile = `${snapshot.createdAt.getTime()}.json`;
+        if (list[snapshot.label]) {
+            snapshotFile = list[snapshot.label].name;
+        }
+        const snapshotFilePath = (0, path_1.join)(this.snapshotDirPath, snapshotFile);
+        try {
+            (0, fs_1.writeFileSync)(snapshotFilePath, JSON.stringify(snapshot, null, 2) + '\n', {
+                encoding: 'utf8',
+            });
+        }
+        catch (_) {
+            throw new Error(`Can not write: ${(0, path_1.join)(this.snapshotDir, snapshotFile)}`);
+        }
+        return (0, path_1.join)(this.snapshotDir, snapshotFile);
+    }
+}
+exports.default = BenchmarkReporter;

package/dist/metric/ContractDatabase.d.ts

@@ -0,0 +1,21 @@
+import { ContractABI } from '@ton/core';
+import { CodeHash, Metric, OpCode } from './collectMetric';
+type Condition = {
+    codeHash: CodeHash;
+    opCode: OpCode;
+    receiver: 'internal' | 'external-in' | 'external-out';
+};
+export type ContractDataKey = CodeHash | string;
+export type ContractData = Record<ContractDataKey, ContractABI | ContractDataKey>;
+export declare class ContractDatabase {
+    protected list: Map<ContractDataKey, ContractABI>;
+    protected match: Map<ContractDataKey, ContractDataKey>;
+    constructor(abiList: Map<ContractDataKey, ContractABI>, codeHashMatch: Map<ContractDataKey, ContractDataKey>);
+    static from(data: ContractData): ContractDatabase;
+    get data(): ContractData;
+    origin(needle: ContractDataKey): string;
+    get(needle: ContractDataKey): ContractABI | undefined;
+    extract(metric: Metric): void;
+    by(where: Partial<Condition>): Partial<Metric>;
+}
+export {};