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.

• utxo : TxIn / Utxo . Utxo or txIn to be added to input

• 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. If address 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 least value 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 only

• inlineDatum : boolean [default : true] : If datum is provided, but it should not be inlined, then inlineDatum: 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 / SimpleScript

• executionUnits : {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 action

  string	"type"	"sig"
  string	"keyHash"	PublicKeyHash hex string

• TimeBeforeScript : Transaction is allowed only after the slot has passed

  string	"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
    }
  }