Balance overview

Balance Verification Phase

Verifies that transaction inputs exactly equal outputs + change + fees. Handles three scenarios: balanced (complete), shortfall (retry), or excess (burn/drain).

Added in v2.0.0

Table of contents

• utilities
  • calculateCertificateBalance
  • calculateProposalDeposits
  • calculateWithdrawals
• utils
  • executeBalance

utilities

calculateCertificateBalance

Calculate certificate deposits and refunds from a list of certificates.

Certificates with deposits (money OUT):

• RegCert: Stake registration deposit
• RegDrepCert: DRep registration deposit
• RegPoolCert: Pool registration deposit (PoolRegistration)
• StakeRegDelegCert: Combined stake registration + delegation deposit
• VoteRegDelegCert: Combined vote registration + delegation deposit
• StakeVoteRegDelegCert: Combined stake + vote registration + delegation deposit

Certificates with refunds (money IN):

• UnregCert: Stake deregistration refund
• UnregDrepCert: DRep deregistration refund
• PoolRetirement: Pool retirement (no refund in Conway era; pool deposits are burned)

Signature

export declare const calculateCertificateBalance: (
  certificates: ReadonlyArray<Certificate.Certificate>,
  poolDeposits: ReadonlyMap<string, bigint>
) => { deposits: bigint; refunds: bigint }

Added in v2.0.0

calculateProposalDeposits

Calculate total proposal deposits from proposal procedures.

Each proposal requires a deposit (govActionDeposit) which is tracked in the ProposalProcedure structure. This deposit is deducted from transaction inputs during balancing.

Signature

export declare const calculateProposalDeposits: (
  proposalProcedures: { readonly procedures: ReadonlyArray<{ readonly deposit: bigint }> } | undefined
) => bigint

Added in v2.0.0

calculateWithdrawals

Calculate total withdrawal amount from a map of reward accounts to withdrawal amounts.

Signature

export declare const calculateWithdrawals: (withdrawals: ReadonlyMap<unknown, bigint>) => bigint

Added in v2.0.0

utils

executeBalance

Balance Verification Phase

Verifies that transaction inputs exactly equal outputs + change + fees. Handles three scenarios: balanced (complete), shortfall (retry), or excess (burn/drain).

Decision Flow:

Calculate Delta: inputs - outputs - change - fees
  ↓
Delta == 0?
  ├─ YES → BALANCED: Complete transaction
  └─ NO → Check delta value
          ↓
       Delta > 0 (Excess)?
          ├─ YES → Check strategy
          │         ├─ DrainTo mode? → Merge into target output → Complete
          │         ├─ Burn mode? → Accept as implicit fee → Complete
          │         └─ Neither? → ERROR (bug in change creation)
          └─ NO (Delta < 0, Shortfall) → Return to changeCreation

Key Principles:

• Delta must equal exactly 0 (balanced) or negative (shortfall) in normal flow
• Positive delta only occurs in burn/drainTo strategies (controlled scenarios)
• Shortfall means change was underestimated; retry with adjusted fee
• DrainTo merges excess into a specified output for exact balancing
• Burn strategy treats excess as implicit fee (leftover becomes network fee)
• Native assets in delta indicate a bug (should never happen with proper change creation)
• This is the final verification gate before transaction completion

Signature

export declare const executeBalance: () => Effect.Effect<
  PhaseResult,
  TransactionBuilderError,
  PhaseContextTag | TxContext | BuildOptionsTag
>