TxBuilder Object Reference
Transaction builder object specifies the spec for the transaction that is to be composed. Cardano Transactions can be composed by writing a JSON object with the following fields in the Transaction Builder of Kuber Playground.
- selections : Array of addresses/utxos that can be used to balance the transaction
- inputs : Utxos being spent in the transaction
- referenceInputs : ReferenceInputs transction fields in the transaction
- outputs : List of outputs created in the transaction
- collaterals : List of collateral inputs in the transaction.
- validityStart : Transaction validFrom in seconds
- validityStartSlot : Transaction validFrom in slots
- validityEnd : Transaction validUntil in seconds
- validityEndSlot : Transaction validUntil in slots
- mint : Minting script and amount in the transaction
- signatures : Additional signatures in the transaction
- fee : Sets transaction fee explicitly.
- changeAddress : Sets Default change address.
- metadata : Transaction metadata
1. selections
: [ string / object ]
Selection consists of a list of utxos/address from which payment is being made. Selection utxos are used if required during balancing.
Note : Utxos can only be the output to PublicKey addresses and not to Script addresses.
Selection item may be one of following format.
- Address string (bech32 or cborHex )
addr...
: All the utxos in the address will be queried and added to selection. - TxIn
- Utxo
2. inputs
: [ string / object ]
Input consists of a list of object thats can have following fields depending on the context in which it's being used.
PubKeyUtxos as input
- TxIn : Kuber will query the utxo details, and add it to transaction input.
- Utxo : Kuber will use the utxos detail without validiting the validity. The utxo will be present in transaction input
- Address bech32 : Wallet address in bech32 format. When address is used, all the utxos in the address will be used as input and spent in the transaction.
- Address CborHex : Wallet address in cbor format. When address is used, all the utxos in the address will be used as input and spent in the transaction.
Script Utxos as input
When spending/redeeming form script utxo, input value should be an object with all of the following fields.
script
: TxIn / PlutusScript . If txIn is provided, the Reference script present in the utxo will be use to determine script code, otherwise, script Object has to be provided.
redeemer
: Datum : Redeemer datum in json format.
datum
: Datum [optional] : Datum matching the datumHash in the utxo. If Inline Datum is present in utxo, datum is not required and is directly fetched from the Utxo.
exUnits
|executionUnits
: Object [optional]:
Specify Execution units values. If not provided, Kuber automatically calculates the execution units and includes it in the transaction. Execution units object must have the following fields: { "steps": "String" Execution units steps "memory": "String" Execution units memory }
3. referenceInputs
: [ string / object ]
Reference inputs are used for referenceData or referenceScripts feature.
- When referenceInput contains datum, it can be accesed from plutus contract,
- When referenceInput contains script, the script need not added in the transaction. It's fetched from the utxo itself. (Note that the txIn has to be set in the
script
field of input)
ReferenceInputs field may be one of the following
- Txin : Kuber will query the utxo details for the txin.
- Utxo : The utxo details will be used as it is provided.
4. outputs
: [ object /string ]
Output object can have following common fields
address
: [ string ][optional if script is present] : Receiver address. Receiver address may be script or public key address. Address may be in bech32 or cborHex format. Ifaddress
is not provided and script is present, address is automatically calculated.e.g: "addr_test1vzzc9nx2lxmu9r7gyd8cyd0dcx0ynh729rpv4c553exs7kgyu9cxl"
e.g: "6136e0cf1e52e05ef92e52c7bc2a04493d6bae481b8acbab12ec4300d7"
value
: Value : Amount to be sent.deductFee
: boolean [ optional ] : If set to true, Fee will be deducted from this output.
addChange
: boolean [ optional ] : If set to true, Change is added to this output. This can be used to make sure that at leastvalue
amount is sent to this output.insuffientUtxoAda
: string [ optional ] : Specify action to perform when output doesn't have min output ada required, as per the protocol parameters. Possible values are- "
error
" [Default] : throw error when utxo doesn't have sufficient ada. - "
increase
" : Increase the ada amount in output to meet the minAda requirement - "
drop
" : Don't include the output in transaction if it doesn't meet the minAda requirement
- "
inlineScript
: SimpleScript / PlutusScript : Script to be inlined in the utxo. The output utxo can be used as referenceScript in future transactions.
Following fields can be present if the Output address is scriptAddress
script
: PlutusScript : If address is not provided, script is used to compute the outputAddress.datumHash
: string [ optional ] : DatumHash in cbor format.datum
: string [ optional ] : Datum of the script output. The datum is by default inlined, It can also be used to calculate datumHash onlyinlineDatum
: boolean [default : true] : If datum is provided, but it should not be inlined, theninlineDatum: false
can be set.
5 collaterals
[ string / object ][ optional]
Collaterals are selected automatically by Kuber using one of the utxos in the selections
.
If required, collaterals list can be set explicitly .
Each Item in the list can be in one of the following form.
- TransactionHash and outputIndex `TxHash#index
- CborHex format of utxo (same format as the one used by cip30
getUtxos
) - Utxo
6. validityStart
: integer
validityStart provides the time in PosixTimeStamp seconds from which the transaction is valid. If validityStart is not provided, it is set to current time.
7. validityStartSlot
: integer
validityStartSlot provides the time slot number from which the transaction is valid. If validityStartSlot is not provided, it is set to current time slot.
8. validityEnd
: integer
validityEnd provides the time in PosixTimeStamp seconds until which the transaction is valid. If validityEnd is not provided, it is set to infinity.
9. validityEndSlot
: integer
validityEndSlot provides the time slot number until which the transaction is valid. If validityEndSlot is not provided, it is set to infinity.
10. mint
: [ object ]
Each object in the mint list must have following keys
amount
{Object} : in amount object, keys represent the tokenName in hexFromat and value is the amount of that token to be minted.e.g.
{ "546f6b656e2331": 1, "546f6b656e2332": 1}
script
{Object} : PlutusScript / SimpleScriptexecutionUnits
: {Object} [Optional] : Specify Execution units values. If not provided, Kuber automatically calculates the executionunits and include it in the transaction{
"steps": (integer) Execution units steps
"memory": (integer) Execution units memory
}
11. signatures
: [ string ]
PubKey Signatures required for usage by Plutus Contract. It must be set when txSignedBy
function constraint is used in Plutus script.
It can be string in one of the following form
- Payment PublicKey Hash hex
- Bech32 Address string
- CBOR Hex format address
12. fee
: integer
- Lovelace
- Fee is calculated automatically, but setting this will set transaction fee explicitly.
13. changeAddress
: string
Default change address. If it's missing, it's selected from one of the selection address. Setting addChange
in any one output will disable this option
14. metadata
: object
Transaction metadata must be a json object with top level integer key label.
Keys in the json shouldn't be longer than 64 bytes length. If the string value in the metadata is longer than 64 bytes length, Kuber will split the string and replace it with array of smaller chunks of the string.
Metadata object example:
{
"420": "content here",
"421": {
"key": "value",
"key": ["value1", "value2"]
}
}
Data types
1. Utxo
Utxo may be String or object.
Utxo String is CBOR hex representation of utxo as per the (cip30
getUtxos
string)Utxo Object may have following keys.
txin TxIn address bech32 or CborHex adress value Value script / referenceScript optional SimpleScript / PlutusScript datum / inlineDatum optional Datum Object datumHash optional datumHash HexString
2. SimpleScript
Simple script obkcct must have key type
identifying the script type.
- type : "all" / "any" / "atleast" / "sig" / "after" / "before"
- ... : Other fields based on type
2.1 BasicScript
SignatureScript : Only the
keyHash
is allowed to perform actionstring "type" "sig" string "keyHash" PublicKeyHash hex string TimeBeforeScript : Transaction is allowed only after the
slot
has passedstring "type" "before" integer "slot" Slot Number TimeAfterScript : Transaction is allowed only until the
slot
string "type" "after" integer "slot" Slot Number
2.2 MultiScripts:
AnyScript: Any One of the script should hold true
string "type" "any" object "scripts" BasicScript / MultiScript AllScript: All the script condition should be met
string "type" "all" object "scripts" BasicScript / MultiScript AnyMScript: M of all the scripts should hold true
string "type" "any" integer "required" No of scriipt that should hold true object "scripts" BasicScript / MultiScript
3. PlutusScript
PlutusScript object represents serialized plutusScript wrapped in text evelope. it has following keys
string | "type" | "PlutuScrpitV1" / "PlutusScriptV2" |
string | "description" | Description for the script. Can be set to empty |
string | "cborHex" | Scrialized cbor hex representation of the script. |
4. Datum
Datum object can recursively be defined to be one of the follows
- Number\
e.g.
{"int": 32}
- Bytes in hex representation\ e.g. `{"bytes": "03a2"}
- List\
e.g.
{"list": [ ...Datum]}
- Map \
e.g.
{"map": { ...,Datum:Datum}}
- DataConstructor\
e.g.
{"constructor": 1, "fields": [ ...Datum]}
5. TxIn
Transaction output identifier.
It may be In one of the following forms
- String
TxHash#index
- Object
- hash : TransactionHash in hex
- index: Transaction output index
6. Value
Value may have one of the following type
integer : Amount in Lovelace
string : String value format. Its extesion over string format of
cardano-cli
.e.g: ada amount : "3A", "3.2Ada", "3.3a", "3ada"
e.g: with single Nft : "3a + b14005d41c24863c570edc85e180cde5eda45bff6c9117ea70856b04.546f6b656e2331"
e.g: with native token : "3000000 + 3 21666f85344ad0f92b47ad3b359d91edc369e51031cb80e649a43434d058bd6a.546f6b656e2332"Note It is possible to use tokenName in UTF-8 instead of hex, but it should be used with caution because the tokenName will be interpreted as Hex if the format is a valid HEX format.
object: ValueMap e.g.
{
"lovelace": 3200000,
"21666f85344ad0f92b47ad3b359d91edc369e51031cb80e649a43434d058bd6a":{
546f6b656e2332: 32
546f6b656e2333: 31
}
}