Models API Reference¶

This section provides complete API documentation for all dbsync-py model classes, organized by functional category.

Base Models¶

Core base classes and foundation types used throughout the package.

`dbsync.models.base` ¶

Base model classes for Cardano DB Sync SQLModel implementation.

This module provides base classes and common patterns for all database models.

`DBSyncBase` ¶

Bases: SQLModel

Base class for all Cardano DB Sync models.

Provides common functionality and configuration for database models.

`repr()` ¶

String representation of the model.

`__table_args__()` ¶

Common table arguments for all models.

Allows table redefinition for testing scenarios.

`tablename()` ¶

Generate table name from class name.

Converts CamelCase to snake_case for table names.

`get_column_names()` `classmethod` ¶

Get list of column names for this model.

Returns:

Type	Description
`list[str]`	List of column names

`to_dict()` ¶

Convert model to dictionary.

Returns:

Type	Description
`dict[str, Any]`	Dictionary representation of the model

`update_from_dict(data)` ¶

Update model fields from dictionary.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	Dictionary with field values to update	required

Foundation Models¶

Essential blockchain foundation models including metadata and network information.

`dbsync.models.foundation` ¶

Foundation models and types for Cardano DB Sync.

This module contains the fundamental types and base models that other modules depend on. Basic foundation models and configuration types.

`ChainMeta` ¶

Bases: DBSyncBase

Chain metadata model for the meta table.

Stores fundamental blockchain network information.

`get_network_info()` ¶

Get network information summary.

Returns:

Type	Description
`dict[str, Any]`	Dictionary with network information

`is_mainnet()` ¶

Check if this is mainnet.

Returns:

Type	Description
`bool`	True if this is mainnet, False otherwise

`is_testnet()` ¶

Check if this is a testnet.

Returns:

Type	Description
`bool`	True if this is a testnet, False otherwise

`EventInfo` ¶

Bases: DBSyncBase

Event info model for the event_info table.

Represents blockchain events and their details for monitoring and debugging purposes. Maps to the actual database schema.

`ExtraMigrations` ¶

Bases: DBSyncBase

Extra migrations model for the extra_migrations table.

Represents optional database migrations that may be applied beyond the standard schema migrations.

Blockchain Models¶

Core blockchain infrastructure including blocks, epochs, slot leaders, and schema versioning.

`dbsync.models.blockchain` ¶

Blockchain models for Cardano DB Sync.

This module contains the core blockchain models including blocks, transactions, epochs, and addresses.

`Address` ¶

Bases: DBSyncBase

Address model for the address table.

Represents Cardano addresses (payment and stake addresses).

`Block` ¶

Bases: DBSyncBase

Block model for the block table.

Represents Cardano blocks with their metadata and relationships.

`Epoch` ¶

Bases: DBSyncBase

Epoch model for the epoch table.

Represents Cardano epochs with their metrics and timing.

`EpochSyncTime` ¶

Bases: DBSyncBase

Epoch sync time model for the epoch_sync_time table.

Tracks synchronization timing for epochs.

`ReverseIndex` ¶

Bases: DBSyncBase

Reverse index model for the reverse_index table.

Provides reverse indexing capabilities for efficient queries.

`SchemaVersion` ¶

Bases: DBSyncBase

Schema version model for the schema_version table.

Tracks the database schema version for migration purposes.

`str()` ¶

Return version as dot-separated string.

`is_compatible(required_version)` ¶

Check if this schema version is compatible with a required version.

Parameters:

Name	Type	Description	Default
`required_version`	`tuple[int, int, int]`	Tuple of (major, minor, patch) version numbers	required

Returns:

Type	Description
`bool`	True if this version is greater than or equal to the required version

`SlotLeader` ¶

Bases: DBSyncBase

Slot leader model for the slot_leader table.

Represents entities that can produce blocks (stake pools).

`StakeAddress` ¶

Bases: DBSyncBase

Stake address model for the stake_address table.

Represents Cardano stake addresses used for delegation and rewards.

`Transaction` ¶

Bases: DBSyncBase

Transaction model for the tx table.

Represents Cardano transactions with their basic metadata.

Transaction Models¶

Transaction-related models including inputs, outputs, metadata, and auxiliary data.

`dbsync.models.transactions` ¶

Transaction detail models for Cardano DB Sync.

This module contains detailed transaction models including inputs, outputs, scripts, redeemers, and other transaction components. Transaction input, output, and metadata models.

`CollateralTransactionInput` ¶

Bases: DBSyncBase

Collateral transaction input model for the collateral_tx_in table.

Represents collateral inputs used for script validation in smart contract transactions.

`CollateralTransactionOutput` ¶

Bases: DBSyncBase

Collateral transaction output model for the collateral_tx_out table.

Represents collateral outputs that are created only if script validation fails.

`Datum` ¶

Bases: DBSyncBase

Datum model for the datum table.

Represents Plutus datum found in transaction witnesses or inlined in outputs.

`ExtraKeyWitness` ¶

Bases: DBSyncBase

Extra key witness model for the extra_key_witness table.

Represents additional key witness hashes in transactions.

`ReferenceTransactionInput` ¶

Bases: DBSyncBase

Reference transaction input model for the reference_tx_in table.

Represents reference inputs (CIP-31) that are read but not consumed.

`ScriptPurposeType` ¶

Bases: str, Enum

Enumeration of script purpose types in Cardano.

`TransactionCbor` ¶

Bases: DBSyncBase

Transaction CBOR model for the tx_cbor table.

Stores the raw CBOR-encoded transaction data.

`TransactionInput` ¶

Bases: DBSyncBase

Transaction input model for the tx_in table.

Represents transaction inputs that spend previous transaction outputs.

`TransactionOutput` ¶

Bases: DBSyncBase

Transaction output model for the tx_out table.

Represents transaction outputs that can be spent as inputs.

`TxMetadata` ¶

Bases: DBSyncBase

Transaction metadata model for the tx_metadata table.

Represents metadata attached to a transaction. Transaction metadata allows arbitrary data to be attached to transactions using a key-value structure where keys are unsigned 64-bit integers.

`Withdrawal` ¶

Bases: DBSyncBase

Withdrawal model for the withdrawal table.

Represents withdrawals from reward accounts in transactions.

Staking Models¶

Stake address, delegation, and reward-related models for Cardano's proof-of-stake system.

`dbsync.models.staking` ¶

Staking and delegation models for Cardano DB Sync.

This module contains the staking and delegation models including stake registrations, delegations, epoch stake distribution, and rewards.

`Delegation` ¶

Bases: DBSyncBase

Delegation model for the delegation table.

Represents stake delegation certificates that delegate stake to a specific stake pool for block production and rewards.

`DelegationVote` ¶

Bases: DBSyncBase

Delegation vote model for the delegation_vote table.

Represents vote delegation certificates from the Conway era that delegate voting power to DReps (Delegated Representatives) for governance.

`EpochStake` ¶

Bases: DBSyncBase

Epoch stake model for the epoch_stake table.

Represents the historical stake distribution for each epoch, showing how much stake each address had delegated to each pool.

`EpochStakeProgress` ¶

Bases: DBSyncBase

Epoch stake progress model for the epoch_stake_progress table.

Tracks the progress of stake calculation for each epoch to monitor synchronization status and performance.

`Reward` ¶

Bases: DBSyncBase

Reward model for the reward table.

Represents staking rewards earned by stake addresses, including block production rewards, delegation rewards, and treasury distributions.

Note: This table has no primary key and uses a composite structure.

`RewardType` ¶

Bases: str, Enum

Enum for reward types in the Cardano protocol.

`StakeDeregistration` ¶

Bases: DBSyncBase

Stake deregistration model for the stake_deregistration table.

Represents stake key deregistration certificates that remove an address from participation in the staking protocol and refund the deposit.

`StakeRegistration` ¶

Bases: DBSyncBase

Stake registration model for the stake_registration table.

Represents stake key registration certificates that enable an address to participate in the staking protocol.

Pool Models¶

Stake pool registration, retirement, metadata, and performance tracking models.

`dbsync.models.pools` ¶

Stake pool management models for Cardano DB Sync.

This module contains the stake pool management models including pool registration, retirement, metadata, relays, and performance tracking. Stake Pool Management Models.

`DelistedPool` ¶

Bases: DBSyncBase

Delisted pool model for the delisted_pool table.

Represents pools that have been delisted from SMASH or other registries.

`OffchainPoolData` ¶

Bases: DBSyncBase

Offchain pool data model for the off_chain_pool_data table.

Represents cached pool metadata that has been fetched from external URLs.

`OffchainPoolFetchError` ¶

Bases: DBSyncBase

Offchain pool fetch error model for the off_chain_pool_fetch_error table.

Represents errors encountered when trying to fetch pool metadata from external URLs.

`PoolHash` ¶

Bases: DBSyncBase

Pool hash model for the pool_hash table.

Represents unique pool identifiers (pool IDs) used throughout the system.

`PoolMetadataRef` ¶

Bases: DBSyncBase

Pool metadata reference model for the pool_metadata_ref table.

Represents references to pool metadata URLs and hashes, used for fetching and validating pool information.

`PoolOwner` ¶

Bases: DBSyncBase

Pool owner model for the pool_owner table.

Represents the ownership relationship between stake addresses and pools.

`PoolRelay` ¶

Bases: DBSyncBase

Pool relay model for the pool_relay table.

Represents network relay configuration for stake pools, defining how other nodes can connect to the pool.

`PoolRelayType` ¶

Bases: str, Enum

Enum for pool relay types in the Cardano protocol.

`PoolRetire` ¶

Bases: DBSyncBase

Pool retire model for the pool_retire table.

Represents pool retirement certificates that schedule pools for deregistration.

`PoolStat` ¶

Bases: DBSyncBase

Pool statistics model for the pool_stat table.

Represents pool performance statistics calculated per epoch.

`PoolUpdate` ¶

Bases: DBSyncBase

Pool update model for the pool_update table.

Represents pool registration and update certificates that define pool parameters, metadata, and operational details.

`ReserveUtxo` ¶

Bases: DBSyncBase

Reserve UTXO model for the reserve table.

Represents UTXOs in the reserve pot, used for treasury and reserve distributions.

`ReservedPoolTicker` ¶

Bases: DBSyncBase

Reserved pool ticker model for the reserved_pool_ticker table.

Represents ticker names that are reserved and cannot be used by pools.

Asset Models¶

Multi-asset support including native tokens, minting, and asset metadata.

`dbsync.models.assets` ¶

Multi-asset support models for Cardano DB Sync.

This module contains the multi-asset models including native tokens, minting events, and multi-asset outputs.

Supports CIP14 asset fingerprints and integration with pycardano classes.

`MaTxMint` ¶

Bases: DBSyncBase

Multi-asset transaction mint model representing minting/burning events.

Maps to the 'ma_tx_mint' table in Cardano DB Sync. Tracks the minting or burning of native assets in transactions.

Attributes:

Name	Type	Description
`id_`	`int \| None`	Primary key
`quantity`	`int`	Amount minted (positive) or burned (negative)
`tx_id`	`int`	Foreign key to transaction
`ident`	`int`	Foreign key to multi_asset

References

Cardano Ledger: Native token minting and burning
Transaction structure with mint field

`absolute_quantity` `property` ¶

Get absolute quantity (always positive).

`is_burn` `property` ¶

Check if this is a burning event (negative quantity).

`is_mint` `property` ¶

Check if this is a minting event (positive quantity).

`MaTxOut` ¶

Bases: DBSyncBase

Multi-asset transaction output model representing asset amounts in outputs.

Maps to the 'ma_tx_out' table in Cardano DB Sync. Tracks the amounts of native assets in transaction outputs.

Attributes:

Name	Type	Description
`id_`	`int \| None`	Primary key
`quantity`	`int`	Amount of the asset in the output
`tx_out_id`	`int`	Foreign key to transaction output
`ident`	`int`	Foreign key to multi_asset

References

Cardano Ledger: Multi-asset transaction outputs
UTXO model with native asset support

`quantity_lovelace` `property` ¶

Get quantity in lovelace equivalent (for display purposes).

`MultiAsset` ¶

Bases: DBSyncBase

Multi-asset model representing native tokens and NFTs.

Maps to the 'multi_asset' table in Cardano DB Sync. Represents unique assets identified by policy ID and asset name.

Attributes:

Name	Type	Description
`id_`	`int \| None`	Primary key
`policy`	`bytes`	Policy ID (28 bytes) - the minting policy hash
`name`	`bytes`	Asset name bytes - the asset name within the policy
`fingerprint`	`str`	CIP14 asset fingerprint for easy identification

References

Cardano Ledger: Native tokens and multi-asset support
CIP-14: Asset fingerprint standard

`asset_name_hex` `property` ¶

Get asset name as hex string.

`policy_id_hex` `property` ¶

Get policy ID as hex string.

`to_pycardano_asset_name()` ¶

Convert to pycardano AssetName.

Returns:

Type	Description
	pycardano.AssetName instance

Raises:

Type	Description
`ImportError`	If pycardano is not available

`to_pycardano_policy_id()` ¶

Convert to pycardano PolicyId.

Returns:

Type	Description
	pycardano.PolicyId instance

Raises:

Type	Description
`ImportError`	If pycardano is not available

`generate_cip14_fingerprint(policy_id, asset_name)` ¶

Generate CIP14 asset fingerprint from policy ID and asset name.

Parameters:

Name	Type	Description	Default
`policy_id`	`bytes`	The 28-byte policy ID	required
`asset_name`	`bytes`	The asset name bytes	required

Returns:

Type	Description
`str`	CIP14 asset fingerprint string

References

CIP-14: https://cips.cardano.org/cips/cip14/

Script Models¶

Smart contract scripts, datums, redeemers, and cost model implementations.

`dbsync.models.scripts` ¶

Script and smart contract models for Cardano DB Sync.

This module contains the script models including Plutus scripts, redeemer data, and script execution context.

Supports Plutus script versioning and integration with pycardano classes.

`CostModel` ¶

Bases: DBSyncBase

Cost model for Plutus script execution.

Maps to the 'cost_model' table in Cardano DB Sync. Stores execution cost parameters for different Plutus script operations.

Attributes:

Name	Type	Description
`id_`	`int \| None`	Primary key
`hash_`	`bytes`	Hash of the cost model (32 bytes) - ensures uniqueness
`costs`	`dict`	JSON object containing the actual cost parameters

References

Plutus: Script execution cost model
Cardano Ledger: Protocol parameter cost models

`hash_hex` `property` ¶

Get cost model hash as hex string.

`is_valid` `property` ¶

Check if cost model has valid structure.

`operation_count` `property` ¶

Get number of operations defined in this cost model.

`get_operation_cost(operation)` ¶

Get cost for a specific operation.

Parameters:

Name	Type	Description	Default
`operation`	`str`	The operation name to get cost for	required

Returns:

Type	Description
`int \| None`	Cost for the operation, or None if not found

`has_operation(operation)` ¶

Check if cost model includes a specific operation.

Parameters:

Name	Type	Description	Default
`operation`	`str`	The operation name to check	required

Returns:

Type	Description
`bool`	True if operation is defined in cost model

`PlutusVersion` ¶

Bases: str, Enum

Plutus script version enumeration.

`Redeemer` ¶

Bases: DBSyncBase

Redeemer model representing script execution context.

Maps to the 'redeemer' table in Cardano DB Sync. Links redeemer data to specific script executions with execution costs.

Attributes:

Name	Type	Description
`id`		Primary key
`tx_id`	`int`	Foreign key to transaction containing this redeemer
`unit_mem`	`int`	Memory units consumed during script execution
`unit_steps`	`int`	CPU steps consumed during script execution
`fee`	`int \| None`	Fee charged for script execution (lovelace)
`purpose`	`str`	Purpose of script execution (spend, mint, cert, reward, vote, propose)
`index`	`int`	Index within the transaction for this purpose
`script_hash`	`bytes \| None`	Hash of the script being executed
`redeemer_data_id`	`int \| None`	Foreign key to redeemer data

References

Plutus: Script execution and cost model
Cardano Ledger: Transaction validation and fees

`execution_cost_ratio` `property` ¶

Get ratio of memory to CPU units.

`is_certificate_redeemer` `property` ¶

Check if this redeemer is for certificate validation.

`is_minting_redeemer` `property` ¶

Check if this redeemer is for minting/burning assets.

`is_reward_redeemer` `property` ¶

Check if this redeemer is for reward withdrawal.

`is_spending_redeemer` `property` ¶

Check if this redeemer is for spending a UTXO.

`script_hash_hex` `property` ¶

Get script hash as hex string.

`total_execution_units` `property` ¶

Get total execution units (memory + steps).

`to_pycardano_execution_units()` ¶

Convert to pycardano ExecutionUnits.

Returns:

Type	Description
	pycardano.ExecutionUnits instance

Raises:

Type	Description
`ImportError`	If pycardano is not available

`RedeemerData` ¶

Bases: DBSyncBase

Redeemer data model representing script execution parameters.

Maps to the 'redeemer_data' table in Cardano DB Sync. Stores the data provided to scripts during execution.

Attributes:

Name	Type	Description
`id`		Primary key
`hash`		Hash of the redeemer data (32 bytes)
`tx_id`	`int`	Foreign key to transaction containing this redeemer data
`value`	`dict \| None`	CBOR-encoded redeemer data
`data_bytes`	`dict \| None`	Raw bytes of the redeemer data

References

Plutus: Script execution and redeemer data
CBOR: Concise Binary Object Representation

`hash_hex` `property` ¶

Get redeemer data hash as hex string.

`size_bytes` `property` ¶

Get size of redeemer data in bytes.

`to_pycardano_redeemer_data()` ¶

Convert to pycardano redeemer data.

Returns:

Type	Description
	Decoded redeemer data object

Raises:

Type	Description
`ImportError`	If pycardano is not available

`RedeemerTag` ¶

Bases: str, Enum

Redeemer tag enumeration for script execution context.

`Script` ¶

Bases: DBSyncBase

Script model representing all types of Cardano scripts.

Maps to the 'script' table in Cardano DB Sync. Represents both native scripts and Plutus scripts with their metadata.

Attributes:

Name	Type	Description
`id_`	`int \| None`	Primary key
`tx_id`	`int`	Foreign key to transaction that registered this script
`hash_`	`bytes`	Script hash (28 bytes)
`script_type`	`bytes`	Script type (native, plutusV1, plutusV2, plutusV3)
`script_json`	`bytes`	Native script JSON representation (for native scripts)
`script_bytes`	`bytes`	Script bytes (for Plutus scripts)
`serialised_size`	`int \| None`	Size of serialized script in bytes

References

Cardano Ledger: Script validation and execution
Plutus: Smart contract platform for Cardano

`hash_hex` `property` ¶

Get script hash as hex string.

`is_native` `property` ¶

Check if this is a native script.

`is_plutus` `property` ¶

Check if this is a Plutus script.

`plutus_version` `property` ¶

Get Plutus version if this is a Plutus script.

`to_pycardano_script_hash()` ¶

Convert to pycardano ScriptHash.

Returns:

Type	Description
	pycardano.ScriptHash instance

Raises:

Type	Description
`ImportError`	If pycardano is not available

`ScriptType` ¶

Bases: str, Enum

Script type enumeration for different script languages.

Treasury Models¶

Treasury, reserves, and monetary policy implementation models.

`dbsync.models.treasury` ¶

Treasury and reserves models for Cardano DB Sync.

This module contains models for treasury operations, reserve payments, pot transfers, and ADA distribution tracking.

`AdaPots` ¶

Bases: DBSyncBase

ADA pots model representing the distribution of all ADA across different protocol pots.

Maps to the 'ada_pots' table in Cardano DB Sync. Provides a snapshot of ADA distribution across treasury, reserves, rewards, UTxO, deposits, and fees at specific blocks/epochs.

The treasury and rewards fields are correct for the whole epoch, but all other fields change block by block during Shelley and later eras.

Attributes:

Name	Type	Description
`id_`	`int \| None`	Primary key
`slot_no`	`int`	Slot number where this snapshot was taken
`epoch_no`	`int`	Epoch number where this snapshot was taken
`treasury`	`int`	Amount in Lovelace in the treasury pot
`reserves`	`int`	Amount in Lovelace in the reserves pot
`rewards`	`int`	Amount in Lovelace in the rewards pot
`utxo`	`int`	Amount in Lovelace in the UTxO set
`deposits_stake`	`int`	Amount in Lovelace from stake key and pool deposits
`deposits_drep`	`int`	Amount in Lovelace from DRep registration deposits (Conway era)
`deposits_proposal`	`int`	Amount in Lovelace from governance proposal deposits (Conway era)
`fees`	`int`	Amount in Lovelace in the fee pot
`block_id`	`int`	Foreign key to block where this snapshot was taken

References

Cardano Ledger: ADA supply tracking and accounting
Protocol: Treasury, reserves, and rewards management
Conway Era: Governance deposit tracking

`circulating_supply` `property` ¶

Calculate circulating ADA supply (UTxO + rewards).

Returns:

Type	Description
`int`	Circulating supply in Lovelace (excludes treasury, reserves, deposits, fees)

`circulating_supply_ada` `property` ¶

Calculate circulating ADA supply in ADA units.

`total_deposits` `property` ¶

Calculate total deposits across all deposit types.

Returns:

Type	Description
`int`	Total deposits in Lovelace

`total_deposits_ada` `property` ¶

Calculate total deposits in ADA units.

`total_supply` `property` ¶

Calculate total ADA supply from all pots.

Returns:

Type	Description
`int`	Total ADA supply in Lovelace

`total_supply_ada` `property` ¶

Calculate total ADA supply in ADA units.

`get_distribution_summary()` ¶

Get ADA distribution summary across all pots.

Returns:

Type	Description
`dict`	Dictionary with ADA distribution information

`get_pot_balance(pot_name)` ¶

Get balance for a specific pot by name.

Parameters:

Name	Type	Description	Default
`pot_name`	`str`	Name of the pot ("treasury", "reserves", "rewards", etc.)	required

Returns:

Type	Description
`int`	Balance in Lovelace, or 0 if pot name is invalid

`get_pot_balance_ada(pot_name)` ¶

Get balance for a specific pot by name in ADA units.

Parameters:

Name	Type	Description	Default
`pot_name`	`str`	Name of the pot	required

Returns:

Type	Description
`float`	Balance in ADA

`PotTransfer` ¶

Bases: DBSyncBase

Pot transfer model representing transfers between treasury and reserves pots.

Maps to the 'pot_transfer' table in Cardano DB Sync. Tracks transfers of ADA between the treasury pot and reserves pot, typically used for protocol governance operations.

Attributes:

Name	Type	Description
`id_`	`int \| None`	Primary key
`cert_index`	`int`	Index of transfer certificate within transaction certificates
`treasury`	`int`	Amount the treasury balance changes by (can be positive or negative)
`reserves`	`int`	Amount the reserves balance changes by (can be positive or negative)
`tx_id`	`int`	Foreign key to transaction containing this transfer

References

Cardano Ledger: Treasury and reserves pot management
Governance: Protocol fund transfers and allocations

`reserves_ada` `property` ¶

Get reserves change amount in ADA.

`total_amount_transferred` `property` ¶

Get the absolute amount transferred (always positive).

`total_amount_transferred_ada` `property` ¶

Get the absolute amount transferred in ADA.

`transfer_direction` `property` ¶

Get transfer direction as string.

Returns:

Type	Description
`str`	"treasury_to_reserves", "reserves_to_treasury", or "balanced"

`treasury_ada` `property` ¶

Get treasury change amount in ADA.

`is_reserves_to_treasury()` ¶

Check if this is a transfer from reserves to treasury.

`is_treasury_to_reserves()` ¶

Check if this is a transfer from treasury to reserves.

`Treasury` ¶

Bases: DBSyncBase

Treasury payment model representing payments from the treasury to stake addresses.

Maps to the 'treasury' table in Cardano DB Sync. Tracks treasury payments to stake addresses for protocol governance rewards.

Note: Before protocol version 5.0 (Alonzo), if more than one payment was made to a stake address in a single epoch, only the last payment was kept and earlier ones removed. For protocol version 5.0 and later, they are summed and produce a single reward with type 'treasury'.

Attributes:

Name	Type	Description
`id_`	`int \| None`	Primary key
`addr_id`	`int`	Foreign key to StakeAddress table
`cert_index`	`int`	Index of payment certificate within transaction certificates
`amount`	`int`	Payment amount in Lovelace (can be large, uses int65type)
`tx_id`	`int`	Foreign key to transaction containing this payment

References

Cardano Ledger: Treasury management and payments
Governance: Protocol treasury distributions

`amount_ada` `property` ¶

Get treasury payment amount in ADA.

`is_large_payment` `property` ¶

Check if this is a large treasury payment (>1M ADA).

`to_reward_record()` ¶

Convert to reward record format.

Returns:

Type	Description
`dict`	Dictionary with reward record information

Protocol Models¶

Protocol parameters, proposals, and epoch parameter tracking.

`dbsync.models.protocol` ¶

Protocol parameter models for Cardano DB Sync.

This module contains models for protocol parameter management including parameter proposals, active epoch parameters, and reward calculations. Protocol parameter and epoch configuration models.

`EpochParam` ¶

Bases: DBSyncBase

Epoch parameter model for the epoch_param table.

Represents the active protocol parameters for each epoch.

`calculate_min_fee(tx_size)` ¶

Calculate minimum fee for a transaction of given size.

Parameters:

Name	Type	Description	Default
`tx_size`	`int`	Transaction size in bytes	required

Returns:

Type	Description
`int`	Minimum fee in lovelace

`get_economic_params()` ¶

Get economic parameters.

Returns:

Type	Description
`dict[str, Any]`	Dictionary with economic parameters

`get_protocol_version()` ¶

Get protocol version information.

Returns:

Type	Description
`dict[str, int \| None]`	Dictionary with major and minor version numbers

`get_size_limits()` ¶

Get size limit parameters.

Returns:

Type	Description
`dict[str, int \| None]`	Dictionary with size limits

`is_fully_decentralized()` ¶

Check if the network is fully decentralized.

Returns:

Type	Description
`bool`	True if decentralisation parameter is 0

`ParamProposal` ¶

Bases: DBSyncBase

Parameter proposal model for the param_proposal table.

Represents protocol parameter change proposals submitted to the network.

`get_proposal_summary()` ¶

Get a summary of the proposed parameter changes.

Returns:

Type	Description
`dict[str, Any]`	Dictionary containing non-null proposed parameters

`is_hard_fork_proposal()` ¶

Check if this proposal includes a hard fork (major protocol version change).

Returns:

Type	Description
`bool`	True if this proposal changes the major protocol version

`RewardRest` ¶

Bases: DBSyncBase

Reward rest model for the reward_rest table.

Represents remaining reward calculations and distributions. Note: This table has no primary key in the database schema.

`amount_ada` `property` ¶

Get reward amount in ADA.

Returns:

Type	Description
`float`	Amount in ADA (amount / 1,000,000)

`epochs_until_spendable(current_epoch)` ¶

Calculate epochs until reward becomes spendable.

Parameters:

Name	Type	Description	Default
`current_epoch`	`int`	Current epoch number	required

Returns:

Type	Description
`int`	Number of epochs until spendable (0 if already spendable)

`get_reward_info()` ¶

Get comprehensive reward information.

Returns:

Type	Description
`dict[str, Any]`	Dictionary with reward details

`is_spendable_in_epoch(epoch_no)` ¶

Check if reward is spendable in given epoch.

Parameters:

Name	Type	Description	Default
`epoch_no`	`int`	Epoch number to check	required

Returns:

Type	Description
`bool`	True if reward is spendable in the given epoch

Governance Models¶

Conway era governance including DReps, committees, governance actions, and voting procedures.

`dbsync.models.governance` ¶

Conway era governance models for Cardano DB Sync.

This module contains models for Conway era governance functionality including DReps (Delegated Representatives), Constitutional Committee, Governance Actions, Voting, and offchain governance metadata.

Key Conway Era Features: - DRep registration and voting power delegation - Constitutional committee with hot/cold key setup - Governance action proposals and lifecycle management - Voting procedures for all governance bodies - Treasury withdrawals and constitution management - Offchain governance metadata (CIP-100, CIP-108, CIP-119)

`Committee` ¶

Bases: DBSyncBase

Committee model for the committee table.

Represents the current Constitutional Committee composition and thresholds for Conway era governance.

`CommitteeDeRegistration` ¶

Bases: DBSyncBase

Committee de-registration model for the committee_de_registration table.

Tracks Constitutional Committee member resignations and de-registrations in Conway era governance.

`CommitteeHash` ¶

Bases: DBSyncBase

Committee hash model for the committee_hash table.

Stores hash identifiers for Constitutional Committee members. The Constitutional Committee ensures governance actions comply with the Cardano Constitution.

`CommitteeMember` ¶

Bases: DBSyncBase

Committee member model for the committee_member table.

Tracks individual Constitutional Committee members, their terms, and expiration dates for Conway era governance.

`CommitteeRegistration` ¶

Bases: DBSyncBase

Committee registration model for the committee_registration table.

Tracks Constitutional Committee member registrations including hot key delegation for Conway era governance.

`CommitteeState` ¶

Bases: str, Enum

Constitutional committee states.

`Constitution` ¶

Bases: DBSyncBase

Constitution model for the constitution table.

Represents the Cardano Constitution and its updates through governance actions in the Conway era.

`DrepDistr` ¶

Bases: DBSyncBase

DRep distribution model for the drep_distr table.

Tracks the stake distribution delegated to each DRep for voting power calculations in Conway era governance.

`DrepHash` ¶

Bases: DBSyncBase

DRep hash model for the drep_hash table.

Stores the hash identifiers for Delegated Representatives (DReps). DReps are entities that can receive voting power delegation from Ada holders for governance decisions in the Conway era.

`DrepRegistration` ¶

Bases: DBSyncBase

DRep registration model for the drep_registration table.

Tracks DRep registration certificates including deposits, anchors, and voting metadata for Conway era governance.

`EpochState` ¶

Bases: DBSyncBase

Epoch state model for the epoch_state table.

Captures governance state snapshots at epoch boundaries including committee composition, DRep distributions, and active proposals.

`GovActionProposal` ¶

Bases: DBSyncBase

Governance action proposal model for the gov_action_proposal table.

Represents all types of governance action proposals in Conway era, including parameter changes, hard forks, treasury withdrawals, etc.

`GovActionType` ¶

Bases: str, Enum

Governance action types in Conway era.

`OffChainVoteAuthor` ¶

Bases: DBSyncBase

Off-chain vote author model for the off_chain_vote_author table.

Stores author information for governance metadata.

`OffChainVoteData` ¶

Bases: DBSyncBase

Off-chain vote data model for the off_chain_vote_data table.

Stores metadata for governance votes following CIP-100 and CIP-119 standards.

`OffChainVoteDrepData` ¶

Bases: DBSyncBase

Off-chain vote DRep data model for the off_chain_vote_drep_data table.

Links DReps to their associated off-chain metadata following CIP-119.

`OffChainVoteExternalUpdate` ¶

Bases: DBSyncBase

Off-chain vote external update model for the off_chain_vote_external_update table.

Tracks external updates and corrections to governance metadata.

`OffChainVoteFetchError` ¶

Bases: DBSyncBase

Off-chain vote fetch error model for the off_chain_vote_fetch_error table.

Tracks errors encountered when fetching governance metadata from external URLs. Committee hash model for tracking constitutional committee members.

`OffChainVoteGovActionData` ¶

Bases: DBSyncBase

Off-chain vote governance action data model for the off_chain_vote_gov_action_data table.

Links governance actions to their associated off-chain metadata.

`OffChainVoteReference` ¶

Bases: DBSyncBase

Off-chain vote reference model for the off_chain_vote_reference table.

Stores references and citations in governance metadata.

`TreasuryWithdrawal` ¶

Bases: DBSyncBase

Treasury withdrawal model for the treasury_withdrawal table.

Represents treasury withdrawal governance actions that move Ada from the treasury to specified stake addresses.

`VoteType` ¶

Bases: str, Enum

Vote types for governance actions.

`VotingAnchor` ¶

Bases: DBSyncBase

Voting anchor model for the voting_anchor table.

Stores metadata anchors for governance actions, votes, and other Conway era governance artifacts following CIP-100 standard.

`VotingProcedure` ¶

Bases: DBSyncBase

Voting procedure model for the voting_procedure table.

Tracks votes cast by Constitutional Committee members, DReps, and SPOs on governance actions in Conway era.

Model Relationships¶

Database Schema Overview¶

erDiagram
    Block ||--o{ Transaction : contains
    Transaction ||--o{ TransactionInput : has
    Transaction ||--o{ TransactionOutput : has
    Transaction ||--o{ TxMetadata : has

    StakeAddress ||--o{ StakeRegistration : registers
    StakeAddress ||--o{ Delegation : delegates
    StakeAddress ||--o{ Reward : receives

    PoolHash ||--o{ PoolRegistration : registers
    PoolHash ||--o{ PoolRetirement : retires
    PoolHash ||--o{ Delegation : receives

    MultiAsset ||--o{ MaTxOut : referenced_in
    MultiAsset ||--o{ MaTxMint : minted_in

    Script ||--o{ TransactionOutput : locks
    Script ||--o{ Redeemer : executed_by

Common Relationship Patterns¶

Most models follow consistent relationship patterns:

Foreign Keys: Use _id suffix (e.g., tx_id, block_id)
Self-References: Some models reference themselves for hierarchical data
Many-to-Many: Handled through junction tables or embedded relationships
Optional References: Foreign keys that can be None for conditional relationships

Type System¶

Custom PostgreSQL Types¶

dbsync-py provides custom type handlers for PostgreSQL-specific types:

Python Type	PostgreSQL Type	Description
`Hash28Type`	`hash28type`	28-byte hash values (pool hashes, etc.)
`Hash32Type`	`hash32type`	32-byte hash values (block/tx hashes)
`LovelaceType`	`lovelace`	ADA amounts in Lovelace
`Word31Type`	`word31type`	31-bit unsigned integers
`Word63Type`	`word63type`	63-bit unsigned integers
`Word64Type`	`word64type`	64-bit unsigned integers
`Int65Type`	`int65type`	65-bit signed integers
`Asset32Type`	`asset32type`	Asset identifiers
`TxIndexType`	`txindex`	Transaction indices

Integration with PyCardano¶

Many models provide seamless integration with PyCardano types:

from dbsync.models import Block, Transaction
from pycardano import BlockHeader, TransactionBody

# Convert from database model to PyCardano
block = session.get(Block, block_id)
cardano_header = block.to_pycardano()

# Work with PyCardano objects
tx = session.get(Transaction, tx_id)
cardano_tx_body = tx.to_pycardano()

Models API Reference¶

Base Models¶

dbsync.models.base ¶

DBSyncBase ¶

__repr__() ¶

__table_args__() ¶

__tablename__() ¶

get_column_names() classmethod ¶

to_dict() ¶

update_from_dict(data) ¶

Foundation Models¶

dbsync.models.foundation ¶

ChainMeta ¶

get_network_info() ¶

is_mainnet() ¶

is_testnet() ¶

EventInfo ¶

ExtraMigrations ¶

Blockchain Models¶

dbsync.models.blockchain ¶

Address ¶

Block ¶

Epoch ¶

EpochSyncTime ¶

ReverseIndex ¶

SchemaVersion ¶

__str__() ¶

is_compatible(required_version) ¶

SlotLeader ¶

StakeAddress ¶

Transaction ¶

Transaction Models¶

dbsync.models.transactions ¶

CollateralTransactionInput ¶

CollateralTransactionOutput ¶

Datum ¶

ExtraKeyWitness ¶

ReferenceTransactionInput ¶

ScriptPurposeType ¶

TransactionCbor ¶

TransactionInput ¶

TransactionOutput ¶

TxMetadata ¶

Withdrawal ¶

Staking Models¶

dbsync.models.staking ¶

Delegation ¶

DelegationVote ¶

EpochStake ¶

EpochStakeProgress ¶

Reward ¶

RewardType ¶

StakeDeregistration ¶

StakeRegistration ¶

Pool Models¶

dbsync.models.pools ¶

DelistedPool ¶

OffchainPoolData ¶

OffchainPoolFetchError ¶

PoolHash ¶

PoolMetadataRef ¶

PoolOwner ¶

PoolRelay ¶

PoolRelayType ¶

PoolRetire ¶

PoolStat ¶

PoolUpdate ¶

ReserveUtxo ¶

ReservedPoolTicker ¶

Asset Models¶

dbsync.models.assets ¶

MaTxMint ¶

absolute_quantity property ¶

is_burn property ¶

is_mint property ¶

MaTxOut ¶

quantity_lovelace property ¶

MultiAsset ¶

asset_name_hex property ¶

policy_id_hex property ¶

`dbsync.models.base` ¶

`DBSyncBase` ¶

`repr()` ¶

`__table_args__()` ¶

`tablename()` ¶

`get_column_names()` `classmethod` ¶

`to_dict()` ¶

`update_from_dict(data)` ¶

`dbsync.models.foundation` ¶

`ChainMeta` ¶

`get_network_info()` ¶

`is_mainnet()` ¶

`is_testnet()` ¶

`EventInfo` ¶

`ExtraMigrations` ¶

`dbsync.models.blockchain` ¶

`Address` ¶

`Block` ¶

`Epoch` ¶

`EpochSyncTime` ¶

`ReverseIndex` ¶

`SchemaVersion` ¶

`str()` ¶

`is_compatible(required_version)` ¶

`SlotLeader` ¶

`StakeAddress` ¶

`Transaction` ¶

`dbsync.models.transactions` ¶

`CollateralTransactionInput` ¶

`CollateralTransactionOutput` ¶

`Datum` ¶

`ExtraKeyWitness` ¶

`ReferenceTransactionInput` ¶

`ScriptPurposeType` ¶

`TransactionCbor` ¶

`TransactionInput` ¶

`TransactionOutput` ¶

`TxMetadata` ¶

`Withdrawal` ¶

`dbsync.models.staking` ¶

`Delegation` ¶

`DelegationVote` ¶

`EpochStake` ¶

`EpochStakeProgress` ¶

`Reward` ¶

`RewardType` ¶

`StakeDeregistration` ¶

`StakeRegistration` ¶

`dbsync.models.pools` ¶

`DelistedPool` ¶

`OffchainPoolData` ¶

`OffchainPoolFetchError` ¶

`PoolHash` ¶

`PoolMetadataRef` ¶

`PoolOwner` ¶

`PoolRelay` ¶

`PoolRelayType` ¶

`PoolRetire` ¶

`PoolStat` ¶

`PoolUpdate` ¶

`ReserveUtxo` ¶

`ReservedPoolTicker` ¶

`dbsync.models.assets` ¶

`MaTxMint` ¶

`absolute_quantity` `property` ¶

`is_burn` `property` ¶

`is_mint` `property` ¶

`MaTxOut` ¶

`quantity_lovelace` `property` ¶

`MultiAsset` ¶

`asset_name_hex` `property` ¶

`policy_id_hex` `property` ¶

`to_pycardano_asset_name()` ¶

`to_pycardano_policy_id()` ¶

`generate_cip14_fingerprint(policy_id, asset_name)` ¶

`dbsync.models.scripts` ¶

`CostModel` ¶

`hash_hex` `property` ¶

`is_valid` `property` ¶

`operation_count` `property` ¶