Cardano.Transaction

Types and functions related to on-chain transactions.

type alias Transaction =
{ body : TransactionBody
, witnessSet : WitnessSet
, isValid : Bool
, auxiliaryData : Maybe AuxiliaryData
}

A Cardano transaction.

new : Transaction

Helper for empty [Transaction] initialization.

type alias TransactionBody =
{ inputs : List OutputReference
, outputs : List Output
, fee : Natural
, ttl : Maybe Natural
, certificates : List Certificate
, withdrawals : List ( StakeAddress, Natural )
, update : Maybe Update
, auxiliaryDataHash : Maybe (Bytes Hash)
, validityIntervalStart : Maybe Int
, mint : MultiAsset Integer
, scriptDataHash : Maybe (Bytes ScriptDataHash)
, collateral : List OutputReference
, requiredSigners : List (Bytes CredentialHash)
, networkId : Maybe NetworkId
, collateralReturn : Maybe Output
, totalCollateral : Maybe Int
, referenceInputs : List OutputReference
, votingProcedures :
List ( Voter, List ( ActionId, VotingProcedure ) )
, proposalProcedures : List ProposalProcedure
, currentTreasuryValue : Maybe Natural
, treasuryDonation : Maybe Natural
}

A Cardano transaction body.

newBody : TransactionBody

Helper for empty transaction body initialization.

Phantom type for script data hashes. This is a 32-bytes Blake2b-256 hash.

type alias WitnessSet =
{ vkeywitness : Maybe (List VKeyWitness)
, nativeScripts : Maybe (List NativeScript)
, bootstrapWitness : Maybe (List BootstrapWitness)
, plutusV1Script : Maybe (List (Bytes ScriptCbor))
, plutusData : Maybe (List Data)
, redeemer : Maybe (List Redeemer)
, plutusV2Script : Maybe (List (Bytes ScriptCbor))
, plutusV3Script : Maybe (List (Bytes ScriptCbor))
}

A Cardano transaction witness set.

Pallas alonzo implementation

newWitnessSet : WitnessSet

Helper for empty witness set initialization.

type alias Update =
{ proposedProtocolParameterUpdates :
BytesMap GenesisHash ProtocolParamUpdate
, epoch : Natural
}

Payload to update the protocol parameters at a specific epoch

type alias ScriptContext =
{ transaction : Transaction
, purpose : ScriptPurpose
}

A context given to a script by the Cardano ledger when being executed.

The context contains information about the entire transaction that contains the script. The transaction may also contain other scripts. To distinguish between multiple scripts, the ScriptContext contains a "purpose" identifying the current resource triggering this execution.

= SPMint { policyId : Bytes PolicyId }
| SPSpend OutputReference
| SPWithdrawFrom Credential
| SPPublish Certificate

Characterizes the kind of script being executed and the associated resource.

= StakeRegistrationCert { delegator : Credential }
| StakeDeregistrationCert { delegator : Credential }
| StakeDelegationCert
{ delegator : Credential
, poolId : Bytes Id
}
| PoolRegistrationCert Params
| PoolRetirementCert
{ poolId : Bytes Id
, epoch : Natural
}
| GenesisKeyDelegationCert
{ genesisHash : Bytes GenesisHash
, genesisDelegateHash : Bytes GenesisDelegateHash
, vrfKeyHash : Bytes VrfKeyHash
}
| MoveInstantaneousRewardsCert MoveInstantaneousReward
| RegCert
{ delegator : Credential
, deposit : Natural
}
| UnregCert
{ delegator : Credential
, refund : Natural
}
| VoteDelegCert
{ delegator : Credential
, drep : Drep
}
| StakeVoteDelegCert
{ delegator : Credential
, poolId : Bytes Id
, drep : Drep
}
| StakeRegDelegCert
{ delegator : Credential
, poolId : Bytes Id
, deposit : Natural
}
| VoteRegDelegCert
{ delegator : Credential
, drep : Drep
, deposit : Natural
}
| StakeVoteRegDelegCert
{ delegator : Credential
, poolId : Bytes Id
, drep : Drep
, deposit : Natural
}
| AuthCommitteeHotCert
{ committeeColdCredential : Credential
, committeeHotCredential : Credential
}
| ResignCommitteeColdCert
{ committeeColdCredential : Credential
, anchor : Maybe Anchor
}
| RegDrepCert
{ drepCredential : Credential
, deposit : Natural
, anchor : Maybe Anchor
}
| UnregDrepCert
{ drepCredential : Credential
, refund : Natural
}
| UpdateDrepCert
{ drepCredential : Credential
, anchor : Maybe Anchor
}

An on-chain certificate attesting of some operation. Publishing certificates triggers different kind of rules. Most of the time, they require signatures from specific keys.

Phantom type for Genesis hash. This is a 28-bytes Blake2b-224 hash.

Phantom type for Genesis delegate hash. This is a 28-bytes Blake2b-224 hash.

= Reserves
| Treasury

The source of rewards.

= StakeCredentials (List ( Credential, Natural ))
| OtherAccountingPot Natural

Reward target for a certificate's [MoveInstantaneousReward].

If StakeCredentials, funds are moved to stake credentials, otherwise the funds are given to the other accounting pot.

{ source : RewardSource
, target : RewardTarget
}

Payload for [MoveInstantaneousRewardsCert].

type alias VKeyWitness =
, signature : Bytes Ed25519Signature
}

VKey witness

Compute the 28-bytes Blake2b hash of a public key.

type alias BootstrapWitness =
{ publicKey : Bytes Ed25519PublicKey
, signature : Bytes Ed25519Signature
}

Bootstrap witness

Phantom type for ED25519 public keys, of length 32 bytes.

Phantom type for ED25519 signatures, of length 64 bytes.

Phantom type for [BootstrapWitness] chain code. It has a length of 32 bytes.

Phantom type for [BootstrapWitness] attributes. Bytes of this type can be of any length.

type alias FeeParameters =
{ baseFee : Int
, feePerByte : Int
, scriptExUnitPrice : ExUnitPrices
, refScriptFeeParams : RefScriptFeeParameters
}

Parameters required to compute transaction fees.

{ minFeeRefScriptCostPerByte : Int
, multiplier : RationalNumber
, sizeIncrement : Int
}

Parameters for the costs of referencing scripts.

Full explanation of the formula here: https://github.com/IntersectMBO/cardano-ledger/blob/master/docs/adr/2024-08-14_009-refscripts-fee-change.md

defaultTxFeeParams : FeeParameters

Default values for fee parameters.

FeeParameters
-> { refScriptBytes : Int }
-> Transaction
-> { txSizeFee : Natural
, scriptExecFee : Natural
, refScriptSizeFee : Natural
}

Re-compute fees for a transaction (does not read body.fee).

computeRefScriptFee : RefScriptFeeParameters -> Int -> Natural

Helper function to compute the fees associated with reference script size.

Full explanation of the formula here: https://github.com/IntersectMBO/cardano-ledger/blob/master/docs/adr/2024-08-14_009-refscripts-fee-change.md

tierRefScriptFee = go 0 minFeeRefScriptCostPerByte
  where
    go acc curTierPrice n
      | n < sizeIncrement =
          floor (acc + (n % 1) * curTierPrice)
      | otherwise =
          let acc' = acc + curTierPrice * (sizeIncrement % 1)
           in go acc' (multiplier * curTierPrice) (n - sizeIncrement)
    sizeIncrement = 25600
    multiplier = 1.2
    minFeeRefScriptCostPerByte = 15
computeScriptExecFee : ExUnitPrices -> Transaction -> Natural

Compute the part of the fees of a Transaction related to the execution of scripts in the Plutus VM.

computeTxSizeFee : { a | baseFee : Int, feePerByte : Int } -> Transaction -> Natural

Compute the part of the fees of a Transaction directly related to the Tx size in bytes.

The "baseFee" and "feePerByte" are network parameters.

Estimate the potential saving in transaction fees by passing a script by reference instead of putting inline in the Tx witnesses.

allInputs : Transaction -> RefDict ()

Extract all inputs that are used in the transaction, from inputs, collateral and reference inputs.

Serialize the body and compute the Tx ID.

locateScriptWithHash : Bytes CredentialHash -> List Output -> Maybe ( Int, Reference )

Helper function to locate the index of a script within a list of Outputs.

(Maybe (List VKeyWitness) -> Maybe (List VKeyWitness))
-> Transaction
-> Transaction

Clear all signatures from the witness set of the Tx.

hashScriptData : CostModels -> Transaction -> Bytes ScriptDataHash

Compute the script data hash of the transaction.

The caller must know what versions of Plutus scripts are present in the Tx and provide accordingly the associated cost models.

Script data is serialized in a very specific way to compute the hash. See Conway CDDL format: https://github.com/IntersectMBO/cardano-ledger/blob/676ffc5c3e0dddb2b1ddeb76627541b195fefb5a/eras/conway/impl/cddl-files/conway.cddl#L197

deserialize : Bytes a -> Maybe Transaction

Deserialize a transaction's cbor bytes into a [Transaction]

serialize : Transaction -> Bytes Transaction

Serialize a [Transaction] into cbor bytes

encodeToCbor : Transaction -> Encoder

Encode a Tx to CBOR

decodeWitnessSet : Decoder WitnessSet

Decode a [WitnessSet] from CBOR.

decodeVKeyWitness : Decoder VKeyWitness

Decode from CBOR one VKey witness signature.

encodeVKeyWitness : VKeyWitness -> Encoder

Encode to CBOR one VKey signatures.