Transactions

Create transactions for sending assets.

Send ADA to Addresses

You can chain the component to send to multiple recipients. For each recipients, append:

tx.sendLovelace(address: string, lovelace: string);

.build() construct the transaction and returns a transaction CBOR. Behind the scene, it selects necessary inputs belonging to the wallet, calculate the fee for this transaction and return remaining assets to the change address. Use wallet.signTx() to sign transaction CBOR.

import { Transaction } from '@meshsdk/core';

const tx = new Transaction({ initiator: wallet })
  .sendLovelace(
    'addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr',
    '1000000'
  )
  .sendLovelace(
    'ANOTHER ADDRESS HERE',
    '1500000'
  )
;

const unsignedTx = await tx.build();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
Send ADA to recipients

Add or remove recipients, input the address and the amount ADA to send.

Recipients
Recipient #1
Recipient #2

Send Multiple Assets to Addresses

For each recipients, we define a list of Asset to send:

import type { Asset } from '@meshsdk/core';

let assets: Asset[] = [];
for (const asset of nativeAssets) {
  let thisAsset = {
    unit: '64af286e2ad0df4de2e7de15f8ff5b3d27faecf4ab2757056d860a424d657368546f6b656e',
    quantity: '1',
  };
  assets.push(thisAsset);
}
tx.sendAssets(recipient.address, assets);

We can chain a series of tx.sendAssets() and tx.sendLovelace() to send multiple assets to multiple recipients.

import { Transaction } from '@meshsdk/core';
import type { Asset } from '@meshsdk/core';

const tx = new Transaction({ initiator: wallet })
  .sendLovelace(
    'addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr',
    '1000000'
  )
  .sendAssets(
    'addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr',
    [
      {
        unit: '64af286e2ad0df4de2e7de15f8ff5b3d27faecf4ab2757056d860a424d657368546f6b656e',
        quantity: '1',
      },
    ]
  )
  .sendLovelace(
    'ANOTHER ADDRESS HERE',
    '1500000'
  );

const unsignedTx = await tx.build();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
Send multi-assets to recipients

Add or remove recipients, input the address and the amount ADA to send.

Recipients
Recipient #1
Recipient #2
No wallets installed

Send Assets to Handler

We can get the ADA Handle's address with fetchHandleAddress():

import { KoiosProvider } from '@meshsdk/core';

const koios = new KoiosProvider('api');
const address = await koios.fetchHandleAddress('jingles');

Next, we can create a transactions, for instance, lets send some lovelace to jingles:

import { KoiosProvider, Transaction } from '@meshsdk/core';

const koios = new KoiosProvider('api');

const tx = new Transaction({ initiator: wallet })
  .sendLovelace(
    await koios.fetchHandleAddress('jingles'),
    '1000000'
);

const unsignedTx = await tx.build();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
Send ADA to handler

Note: this demo only works on mainnet.

Recipients
No wallets installed

Set Start and Expire Time

We can define the time-to-live (TTL) for the transaction. TTL is the time limit for our transaction to be included in a blockchain, if it is not in a blockchain by then the transaction will be cancelled. This time limit is defined as slot.

In order to get the slot of the time you wish the transaction would expire, you can use resolveSlotNo. For example, if you would like the transaction to expire in 5 minutes, we can get the slot by doing:

import { resolveSlotNo } from '@meshsdk/core';
let minutes = 5; // add 5 minutes
let nowDateTime = new Date();
let dateTimeAdd5Min = new Date(nowDateTime.getTime() + minutes*60000);
const slot = resolveSlotNo('mainnet', dateTimeAdd5Min.getTime());

Then, we set the TTL with setTimeToExpire and providing the slot, this means that if the transaction is submitted after after slot will not be valid.

const tx = new Transaction({ initiator: wallet });
// do tx.sendLovelace() or any transactions actions
tx.setTimeToExpire(slot)
const unsignedTx = await tx.build();

Likewise, we can set a "validity start interval" for the transaction, where it is the time the transaction will be valid. We can define the start time with setTimeToStart and providing the slot:

const tx = new Transaction({ initiator: wallet });
// do tx.sendLovelace() or any transactions actions
tx.setTimeToStart(slot)
const unsignedTx = await tx.build();

Note that, if you are using a policy locking script, you must define setTimeToExpire before the expiry; otherwise, you will catch the ScriptWitnessNotValidatingUTXOW error.

Set Metadata

Cardano Transaction Metadata allows anyone to embed metadata into transactions, which is then stored in the blockchain. Metadata be a text, specific structured text, number, hash, a combination of that, etc. If the content of metadata should remain secret, then it is the responsibility of the sender to encrypt it. Metadata can act as a confirmation or assurance of authenticity when combined with off-chain infrastructure such as physical identifiers. Metadata have a maximum length, it is limited by the current protocal on the maximum size of a single transaction.

Here are some uses of metadata:

  • Validation and verification. To check and verify external physical objects and legitimate content, for example, coupling with a physical identifier, such as a QR-code, but it's especially beneficial for low-cost supply chain tracking of fast-moving consumer goods.
  • Authentication and attribution. To confirm the authenticity of credentials received from an educational institution or membership group, as metadata can serve as an immutable and always-accessible evidence of certification.
  • Secure record of information. To save vital information, so no one can alter it, and it will last as long as the Cardano blockchain exists.

You can insert metadata into a transaction with setMetadata(key, value). The key is a number, and value is a string.

import { Transaction } from '@meshsdk/core';

const tx = new Transaction({ initiator: wallet });
tx.sendLovelace(
  'addr_test1vpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0c7e4cxr',
  '1000000'
);
tx.setMetadata(0, 'Transaction message');
No wallets installed

Coin Selection

There are two coin selection algorithm, one for selecting lovelace, another for selecting multiple assets.

To select UTXOs for transaction that only requires lovelace, use largestFirst.

largestFirst = (
  lovelace: Quantity, initialUTxOSet: UTxO[], includeTxFees = false,
  { maxTxSize, minFeeA, minFeeB } = DEFAULT_PROTOCOL_PARAMETERS,
): UTxO[]

For example, selecting the UTXOs for sending 10000000 lovelace:

import { largestFirst } from '@meshsdk/core';

const utxos = await wallet.getUtxos();

const costLovelace = '10000000';
const selectedUtxos = largestFirst(costLovelace, utxos, true);

largestFirstMultiAsset allows you to select native assets by defining a Map of required assets.

largestFirstMultiAsset = (
  requestedOutputSet: Map<Unit, Quantity>, initialUTxOSet: UTxO[],
  includeTxFees = false, parameters = DEFAULT_PROTOCOL_PARAMETERS,
): UTxO[]

Although you have use this to specify require lovelace to fulfill this transaction, but if your transaction only required lovelace, the algorithm will exclude all multiasset utxo from the selection, thus you could select the required UTXOs more efficiently.

import { largestFirstMultiAsset } from '@meshsdk/core';
import type { Unit, Quantity } from '@meshsdk/core';

const utxos = await wallet.getUtxos();

const assetMap = new Map<Unit, Quantity>();
assetMap.set(
  'd9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e',
  '1'
);
// if you need to include lovelace
assetMap.set(
  'lovelace',
  '10000000'
);
// if you need to include more than 1 native asset
assetMap.set(
  'another asset unit',
  '1'
);

const selectedUtxos = largestFirstMultiAsset(assetMap, utxos, true);

The third parameter, includeTxFees, if True, Mesh will calculate the fees required, and include additional UTXOs to fulfill the fees amount.