Implementation of ContractDBInterface that uses NAPI callbacks to TypeScript. More...

#include <ts_callback_contract_db.hpp>

Inheritance diagram for bb::nodejs::TsCallbackContractDB:

Public Member Functions
	TsCallbackContractDB (Napi::ThreadSafeFunction instanceCallback, Napi::ThreadSafeFunction classCallback, Napi::ThreadSafeFunction addContractsCallback, Napi::ThreadSafeFunction bytecodeCommitmentCallback, Napi::ThreadSafeFunction debugNameCallback, Napi::ThreadSafeFunction createCheckpointCallback, Napi::ThreadSafeFunction commitCheckpointCallback, Napi::ThreadSafeFunction revertCheckpointCallback)
	Constructs a callback-based contracts database.

std::optional< bb::avm2::ContractInstance >	get_contract_instance (const bb::avm2::AztecAddress &address) const override
	Fetches a contract instance by address.

std::optional< bb::avm2::ContractClass >	get_contract_class (const bb::avm2::ContractClassId &class_id) const override
	Fetches a contract class by class ID.

void	add_contracts (const bb::avm2::ContractDeploymentData &contract_deployment_data) override
	Adds contracts from deployment data.

std::optional< bb::avm2::FF >	get_bytecode_commitment (const bb::avm2::ContractClassId &class_id) const override
	Fetches bytecode commitment for a contract class.

std::optional< std::string >	get_debug_function_name (const bb::avm2::AztecAddress &address, const bb::avm2::FF &selector) const override
	Fetches debug function name for a contract function.

void	create_checkpoint () override
	Creates a new checkpoint.

void	commit_checkpoint () override
	Commits the current checkpoint.

void	revert_checkpoint () override
	Reverts the current checkpoint.

void	release ()
	Releases the thread-safe function handles.

Public Member Functions inherited from bb::avm2::simulation::ContractDBInterface
virtual	~ContractDBInterface ()=default

virtual std::optional< ContractInstance >	get_contract_instance (const AztecAddress &address) const =0

virtual std::optional< ContractClass >	get_contract_class (const ContractClassId &class_id) const =0

virtual std::optional< FF >	get_bytecode_commitment (const ContractClassId &class_id) const =0

virtual std::optional< std::string >	get_debug_function_name (const AztecAddress &address, const FunctionSelector &selector) const =0

Private Attributes
Napi::ThreadSafeFunction	contract_instance_callback_

Napi::ThreadSafeFunction	contract_class_callback_

Napi::ThreadSafeFunction	add_contracts_callback_

Napi::ThreadSafeFunction	bytecode_commitment_callback_

Napi::ThreadSafeFunction	debug_name_callback_

Napi::ThreadSafeFunction	create_checkpoint_callback_

Napi::ThreadSafeFunction	commit_checkpoint_callback_

Napi::ThreadSafeFunction	revert_checkpoint_callback_

bool	released_ = false

Detailed Description

Implementation of ContractDBInterface that uses NAPI callbacks to TypeScript.

This class bridges C++ contract data queries to TypeScript's PublicContractsDB. During simulation, when C++ needs contract instances or classes, it calls back to TypeScript through thread-safe NAPI functions.

Thread Safety:

Uses Napi::ThreadSafeFunction to safely call TypeScript from C++ worker threads
BlockingCall ensures synchronous execution with the JavaScript event loop

Lifecycle:

Thread-safe functions must be released after use to avoid memory leaks
Caller is responsible for releasing TSFNs by calling release()

Definition at line 27 of file ts_callback_contract_db.hpp.

Constructor & Destructor Documentation

◆ TsCallbackContractDB()

bb::nodejs::TsCallbackContractDB::TsCallbackContractDB	(	Napi::ThreadSafeFunction	instanceCallback,
		Napi::ThreadSafeFunction	classCallback,
		Napi::ThreadSafeFunction	addContractsCallback,
		Napi::ThreadSafeFunction	bytecodeCommitmentCallback,
		Napi::ThreadSafeFunction	debugNameCallback,
		Napi::ThreadSafeFunction	createCheckpointCallback,
		Napi::ThreadSafeFunction	commitCheckpointCallback,
		Napi::ThreadSafeFunction	revertCheckpointCallback
	)

Constructs a callback-based contracts database.

Parameters

instanceCallback	Thread-safe function to fetch contract instances from TypeScript Expected signature: (address: string) => Promise<Buffer \| undefined>
classCallback	Thread-safe function to fetch contract classes from TypeScript Expected signature: (classId: string) => Promise<Buffer \| undefined>
addContractsCallback	Thread-safe function to add contracts Expected signature: (contractDeploymentData: Buffer) => Promise<void>
bytecodeCommitmentCallback	Thread-safe function to fetch bytecode commitments Expected signature: (classId: string) => Promise<Buffer \| undefined>
debugNameCallback	Thread-safe function to fetch debug function names Expected signature: (address: string, selector: string) => Promise<string \| undefined>
createCheckpointCallback	Thread-safe function to create a checkpoint Expected signature: () => Promise<void>
commitCheckpointCallback	Thread-safe function to commit a checkpoint Expected signature: () => Promise<void>
revertCheckpointCallback	Thread-safe function to revert a checkpoint Expected signature: () => Promise<void>

Definition at line 11 of file ts_callback_contract_db.cpp.

Member Function Documentation

◆ add_contracts()

void bb::nodejs::TsCallbackContractDB::add_contracts ( const bb::avm2::ContractDeploymentData & contract_deployment_data )

overridevirtual

Adds contracts from deployment data.

Parameters

contract_deployment_data The contract deployment data

Implements bb::avm2::simulation::ContractDBInterface.

Definition at line 80 of file ts_callback_contract_db.cpp.

◆ commit_checkpoint()

void bb::nodejs::TsCallbackContractDB::commit_checkpoint ( )

overridevirtual

Commits the current checkpoint.

Accepts the current checkpoint's state as latest.

Implements bb::avm2::simulation::ContractDBInterface.

Definition at line 181 of file ts_callback_contract_db.cpp.

◆ create_checkpoint()

void bb::nodejs::TsCallbackContractDB::create_checkpoint ( )

overridevirtual

Creates a new checkpoint.

Creates a checkpoint in the TypeScript contracts DB, enabling rollbacks to current state.

Implements bb::avm2::simulation::ContractDBInterface.

Definition at line 149 of file ts_callback_contract_db.cpp.

◆ get_bytecode_commitment()

std::optional< bb::avm2::FF > bb::nodejs::TsCallbackContractDB::get_bytecode_commitment ( const bb::avm2::ContractClassId & class_id ) const

override

Fetches bytecode commitment for a contract class.

Parameters

class_id The contract class ID

Returns: std::optional<FF> The bytecode commitment if found, nullopt otherwise

Definition at line 96 of file ts_callback_contract_db.cpp.

◆ get_contract_class()

std::optional< bb::avm2::ContractClass > bb::nodejs::TsCallbackContractDB::get_contract_class ( const bb::avm2::ContractClassId & class_id ) const

override

Fetches a contract class by class ID.

Calls back to TypeScript to retrieve the contract class. The TypeScript callback should return a msgpack-serialized ContractClassHint buffer, or undefined if not found.

Parameters

class_id The contract class ID to lookup

Returns: std::optional<ContractClass> The contract class if found, nullopt otherwise

Definition at line 55 of file ts_callback_contract_db.cpp.

◆ get_contract_instance()

std::optional< bb::avm2::ContractInstance > bb::nodejs::TsCallbackContractDB::get_contract_instance ( const bb::avm2::AztecAddress & address ) const

override

Fetches a contract instance by address.

Calls back to TypeScript to retrieve the contract instance. The TypeScript callback should return a msgpack-serialized ContractInstanceHint buffer, or undefined if not found.

Parameters

address The contract address to lookup

Returns: std::optional<ContractInstance> The contract instance if found, nullopt otherwise

Definition at line 29 of file ts_callback_contract_db.cpp.

◆ get_debug_function_name()

std::optional< std::string > bb::nodejs::TsCallbackContractDB::get_debug_function_name	(	const bb::avm2::AztecAddress &	address,
		const bb::avm2::FF &	selector
	)		const