export interface ReadOnlyTransactionBuilder extends TransactionBuilderBase {
  /**
   * Execute all queued operations and return a transaction result via Promise.
   *
   * Creates fresh state and runs all accumulated ProgramSteps sequentially.
   * Can be called multiple times on the same builder instance with independent results.
   *
   * @returns Promise<TransactionResultBase> which provides query-only methods
   *
   * @since 2.0.0
   * @category completion-methods
   */
  readonly build: (options?: BuildOptions) => Promise<TransactionResultBase>

  /**
   * Execute all queued operations and return a transaction result via Effect.
   *
   * Creates fresh state and runs all accumulated ProgramSteps sequentially.
   * Suitable for Effect-TS compositional workflows and error handling.
   *
   * @returns Effect<TransactionResultBase, ...> which provides query-only methods
   *
   * @since 2.0.0
   * @category completion-methods
   */
  readonly buildEffect: (
    options?: BuildOptions
  ) => Effect.Effect<
    TransactionResultBase,
    TransactionBuilderError | EvaluationError | WalletNew.WalletError | Provider.ProviderError,
    never
  >

  /**
   * Execute all queued operations with explicit error handling via Either.
   *
   * Creates fresh state and runs all accumulated ProgramSteps sequentially.
   * Returns Either<Result, Error> for pattern-matched error recovery.
   *
   * @returns Promise<Either<TransactionResultBase, Error>>
   *
   * @since 2.0.0
   * @category completion-methods
   */
  readonly buildEither: (
    options?: BuildOptions
  ) => Promise<
    Either<
      TransactionResultBase,
      TransactionBuilderError | EvaluationError | WalletNew.WalletError | Provider.ProviderError
    >
  >
}

export interface SigningTransactionBuilder extends TransactionBuilderBase {
  /**
   * Execute all queued operations and return a signing-ready transaction via Promise.
   *
   * Creates fresh state and runs all accumulated ProgramSteps sequentially.
   * Can be called multiple times on the same builder instance with independent results.
   *
   * @returns Promise<SignBuilder> which provides signing capabilities
   *
   * @since 2.0.0
   * @category completion-methods
   */
  readonly build: (options?: BuildOptions) => Promise<SignBuilder>

  /**
   * Execute all queued operations and return a signing-ready transaction via Effect.
   *
   * Creates fresh state and runs all accumulated ProgramSteps sequentially.
   * Suitable for Effect-TS compositional workflows and error handling.
   *
   * @returns Effect<SignBuilder, ...> which provides signing capabilities
   *
   * @since 2.0.0
   * @category completion-methods
   */
  readonly buildEffect: (
    options?: BuildOptions
  ) => Effect.Effect<
    SignBuilder,
    TransactionBuilderError | EvaluationError | WalletNew.WalletError | Provider.ProviderError,
    never
  >

  /**
   * Execute all queued operations with explicit error handling via Either.
   *
   * Creates fresh state and runs all accumulated ProgramSteps sequentially.
   * Returns Either<Result, Error> for pattern-matched error recovery.
   *
   * @returns Promise<Either<SignBuilder, Error>>
   *
   * @since 2.0.0
   * @category completion-methods
   */
  readonly buildEither: (
    options?: BuildOptions
  ) => Promise<
    Either<SignBuilder, TransactionBuilderError | EvaluationError | WalletNew.WalletError | Provider.ProviderError>
  >
}

export type TransactionBuilder = SigningTransactionBuilder | ReadOnlyTransactionBuilder

export interface TransactionBuilderBase {
  /**
   * Append a payment output to the transaction.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category builder-methods
   */
  readonly payToAddress: (params: PayToAddressParams) => this

  /**
   * Specify transaction inputs from provided UTxOs.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category builder-methods
   */
  readonly collectFrom: (params: CollectFromParams) => this

  /**
   * Send all wallet assets to a recipient address.
   *
   * This operation collects all wallet UTxOs and creates a single output
   * containing all assets minus the transaction fee. No change output is created.
   *
   * Use cases:
   * - Draining a wallet completely
   * - Consolidating all UTxOs into a single output
   * - Migrating funds to a new address
   *
   * **Important**: This operation is mutually exclusive with `payToAddress` and `collectFrom`.
   * When `sendAll` is used, all wallet UTxOs are automatically collected and the output
   * is automatically created. Any existing outputs or inputs will cause an error.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * import { Address } from "@evolution-sdk/evolution"
   *
   * const tx = await client
   *   .newTx()
   *   .sendAll({ to: Address.fromBech32("addr1...") })
   *   .build()
   * ```
   *
   * @since 2.0.0
   * @category builder-methods
   */
  readonly sendAll: (params: SendAllParams) => this

  /**
   * Attach a script to the transaction.
   *
   * Scripts must be attached before being referenced by transaction inputs, minting policies,
   * or certificate operations. The script is stored in the builder state and indexed by its hash
   * for efficient lookup during transaction assembly.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * import * as Script from "../../Script.js"
   * import * as NativeScripts from "../../NativeScripts.js"
   *
   * const nativeScript = NativeScripts.makeScriptPubKey(keyHashBytes)
   * const script = Script.fromNativeScript(nativeScript)
   *
   * const tx = await builder
   *   .attachScript({ script })
   *   .mintAssets({ assets: { "<policyId><assetName>": 1000n } })
   *   .build()
   * ```
   *
   * @since 2.0.0
   * @category builder-methods
   */
  readonly attachScript: (params: { script: CoreScript.Script }) => this

  /**
   * Mint or burn native tokens.
   *
   * Minting creates new tokens, burning destroys existing tokens.
   * - Positive amounts: mint new tokens
   * - Negative amounts: burn existing tokens
   *
   * Can be called multiple times; mints are merged by PolicyId and AssetName.
   * If minting from a script policy, provide the redeemer and attach the script via attachScript().
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * // Mint tokens from a native script policy
   * const tx = await builder
   *   .mintAssets({
   *     assets: {
   *       "<policyId><assetName>": 1000n
   *     }
   *   })
   *   .build()
   *
   * // Mint from Plutus script policy with redeemer
   * const tx = await builder
   *   .attachScript(mintingScript)
   *   .mintAssets({
   *     assets: {
   *       "<policyId><assetName>": 1000n
   *     },
   *     redeemer: myRedeemer
   *   })
   *   .build()
   * ```
   *
   * @since 2.0.0
   * @category builder-methods
   */
  readonly mintAssets: (params: MintTokensParams) => this

  /**
   * Add reference inputs to the transaction.
   *
   * Reference inputs allow reading UTxO data (datums, reference scripts) without consuming them.
   * They are commonly used to:
   * - Reference validators/scripts stored on-chain (reduces tx size and fees)
   * - Read datum values without spending the UTxO
   * - Share scripts across multiple transactions
   *
   * Reference scripts incur tiered fees based on size:
   * - Tier 1 (0-25KB): 15 lovelace/byte
   * - Tier 2 (25-50KB): 25 lovelace/byte
   * - Tier 3 (50-200KB): 100 lovelace/byte
   * - Maximum: 200KB total limit
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * import * as UTxO from "../../UTxO.js"
   *
   * // Use reference script stored on-chain instead of attaching to transaction
   * const refScriptUtxo = await provider.getUtxoByTxHash("abc123...")
   *
   * const tx = await builder
   *   .readFrom({ referenceInputs: [refScriptUtxo] })
   *   .collectFrom({ inputs: [scriptUtxo], redeemer: myRedeemer })
   *   .build()
   * ```
   *
   * @since 2.0.0
   * @category builder-methods
   */
  readonly readFrom: (params: ReadFromParams) => this

  /**
   * Register a stake credential on-chain.
   *
   * Creates a stake registration certificate, enabling the credential to delegate
   * to pools and receive rewards. Requires paying a stake key deposit (currently 2 ADA).
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category staking-methods
   */
  readonly registerStake: (params: RegisterStakeParams) => this

  /**
   * Deregister a stake credential from the chain.
   *
   * Removes the stake credential registration and reclaims the deposit.
   * All rewards must be withdrawn before deregistering.
   *
   * For script-controlled credentials, provide a redeemer. The redeemer can use:
   * - **Static**: Direct Data value
   * - **Self**: Callback receiving the indexed certificate
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category staking-methods
   */
  readonly deregisterStake: (params: DeregisterStakeParams) => this

  /**
   * Delegate stake and/or voting power to a pool or DRep.
   *
   * Supports three delegation modes:
   * - **Stake only**: Provide `poolKeyHash` to delegate to a stake pool
   * - **Vote only**: Provide `drep` to delegate governance voting power (Conway)
   * - **Both**: Provide both for combined stake + vote delegation
   *
   * For script-controlled credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @deprecated Use delegateToPool, delegateToDRep, or delegateToPoolAndDRep instead
   * @since 2.0.0
   * @category staking-methods
   */
  readonly delegateTo: (params: DelegateToParams) => this

  /**
   * Delegate stake to a pool.
   *
   * Creates a StakeDelegation certificate to delegate your stake credential
   * to a specific stake pool for earning staking rewards.
   *
   * For script-controlled credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category staking-methods
   */
  readonly delegateToPool: (params: DelegateToPoolParams) => this

  /**
   * Delegate voting power to a DRep.
   *
   * Creates a VoteDelegCert certificate to delegate your governance voting power
   * to a Delegated Representative (Conway era).
   *
   * For script-controlled credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category staking-methods
   */
  readonly delegateToDRep: (params: DelegateToDRepParams) => this

  /**
   * Delegate both stake and voting power.
   *
   * Creates a StakeVoteDelegCert certificate to simultaneously delegate your
   * stake to a pool and your voting power to a DRep (Conway era).
   *
   * For script-controlled credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category staking-methods
   */
  readonly delegateToPoolAndDRep: (params: DelegateToPoolAndDRepParams) => this

  /**
   * Withdraw staking rewards from a stake credential.
   *
   * Withdraws accumulated rewards to the transaction's change address.
   * Use `amount: 0n` to trigger a stake validator without withdrawing rewards
   * (useful for the coordinator pattern).
   *
   * For script-controlled credentials, provide a redeemer. The redeemer can use:
   * - **Static**: Direct Data value
   * - **Self**: Callback receiving the indexed withdrawal
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category staking-methods
   */
  readonly withdraw: (params: WithdrawParams) => this

  /**
   * Register a stake credential and delegate in a single certificate.
   *
   * Combines registration and delegation into one certificate, reducing
   * transaction size and fees. Available in Conway era onwards.
   *
   * Supports three delegation modes:
   * - **Stake only**: Provide `poolKeyHash` to register and delegate to pool
   * - **Vote only**: Provide `drep` to register and delegate voting power
   * - **Both**: Provide both for combined registration + delegation
   *
   * For script-controlled credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category staking-methods
   */
  readonly registerAndDelegateTo: (params: RegisterAndDelegateToParams) => this

  /**
   * Register as a Delegated Representative (DRep).
   *
   * Registers a credential as a DRep for governance voting. Requires paying
   * a DRep deposit. Optionally provide an anchor with metadata URL and hash.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category governance-methods
   */
  readonly registerDRep: (params: RegisterDRepParams) => this

  /**
   * Update DRep metadata anchor.
   *
   * Updates the anchor (metadata URL + hash) for a registered DRep.
   * For script-controlled DRep credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category governance-methods
   */
  readonly updateDRep: (params: UpdateDRepParams) => this

  /**
   * Deregister as a DRep.
   *
   * Removes DRep registration and reclaims the deposit.
   * For script-controlled DRep credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category governance-methods
   */
  readonly deregisterDRep: (params: DeregisterDRepParams) => this

  /**
   * Authorize a committee hot credential.
   *
   * Authorizes a hot credential to act on behalf of a cold committee credential.
   * The cold credential is kept offline for security; the hot credential signs
   * governance actions.
   *
   * For script-controlled cold credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category governance-methods
   */
  readonly authCommitteeHot: (params: AuthCommitteeHotParams) => this

  /**
   * Resign from the constitutional committee.
   *
   * Submits a resignation from committee membership. Optionally provide
   * an anchor with resignation rationale.
   *
   * For script-controlled cold credentials, provide a redeemer.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category governance-methods
   */
  readonly resignCommitteeCold: (params: ResignCommitteeColdParams) => this

  /**
   * Register or update a stake pool.
   *
   * Registers a new stake pool or updates existing pool parameters.
   * Pool parameters include operator key, VRF key, costs, margin, reward account, etc.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category pool-methods
   */
  readonly registerPool: (params: RegisterPoolParams) => this

  /**
   * Retire a stake pool.
   *
   * Announces pool retirement effective at the specified epoch.
   * The pool will continue operating until the retirement epoch.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @since 2.0.0
   * @category pool-methods
   */
  readonly retirePool: (params: RetirePoolParams) => this

  /**
   * Set the transaction validity interval.
   *
   * Configures the time window during which the transaction is valid:
   * - `from`: Transaction is valid after this time (converted to validityIntervalStart slot)
   * - `to`: Transaction expires after this time (converted to ttl slot)
   *
   * Times are Unix timestamps in milliseconds. At least one bound must be specified.
   * For time-locked scripts, `to` is typically required for script evaluation.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * import * as Time from "@evolution-sdk/Time"
   *
   * // Transaction valid for 10 minutes from now
   * const tx = await builder
   *   .setValidity({
   *     from: Time.now(),
   *     to: Time.now() + 600_000n  // 10 minutes
   *   })
   *   .build()
   *
   * // Only set expiration (most common)
   * const tx = await builder
   *   .setValidity({ to: Time.now() + 300_000n })  // 5 minute TTL
   *   .build()
   * ```
   *
   * @since 2.0.0
   * @category validity-methods
   */
  readonly setValidity: (params: ValidityParams) => this

  /**
   * Submit votes on governance actions.
   *
   * Submits voting procedures to vote on governance proposals. Supports multiple
   * voters voting on multiple proposals in a single transaction.
   *
   * For script-controlled voters (DRep, Constitutional Committee member, or stake pool
   * with script credential), provide a redeemer to satisfy the vote purpose validator.
   * The redeemer will be applied to all script voters in the voting procedures.
   *
   * Use VotingProcedures.singleVote() helper for simple cases or construct
   * VotingProcedures directly for complex multi-voter scenarios.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * import * as VotingProcedures from "@evolution-sdk/VotingProcedures"
   * import * as Vote from "@evolution-sdk/Vote"
   * import * as Data from "@evolution-sdk/Data"
   *
   * // Simple single vote with helper
   * await client.newTx()
   *   .vote({
   *     votingProcedures: VotingProcedures.singleVote(
   *       new VotingProcedures.DRepVoter({ credential: myDRepCred }),
   *       govActionId,
   *       new VotingProcedures.VotingProcedure({
   *         vote: Vote.yes(),
   *         anchor: null
   *       })
   *     ),
   *     redeemer: Data.to(new Constr(0, [])) // for script DRep
   *   })
   *   .attachScript({ script: voteScript })
   *   .build()
   *   .then(tx => tx.sign())
   *   .then(tx => tx.submit())
   *
   * // Multiple votes from same voter
   * await client.newTx()
   *   .vote({
   *     votingProcedures: VotingProcedures.multiVote(
   *       new VotingProcedures.DRepVoter({ credential: myDRepCred }),
   *       [
   *         [govActionId1, new VotingProcedures.VotingProcedure({ vote: Vote.yes(), anchor: null })],
   *         [govActionId2, new VotingProcedures.VotingProcedure({ vote: Vote.no(), anchor: null })]
   *       ]
   *     )
   *   })
   *   .build()
   * ```
   *
   * @since 2.0.0
   * @category governance-methods
   */
  readonly vote: (params: VoteParams) => this

  /**
   * Submit a governance action proposal.
   *
   * Submits a governance action proposal to the blockchain.
   * The deposit (govActionDeposit) is automatically fetched from protocol parameters
   * and will be refunded to the specified reward account when the proposal is finalized.
   *
   * Call .propose() multiple times to submit multiple proposals in one transaction.
   * Consistent with .registerStake() and .registerDRep() - no manual deposit handling.
   *
   * The deposit amount is automatically deducted during transaction balancing.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * import * as GovernanceAction from "@evolution-sdk/GovernanceAction"
   * import * as RewardAccount from "@evolution-sdk/RewardAccount"
   *
   * // Submit single proposal (deposit auto-fetched)
   * await client.newTx()
   *   .propose({
   *     governanceAction: new GovernanceAction.InfoAction({}),
   *     rewardAccount: myRewardAccount,
   *     anchor: myAnchor // or null
   *   })
   *   .build()
   *   .then(tx => tx.sign())
   *   .then(tx => tx.submit())
   *
   * // Multiple proposals in one transaction
   * await client.newTx()
   *   .propose({
   *     governanceAction: new GovernanceAction.InfoAction({}),
   *     rewardAccount: myRewardAccount,
   *     anchor: null
   *   })
   *   .propose({
   *     governanceAction: new GovernanceAction.NoConfidenceAction({ govActionId: null }),
   *     rewardAccount: myRewardAccount,
   *     anchor: myOtherAnchor
   *   })
   *   .build()
   *   .then(tx => tx.sign())
   *   .then(tx => tx.submit())
   * ```
   *
   * @since 2.0.0
   * @category governance-methods
   */
  readonly propose: (params: ProposeParams) => this

  /**
   * Add a required signer to the transaction.
   *
   * Adds a key hash to the transaction's requiredSigners field. This is used to
   * require specific key signatures even when those keys don't control inputs.
   * Common use cases include:
   * - Multi-sig schemes requiring explicit signature verification
   * - Plutus scripts that check for specific signers in the transaction
   * - Governance transactions requiring DRep or committee member signatures
   *
   * Duplicate key hashes are automatically deduplicated.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * import * as KeyHash from "@evolution-sdk/KeyHash"
   * import * as Address from "@evolution-sdk/Address"
   *
   * // Add signer from address credential
   * const address = Address.fromBech32("addr_test1...")
   * const cred = address.paymentCredential
   * if (cred._tag === "KeyHash") {
   *   const tx = await builder
   *     .addSigner({ keyHash: cred })
   *     .build()
   * }
   * ```
   *
   * @since 2.0.0
   * @category builder-methods
   */
  readonly addSigner: (params: AddSignerParams) => this

  /**
   * Attach metadata to the transaction.
   *
   * Metadata is stored in the auxiliary data section and identified by numeric labels
   * following the CIP-10 standard. Common use cases include:
   * - Transaction messages/comments (label 674, CIP-20)
   * - NFT metadata (label 721, CIP-25)
   * - Royalty information (label 777, CIP-27)
   * - DApp-specific data
   *
   * Multiple metadata entries with different labels can be attached by calling this
   * method multiple times. The same label cannot be used twice.
   *
   * Queues a deferred operation that will be executed when build() is called.
   * Returns the same builder for method chaining.
   *
   * @example
   * ```typescript
   * import { fromEntries } from "@evolution-sdk/evolution/TransactionMetadatum"
   *
   * // Attach a simple message (CIP-20)
   * const tx = await builder
   *   .payToAddress({ address, assets: { lovelace: 2_000_000n } })
   *   .attachMetadata({ label: 674n, metadata: "Hello, Cardano!" })
   *   .build()
   *
   * // Attach NFT metadata (CIP-25)
   * const nftMetadata = fromEntries([
   *   ["name", "My NFT #42"],
   *   ["image", "ipfs://Qm..."]
   * ])
   * const tx = await builder
   *   .mintAssets({ assets: { [policyId + assetName]: 1n } })
   *   .attachMetadata({ label: 721n, metadata: nftMetadata })
   *   .build()
   * ```
   *
   * @since 2.0.0
   * @category metadata-methods
   */
  readonly attachMetadata: (params: AttachMetadataParams) => this

  // ============================================================================
  // Composition Methods
  // ============================================================================

  /**
   * Compose this builder with another builder's accumulated operations.
   *
   * Merges all queued operations from another transaction builder into this one.
   * The other builder's programs are captured at compose time and will be executed
   * when build() is called on this builder.
   *
   * This enables modular transaction building where common patterns can be
   * encapsulated in reusable builder fragments.
   *
   * **Important**: Composition is one-way - changes to the other builder after
   * compose() is called will not affect this builder.
   *
   * @example
   * ```typescript
   * // Create reusable builder for common operations
   * const mintBuilder = builder
   *   .mintAssets({ policyId, assets: { tokenName: 1n }, redeemer })
   *   .attachScript({ script: mintingPolicy })
   *
   * // Compose into a transaction that also pays to an address
   * const tx = await builder
   *   .payToAddress({ address, assets: { lovelace: 5_000_000n } })
   *   .compose(mintBuilder)
   *   .build()
   *
   * // Compose multiple builders
   * const fullTx = await builder
   *   .compose(mintBuilder)
   *   .compose(metadataBuilder)
   *   .compose(certBuilder)
   *   .build()
   * ```
   *
   * @param other - Another transaction builder whose operations will be merged
   * @returns The same builder for method chaining
   *
   * @since 2.0.0
   * @category composition-methods
   */
  readonly compose: (other: TransactionBuilder) => this

  /**
   * Get a snapshot of the accumulated programs.
   *
   * Returns a read-only copy of all queued operations that have been added
   * to this builder. Useful for inspection, debugging, or advanced composition patterns.
   *
   * @returns Read-only array of accumulated program steps
   *
   * @since 2.0.0
   * @category composition-methods
   */
  readonly getPrograms: () => ReadonlyArray<ProgramStep>

  // ============================================================================
  // Transaction Chaining Methods
  // ============================================================================

  /**
   * Execute transaction build and return consumed/available UTxOs for chaining.
   *
   * Runs the full build pipeline (coin selection, fee calculation, evaluation) and returns
   * which UTxOs were consumed and which remain available for subsequent transactions.
   * Use this when building multiple dependent transactions in sequence.
   *
   * @returns Promise<ChainResult> with consumed and available UTxOs
   *
   * @example
   * ```typescript
   * // Build first transaction, get remaining UTxOs
   * const tx1 = await builder
   *   .payTo({ address, value: { lovelace: 5_000_000n } })
   *   .build({ availableUtxos: walletUtxos })
   *
   * // Build second transaction using remaining UTxOs from chainResult
   * const tx2 = await builder
   *   .payTo({ address, value: { lovelace: 3_000_000n } })
   *   .build({ availableUtxos: tx1.chainResult().available })
   * ```
   *
   * @since 2.0.0
   * @category chaining-methods
   */
}

export interface ProtocolParameters {
  /** Coefficient for linear fee calculation (minFeeA) */
  minFeeCoefficient: bigint

  /** Constant for linear fee calculation (minFeeB) */
  minFeeConstant: bigint

  /** Minimum ADA per UTxO byte (for future change output validation) */
  coinsPerUtxoByte: bigint

  /** Maximum transaction size in bytes */
  maxTxSize: number

  /** Price per memory unit for script execution (optional, for ExUnits cost calculation) */
  priceMem?: number

  /** Price per CPU step for script execution (optional, for ExUnits cost calculation) */
  priceStep?: number

  /** Cost per byte for reference scripts (Conway-era, default 44) */
  minFeeRefScriptCostPerByte?: number

  // Future fields for advanced features:
  // maxBlockHeaderSize?: number
  // maxTxExecutionUnits?: ExUnits
  // maxBlockExecutionUnits?: ExUnits
  // collateralPercentage?: number
  // maxCollateralInputs?: number
}

export interface TxBuilderConfig {
  /**
   * Optional wallet provides:
   * - Change address via wallet.Effect.address()
   * - Available UTxOs via wallet.Effect.address() + provider.Effect.getUtxos()
   * - Signing capability via wallet.Effect.signTx() (SigningWallet and ApiWallet only)
   *
   * When provided: Automatic change address and UTxO resolution.
   * When omitted: Must provide changeAddress and availableUtxos in BuildOptions.
   *
   * ReadOnlyWallet: For read-only clients that can build but not sign transactions.
   * SigningWallet/ApiWallet: For signing clients with full transaction signing capability.
   *
   * Override per-build via BuildOptions.changeAddress and BuildOptions.availableUtxos.
   */
  readonly wallet?: WalletNew.SigningWallet | WalletNew.ApiWallet | WalletNew.ReadOnlyWallet

  /**
   * Optional provider for:
   * - Fetching UTxOs for the wallet's address (provider.Effect.getUtxos)
   * - Transaction submission (provider.Effect.submitTx)
   * - Protocol parameters
   *
   * Works together with wallet to provide everything needed for transaction building.
   * When wallet is omitted, provider is only used if you call provider methods directly.
   */
  readonly provider?: Provider.Provider

  /**
   * Network type for slot configuration in script evaluation.
   *
   * Used to determine the correct slot configuration when evaluating Plutus scripts.
   * Each network has different genesis times and slot configurations.
   *
   * Options:
   * - `"Mainnet"`: Production network
   * - `"Preview"`: Preview testnet
   * - `"Preprod"`: Pre-production testnet
   * - `"Custom"`: Custom network (emulator/devnet) - requires slotConfig
   *
   * When omitted, defaults to "Mainnet".
   *
   * @default "Mainnet"
   * @since 2.0.0
   */
  readonly network?: Network.Network

  /**
   * Custom slot configuration for the network.
   *
   * Slot configuration defines the relationship between slots and Unix time,
   * which is required for:
   * - UPLC evaluation of time-based validators
   * - Converting validity bounds (from/to) from Unix time to slots
   *
   * By default, slot config is determined from the network (mainnet/preview/preprod).
   * Set this for custom networks (devnet, emulator, private chains).
   *
   * Priority: BuildOptions.slotConfig > TxBuilderConfig.slotConfig > SLOT_CONFIG_NETWORK[network]
   *
   * Use cases:
   * - Devnet with custom genesis time
   * - Emulator with specific slot configuration
   * - Private networks with custom parameters
   *
   * Example:
   * ```typescript
   * makeTxBuilder({
   *   slotConfig: {
   *     zeroTime: clusterGenesisTime,
   *     zeroSlot: 0n,
   *     slotLength: 1000 // 1 second per slot
   *   },
   *   wallet,
   *   provider
   * })
   * ```
   *
   * @since 2.0.0
   */
  readonly slotConfig?: Time.SlotConfig

  // Future fields:
  // readonly costModels?: Uint8Array // Cost models for script evaluation
}

export declare function makeTxBuilder<
  W extends WalletNew.SigningWallet | WalletNew.ApiWallet | WalletNew.ReadOnlyWallet | undefined
>(config: Partial<TxBuilderConfig> & { wallet?: W }): TxBuilderResultType<W>

export declare class AvailableUtxosTag

export declare class BuildOptionsTag

export declare class ChangeAddressTag

export declare class FullProtocolParametersTag

export declare class ProtocolParametersTag

export declare class TxBuilderConfigTag

export declare class TxContext

export declare class EvaluationError

export interface ScriptFailure {
  /** Redeemer purpose: "spend", "mint", "withdraw", "publish" */
  readonly purpose: string
  /** Index within the purpose category */
  readonly index: number
  /** User-provided label for debugging (from operation params) */
  readonly label?: string
  /** Key used internally to track this redeemer (e.g., "txHash#index" for spend) */
  readonly redeemerKey?: string
  /** Script hash if available */
  readonly scriptHash?: string
  /** UTxO reference for spend redeemers */
  readonly utxoRef?: string
  /** Credential hash for withdraw/cert redeemers */
  readonly credential?: string
  /** Policy ID for mint redeemers */
  readonly policyId?: string
  /** Validation error message from the script */
  readonly validationError: string
  /** Execution traces emitted by the script */
  readonly traces: ReadonlyArray<string>
}

export declare class TransactionBuilderError

export interface ChainResult {
  /** UTxOs consumed from availableUtxos by coin selection */
  readonly consumed: ReadonlyArray<CoreUTxO.UTxO>
  /** Available UTxOs: remaining unspent + newly created (with computed txHash) */
  readonly available: ReadonlyArray<CoreUTxO.UTxO>
  /** Pre-computed transaction hash (blake2b-256 of transaction body) */
  readonly txHash: string
}

export interface EvaluationContext {
  /** Cost models for script evaluation */
  readonly costModels: CostModel.CostModels
  /** Maximum execution steps allowed */
  readonly maxTxExSteps: bigint
  /** Maximum execution memory allowed */
  readonly maxTxExMem: bigint
  /** Slot configuration for time-based operations */
  readonly slotConfig: {
    readonly zeroTime: bigint
    readonly zeroSlot: bigint
    readonly slotLength: number
  }
}

export interface Evaluator {
  /**
   * Evaluate transaction scripts and return execution units.
   *
   * @since 2.0.0
   * @category methods
   */
  evaluate: (
    tx: Transaction.Transaction,
    additionalUtxos: ReadonlyArray<CoreUTxO.UTxO> | undefined,
    context: EvaluationContext
  ) => Effect.Effect<ReadonlyArray<EvalRedeemer>, EvaluationError>
}

export interface DeferredRedeemerData {
  readonly tag: "spend" | "mint" | "cert" | "reward" | "vote"
  readonly deferred: DeferredRedeemer
  readonly exUnits?: {
    readonly mem: bigint
    readonly steps: bigint
  }
  /** Optional label for debugging - identifies this redeemer in error messages */
  readonly label?: string
}

export interface RedeemerData {
  readonly tag: "spend" | "mint" | "cert" | "reward" | "vote"
  readonly data: PlutusData.Data
  readonly exUnits?: {
    // Optional: from script evaluation
    readonly mem: bigint
    readonly steps: bigint
  }
  /** Optional label for debugging - identifies this redeemer in error messages */
  readonly label?: string
}

export interface TxBuilderState {
  readonly selectedUtxos: ReadonlyArray<CoreUTxO.UTxO> // Core UTxO type
  readonly outputs: ReadonlyArray<TxOut.TransactionOutput> // Transaction outputs (no txHash/outputIndex yet)
  readonly scripts: Map<string, CoreScript.Script> // Scripts attached to the transaction
  readonly totalOutputAssets: CoreAssets.Assets // Asset totals for balancing
  readonly totalInputAssets: CoreAssets.Assets // Asset totals for balancing
  readonly redeemers: Map<string, RedeemerData> // Resolved redeemer data (static mode)
  readonly deferredRedeemers: Map<string, DeferredRedeemerData> // Deferred redeemers (self/batch mode)
  readonly referenceInputs: ReadonlyArray<CoreUTxO.UTxO> // Reference inputs (UTxOs with reference scripts)
  readonly certificates: ReadonlyArray<Certificate.Certificate> // Certificates for staking operations
  readonly withdrawals: Map<RewardAccount.RewardAccount, bigint> // Withdrawal amounts by reward account
  readonly poolDeposits: Map<string, bigint> // Pool deposits keyed by pool key hash
  readonly mint?: Mint.Mint // Assets being minted/burned (positive = mint, negative = burn)
  readonly votingProcedures?: VotingProcedures.VotingProcedures // Voting procedures for governance actions (Conway)
  readonly proposalProcedures?: ProposalProcedures.ProposalProcedures // Proposal procedures for governance actions (Conway)
  readonly collateral?: {
    // Collateral data for script transactions
    readonly inputs: ReadonlyArray<CoreUTxO.UTxO>
    readonly totalAmount: bigint
    readonly returnOutput?: TxOut.TransactionOutput // Optional: only if there are leftover assets
  }
  readonly validity?: {
    // Transaction validity interval (Unix times, converted to slots during assembly)
    readonly from?: Time.UnixTime // validityIntervalStart
    readonly to?: Time.UnixTime // ttl
  }
  readonly requiredSigners: ReadonlyArray<KeyHash.KeyHash> // Extra signers required (for script validation)
  readonly auxiliaryData?: AuxiliaryData.AuxiliaryData // Auxiliary data (metadata, scripts, etc.)
  readonly sendAllTo?: CoreAddress.Address // Target address for sendAll operation
}

type ProgramStep = Effect.Effect<void, TransactionBuilderError, TxContext | TxBuilderConfigTag>

export type ProgramStep = Effect.Effect<void, TransactionBuilderError, TxContext | TxBuilderConfigTag>

export interface BuildOptions {
  /**
   * Override protocol parameters for this specific transaction build.
   *
   * By default, fetches from provider during build().
   * Provide this to use different protocol parameters for testing or special cases.
   *
   * Use cases:
   * - Testing with different fee parameters
   * - Simulating future protocol changes
   * - Using cached parameters to avoid provider fetch
   *
   * Example:
   * ```typescript
   * // Test with custom fee parameters
   * builder.build({
   *   protocolParameters: { ...params, minFeeCoefficient: 50n, minFeeConstant: 200000n }
   * })
   * ```
   *
   * @since 2.0.0
   */
  readonly protocolParameters?: ProtocolParameters

  /**
   * Coin selection strategy for automatic input selection.
   *
   * Options:
   * - `"largest-first"`: Use largest-first algorithm (DEFAULT)
   * - `"random-improve"`: Use random-improve algorithm (not yet implemented)
   * - `"optimal"`: Use optimal algorithm (not yet implemented)
   * - Custom function: Provide your own CoinSelectionFunction
   * - `undefined`: Use default (largest-first)
   *
   * Coin selection runs after programs execute and automatically
   * selects UTxOs to cover required outputs + fees. UTxOs already collected
   * via collectFrom() are excluded to prevent double-spending.
   *
   * To disable coin selection entirely, ensure all inputs are provided via collectFrom().
   *
   * @default "largest-first"
   */
  readonly coinSelection?: CoinSelectionAlgorithm | CoinSelectionFunction

  // ============================================================================
  // Change Handling Configuration
  // ============================================================================

  /**
   * Override the change address for this specific transaction build.
   *
   * By default, uses wallet.Effect.address() from TxBuilderConfig.
   * Provide this to use a different address for change outputs.
   *
   * Use cases:
   * - Multi-address wallet (use account index 5 for change)
   * - Different change address per transaction
   * - Multi-sig workflows where change address varies
   * - Testing with different addresses
   *
   * Example:
   * ```typescript
   * // Use different account for change
   * builder.build({ changeAddress: wallet.addresses[5] })
   *
   * // Custom Core Address
   * builder.build({ changeAddress: Core.Address.fromBech32("addr_test1...") })
   * ```
   *
   * @since 2.0.0
   */
  readonly changeAddress?: CoreAddress.Address

  /**
   * Override the available UTxOs for this specific transaction build.
   *
   * By default, fetches UTxOs from provider.Effect.getUtxos(wallet.address).
   * Provide this to use a specific set of UTxOs for coin selection.
   *
   * Use cases:
   * - Use UTxOs from specific account index
   * - Pre-filtered UTxO set
   * - Testing with known UTxO set
   * - Multi-address UTxO aggregation
   *
   * Example:
   * ```typescript
   * // Use UTxOs from specific account
   * builder.build({ availableUtxos: utxosFromAccount5 })
   *
   * // Combine UTxOs from multiple addresses
   * builder.build({ availableUtxos: [...utxos1, ...utxos2] })
   * ```
   *
   * @since 2.0.0
   */
  readonly availableUtxos?: ReadonlyArray<CoreUTxO.UTxO>

  /**
   * # Change Handling Strategy Matrix
   * 
   * | unfrack | drainTo | onInsufficientChange | leftover >= minUtxo | Has Native Assets | Result |
   * |---------|---------|---------------------|---------------------|-------------------|--------|
   * | false   | unset   | 'error' (default)   | true                | any               | Single change output created |
   * | false   | unset   | 'error'             | false               | any               | TransactionBuilderError thrown |
   * | false   | unset   | 'burn'              | false               | false             | Leftover becomes extra fee |
   * | false   | unset   | 'burn'              | false               | true              | TransactionBuilderError thrown |
   * | false   | set     | any                 | true                | any               | Single change output created |
   * | false   | set     | any                 | false               | any               | Assets merged into outputs[drainTo] |
   * | true    | unset   | 'error' (default)   | true                | any               | Multiple optimized change outputs |
   * | true    | unset   | 'error'             | false               | any               | TransactionBuilderError thrown |
   * | true    | unset   | 'burn'              | false               | false             | Leftover becomes extra fee |
   * | true    | unset   | 'burn'              | false               | true              | TransactionBuilderError thrown |
   * | true    | set     | any                 | true                | any               | Multiple optimized change outputs |
   * | true    | set     | any                 | false               | any               | Assets merged into outputs[drainTo] |
   * 
   * **Execution Priority:** unfrack attempt → changeOutput >= minUtxo check → drainTo → onInsufficientChange
   * 
   * **Note:** When drainTo is set, onInsufficientChange is never evaluated (unreachable code path)
   * 

  /**
   * Output index to merge leftover assets into as a fallback when change output cannot be created.
   * 
   * This serves as **Fallback #1** in the change handling strategy:
   * 1. Try to create change output (with optional unfracking)
   * 2. If that fails → Use drainTo (if configured)
   * 3. If drainTo not configured → Use onInsufficientChange strategy
   * 
   * Use cases:
   * - Wallet drain: Send maximum to recipient without leaving dust
   * - Multi-output drain: Choose which output receives leftover
   * - Avoiding minimum UTxO: Merge small leftover that can't create valid change
   * 
   * Example:
   * ```typescript
   * builder
   *   .payToAddress({ address: "recipient", assets: { lovelace: 5_000_000n }})
   *   .build({ drainTo: 0 })  // Fallback: leftover goes to recipient
   * ```
   * 
   * @since 2.0.0
   */
  readonly drainTo?: number

  /**
   * Strategy for handling insufficient leftover assets when change output cannot be created.
   *
   * This serves as **Fallback #2** (final fallback) in the change handling strategy:
   * 1. Try to create change output (with optional unfracking)
   * 2. If that fails AND drainTo configured → Drain to that output
   * 3. If that fails OR drainTo not configured → Use this strategy
   *
   * Options:
   * - `'error'` (DEFAULT): Throw error, transaction fails - **SAFE**, prevents fund loss
   * - `'burn'`: Allow leftover to become extra fee - Requires **EXPLICIT** user consent
   *
   * Default behavior is 'error' to prevent accidental loss of funds.
   *
   * Example:
   * ```typescript
   * // Safe (default): Fail if change insufficient
   * .build({ onInsufficientChange: 'error' })
   *
   * // Explicit consent to burn leftover as fee
   * .build({ onInsufficientChange: 'burn' })
   * ```
   *
   * @default 'error'
   * @since 2.0.0
   */
  readonly onInsufficientChange?: "error" | "burn"

  /**
   * Script evaluator for Plutus script execution costs.
   *
   * If provided, replaces the default provider-based evaluation.
   * Use `createUPLCEvaluator()` for UPLC libraries, or implement `Evaluator` directly.
   *
   * @since 2.0.0
   */
  readonly evaluator?: Evaluator

  /**
   * Pass additional UTxOs to provider-based evaluators.
   *
   * By default, provider evaluators (Ogmios, Blockfrost) don't receive additionalUtxos
   * because they can resolve UTxOs from the chain, and passing them causes
   * "OverlappingAdditionalUtxo" errors.
   *
   * Set to `true` for edge cases where you need to evaluate with UTxOs that
   * are not yet on chain (e.g., chained transactions, emulator scenarios).
   *
   * Note: This option has no effect on custom evaluators (Aiken, Scalus) which
   * always receive additionalUtxos since they cannot resolve from chain.
   *
   * @default false
   * @since 2.0.0
   */
  readonly passAdditionalUtxos?: boolean

  /**
   * Format for encoding redeemers in the script data hash.
   *
   * - `"array"` (DEFAULT): Conway-era format, redeemers encoded as array
   * - `"map"`: Babbage-era format, redeemers encoded as map
   *
   * Use `"map"` for Babbage compatibility or debugging.
   *
   * @default "array"
   * @since 2.0.0
   */
  readonly scriptDataFormat?: "array" | "map"

  /**
   * Custom slot configuration for script evaluation.
   *
   * By default, slot config is determined from the network (mainnet/preview/preprod).
   * Provide this to override for custom networks (emulator, devnet, etc.).
   *
   * The slot configuration defines the relationship between slots and Unix time,
   * which is required for UPLC evaluation of time-based validators.
   *
   * Use cases:
   * - Emulator with custom genesis time
   * - Development network with different slot configuration
   * - Testing with specific time scenarios
   *
   * Example:
   * ```typescript
   * // For custom emulator
   * builder.build({
   *   slotConfig: {
   *     zeroTime: 1234567890000n,
   *     zeroSlot: 0n,
   *     slotLength: 1000
   *   }
   * })
   * ```
   *
   * @since 2.0.0
   */
  readonly slotConfig?: Time.SlotConfig

  /**
   * Amount to set as collateral return output (in lovelace).
   *
   * Used for Plutus script transactions to cover potential script execution failures.
   * If not provided, defaults to 5 ADA (5_000_000 lovelace).
   *
   * @default 5_000_000n
   * @since 2.0.0
   */
  readonly setCollateral?: bigint

  /**
   * Unfrack: Optimize wallet UTxO structure
   *
   * Implements Unfrack.It principles for efficient wallet management:
   * - Token bundling: Group tokens into optimally-sized UTxOs
   * - ADA optimization: Roll up or subdivide ADA-only UTxOs
   *
   * Works as an **enhancement** to change output creation. When enabled:
   * - Change output will be split into multiple optimized UTxOs
   * - If unfracking fails (insufficient ADA), falls back to drainTo or onInsufficientChange
   *
   * Named in respect to the Unfrack.It open source community
   */
  readonly unfrack?: UnfrackOptions

  /**
   * Enable debug logging during transaction build.
   *
   * When `true`, applies pretty logger with DEBUG level:
   * - Coin selection details
   * - Change creation steps
   * - Fee calculation progress
   * - Fiber termination messages with stack traces
   *
   * When `false` or `undefined` (default), no log layer is applied:
   * - Effect.logDebug calls are not visible
   * - Fiber termination logs are suppressed
   * - Clean output for production use
   *
   * @default false
   * @since 2.0.0
   */
  readonly debug?: boolean
}

export declare class PhaseContextTag

export interface UnfrackAdaOptions {
  /**
   * Roll Up ADA-Only: Intentionally collect and consolidate ADA-only UTxOs
   * @default false (only collect when needed for change)
   */
  readonly rollUpAdaOnly?: boolean

  /**
   * Subdivide Leftover ADA: If leftover ADA > threshold, split into multiple UTxOs
   * Creates multiple ADA options for future transactions (parallelism)
   * @default 100_000000 (100 ADA)
   */
  readonly subdivideThreshold?: Coin.Coin

  /**
   * Subdivision percentages for leftover ADA
   * Must sum to 100
   * @default [50, 15, 10, 10, 5, 5, 5]
   */
  readonly subdividePercentages?: ReadonlyArray<number>

  /**
   * Maximum ADA-only UTxOs to consolidate in one transaction.
   * NOTE: Not yet implemented. Will hook into coin selection to merge dust UTxOs.
   * @default 20
   */
  readonly maxUtxosToConsolidate?: number
}

export interface UnfrackOptions {
  readonly tokens?: UnfrackTokenOptions
  readonly ada?: UnfrackAdaOptions
}

export interface UnfrackTokenOptions {
  /**
   * Bundle Size: Number of tokens to collect per UTxO
   * - Same policy: up to bundleSize tokens together
   * - Multiple policies: up to bundleSize/2 tokens from different policies
   * - Policy exceeds bundle: split into multiple UTxOs
   * @default 10
   */
  readonly bundleSize?: number

  /**
   * Isolate Fungible Behavior: Place each fungible token policy on its own UTxO
   * Decreases fees and makes DEX interactions easier
   * @default false
   */
  readonly isolateFungibles?: boolean

  /**
   * Group NFTs by Policy: Separate NFTs onto policy-specific UTxOs
   * Decreases fees for marketplaces, staking, sending
   * @default false
   */
  readonly groupNftsByPolicy?: boolean
}