Cardano.TxIntent

Building Cardano Transactions with Intents.

Transaction Building Overview

This framework aims to provide intuitive and correct building blocks for transaction building, based on the following aspects of transactions.

  1. Intent: what we want to achieve with this transaction
    • Transfer: send some tokens from somewhere to somewhere else
    • Mint and burn: create and destroy tokens
    • Use a script: provide/spend tokens and data to/from a script
    • Stake management: collect rewards, manage delegations and pool registrations
    • Voting: vote on proposals
    • Propose: make your own proposals
  2. Metadata: additional information
  3. Constraints: what additional constraints do we want to set
    • Temporal validity range: first/last slots when the Tx is valid
  4. Requirements: what is imposed by the protocol
    • Tx fee: depends on size/mem/cpu
    • Hashes: for metadata and script data
    • Collateral: for plutus scripts
    • Signatures: for consuming inputs and scripts requirements

This API revolves around composing intents, then adding metadata and constraints, and finally trying to validate it and auto-populate all requirements.

Code Documentation

RefDict Output
-> List TxIntent
-> Result TxFinalizationError (List TxIntent)

Attempt to balance a transaction with a provided address.

All the missing value from inputs and/or outputs is compensated by adding new intents with the provided address as source and/or destination.

The function may fail while verifying that all references are present in the local state UTxOs.

RefDict Output
-> List TxOtherInfo
-> List TxIntent
-> Result TxFinalizationError TxFinalized

Finalize a transaction before signing and submitting it.

Analyze all intents and perform the following actions:

  • Check the Tx balance
  • Select the input UTxOs with a default coin selection algorithm
  • Evaluate script execution costs with default mainnet parameters
  • Try to find fee payment source automatically and compute automatic Tx fee

The network parameters will be automatically chosen to be:

  • default Mainnet parameters if the guessed fee address is from Mainnet
  • default Preview parameters if the guessed fee address is from a testnet.

Preprod is not supported for this simplified [finalize] function. In case you want more customization, please use [finalizeAdvanced].

{ govState : GovernanceState
, localStateUtxos : RefDict Output
, coinSelectionAlgo : Algorithm
, evalScriptsCosts :
RefDict Output -> Transaction -> Result String (List Redeemer)
, costModels : CostModels
}
-> Fee
-> List TxOtherInfo
-> List TxIntent
-> Result TxFinalizationError TxFinalized

Finalize a transaction before signing and submitting it.

Analyze all intents and perform the following actions:

  • Check the Tx balance
  • Select the input UTxOs with the provided coin selection algorithm
  • Evaluate script execution costs with the provided function
  • Compute Tx fee if set to auto
type alias TxFinalized =
{ tx : Transaction
, expectedSignatures : List (Bytes CredentialHash)
}

Result of the Tx finalization.

The hashes of the credentials expected to provide a signature are provided as an additional artifact of Tx finalization.

= UnableToGuessFeeSource
| UnbalancedIntents
{ inputTotal : Value
, outputTotal : Value
, extraneousInput : Value
, extraneousOutput : Value
}
String
| InsufficientManualFee
{ declared : Natural
, computed : Natural
}
| NotEnoughMinAda String
| InvalidAddress Address String
| InvalidStakeAddress StakeAddress String
| DuplicateVoters (List { voter : String })
| EmptyVotes { voter : String }
| DuplicateMints (List { policyId : String })
| EmptyMint { policyId : String }
| WitnessError Error
| FailedToPerformCoinSelection Error
| CollateralSelectionError Error
| DuplicatedMetadataTags Int
| IncorrectTimeValidityRange String
| UplcVmError String
| GovProposalsNotSupportedInSimpleFinalize
| FailurePleaseReportToElmCardano String

Errors that may happen during Tx finalization.

Provide a default function to convert an error to a human-readable string.

= SendTo Address Value
| SendToOutput Output
| SendToOutputAdvanced (TxContext -> Output)
| Spend SpendSource
| MintBurn
{ policyId : Bytes CredentialHash
, assets : BytesMap AssetName Integer
, scriptWitness : Script
}
| IssueCertificate CertificateIntent
| WithdrawRewards
{ stakeCredential : StakeAddress
, amount : Natural
, scriptWitness : Maybe Script
}
| Vote Voter (List VoteIntent)
| Propose ProposalIntent

Represents different types of transaction intents.

= FromWallet
{ address : Address
, value : Value
, guaranteedUtxos : List OutputReference
}
| FromNativeScript
{ spentInput : OutputReference
, nativeScriptWitness : NativeScript
}
| FromPlutusScript
{ spentInput : OutputReference
, datumWitness : Maybe (Source Data)
, plutusScriptWitness : PlutusScript
}

Represents different sources for spending assets.

= RegisterStake
{ delegator : Credential
, deposit : Natural
}
| UnregisterStake
{ delegator : Credential
, refund : Natural
}
| DelegateStake
{ delegator : Credential
, poolId : Bytes Id
}
| RegisterPool { deposit : Natural } Params
| RetirePool
{ poolId : Bytes Id
, epoch : Natural
}
| RegisterDrep
{ drep : Credential
, deposit : Natural
, info : Maybe Anchor
}
| UnregisterDrep
{ drep : Credential
, refund : Natural
}
| VoteAlwaysAbstain { delegator : Credential }
| VoteAlwaysNoConfidence { delegator : Credential }
| DelegateVotes
{ delegator : Credential
, drep : Credential
}

All intents requiring the on-chain publication of a certificate.

These include stake registration and delegation, stake pool management, and voting or delegating your voting power.

type alias VoteIntent =
{ actionId : ActionId
, vote : Vote
, rationale : Maybe Anchor
}

Governance vote.

type alias ProposalIntent =
{ govAction : ActionProposal
, offchainInfo : Anchor
, deposit : Natural
, depositReturnAccount : StakeAddress
}

Governance action proposal.

= ParameterChange ProtocolParamUpdate
| HardForkInitiation ProtocolVersion
| TreasuryWithdrawals
(List
{ destination : StakeAddress
, amount : Natural
}
)
| NoConfidence
| UpdateCommittee
{ removeMembers : List Credential
, addMembers :
List
{ newMember : Credential
, expirationEpoch : Natural
}
, quorumThreshold : UnitInterval
}
| NewConstitution Constitution
| Info

The different kinds of proposals available for governance.

= TxReferenceInput OutputReference
| TxMetadata
{ tag : Natural
, metadata : Metadatum
}
| TxTimeValidityRange
{ start : Int
, end : Natural
}

Represents additional information for a transaction.

type Fee
= ManualFee
(List
{ paymentSource : Address
, exactFeeAmount : Natural
}
)
| AutoFee { paymentSource : Address }

Configure fees manually or automatically for a transaction.

type alias GovernanceState =
{ guardrailsScript :
Maybe
{ policyId : Bytes PolicyId
, plutusVersion : PlutusVersion
, scriptWitness : Source (Bytes ScriptCbor)
}
, lastEnactedCommitteeAction : Maybe ActionId
, lastEnactedConstitutionAction : Maybe ActionId
, lastEnactedHardForkAction : Maybe ActionId
, lastEnactedProtocolParamUpdateAction : Maybe ActionId
}

Contains pointers to the latest enacted governance actions and to the constitution.

emptyGovernanceState : GovernanceState

Just a helper initialization for when we don’t care about governance proposals.

-> Transaction
-> RefDict Output
-> { updatedState : RefDict Output
, spent : List ( OutputReference, Output )
, created : List ( OutputReference, Output )
}

Update the known local state with the spent and created UTxOs of a given transaction.

elm doc
preview
Open Files
Close Preview
Browse Source
    dmy@2025