Icon LinkWallet Transferring

This guide provides instructions for transferring assets between wallets and contracts using the SDK. It includes methods to validate balances and initiate and configure transfer requests.

Icon LinkTransferring Assets Between Accounts

The transfer method initiates a transaction request that transfers an asset from one wallet to another. This method requires three parameters:

1. The receiver's wallet address
2. The amount of the asset to be transferred
3. The ID of the asset to be transferred (optional - defaults to the base asset ID)

Upon execution, this function returns a promise that resolves to a transaction response. To wait for the transaction to be processed, call response.waitForResult().

Icon LinkExample

Here is an example of how to use the transfer function:

// #import { Wallet, BN };
 
const sender = Wallet.fromPrivateKey('...');
const destination = Wallet.generate({
  provider: sender.provider,
});
const amountToTransfer = 500;
 
const baseAssetId = await sender.provider.getBaseAssetId();
 
const response = await sender.transfer(destination.address, amountToTransfer, baseAssetId);
 
await response.wait();
 
// Retrieve balances
const receiverBalance = await destination.getBalance(baseAssetId);
 
// Validate new balance
expect(new BN(receiverBalance).toNumber()).toEqual(amountToTransfer);

In the previous example, we used the transfer method which creates a ScriptTransactionRequest, populates its data with the provided transfer information and submits the transaction.

However, there may be times when you need the Transaction ID before actually submitting it to the node. To achieve this, you can simply call the createTransfer method instead.

This method also creates a ScriptTransactionRequest and populates it with the provided data but returns the request object prior to submission.

const transactionRequest = await sender.createTransfer(
  destination.address,
  amountToTransfer,
  assetId
);
 
const chainId = provider.getChainId();
 
const transactionId = transactionRequest.getTransactionId(chainId);
 
const response = await sender.sendTransaction(transactionRequest);
 
const { id } = await response.wait();
 
// The transaction id should is the same as the one returned by the transaction request
expect(id).toEqual(transactionId);

Icon InfoCircle

Note: Any changes made to a transaction request will alter the transaction ID. Therefore, you should only get the transaction ID after all modifications have been made.

const transactionRequest = await sender.createTransfer(
  destination.address,
  amountToTransfer,
  assetId
);
 
const chainId = provider.getChainId();
 
const transactionId = transactionRequest.getTransactionId(chainId);
 
transactionRequest.maturity = 1;
 
const { maxFee } = await provider.estimateTxGasAndFee({ transactionRequest });
 
transactionRequest.maxFee = maxFee;
 
const response = await sender.sendTransaction(transactionRequest);
 
const { id } = await response.wait();
 
expect(id).not.toEqual(transactionId);

Icon LinkTransferring Assets To Contracts

When transferring assets to a deployed contract, we use the transferToContract method, which shares a similar parameter structure with the transfer method.

However, instead of supplying the target wallet's address, as done in destination.address for the transfer method, we need to provide an instance of Address created from the deployed contract id.

If you have the Contract instance of the deployed contract, you can simply use its id property. However, if the contract was deployed with forc deploy or not by you, you will likely only have its ID in a hex string format. In such cases, you can create an Address instance from the contract ID using Address.fromAddressOrString('0x123...').

Here's an example demonstrating how to use transferToContract:

// #import { Wallet, BN };
 
const senderWallet = Wallet.fromPrivateKey('...');
 
const amountToTransfer = 400;
const assetId = provider.getBaseAssetId();
const contractId = Address.fromAddressOrString('0x123...');
 
const contractBalance = await deployedContract.getBalance(assetId);
 
const tx = await sender.transferToContract(contractId, amountToTransfer, assetId);
expect(new BN(contractBalance).toNumber()).toBe(0);
 
await tx.waitForResult();
 
expect(new BN(await deployedContract.getBalance(assetId)).toNumber()).toBe(amountToTransfer);

Always remember to call the waitForResult() function on the transaction response. That ensures the transaction has been mined successfully before proceeding.

Icon LinkTransferring Assets To Multiple Wallets

To transfer assets to multiple wallets, use the Account.batchTransfer method:

const myWallet = Wallet.fromPrivateKey(privateKey, provider);
 
const recipient1 = Wallet.generate({ provider });
const recipient2 = Wallet.generate({ provider });
 
const transfersToMake: TransferParams[] = [
  { amount: 100, destination: recipient1.address, assetId: baseAssetId },
  { amount: 200, destination: recipient2.address, assetId: baseAssetId },
  { amount: 300, destination: recipient2.address, assetId: someOtherAssetId },
];
 
const tx = await myWallet.batchTransfer(transfersToMake);
const { isStatusSuccess } = await tx.waitForResult();

This section demonstrates additional examples of transferring assets between wallets and to contracts.

Icon LinkChecking Balances

Before transferring assets, ensure your wallet has sufficient funds. Attempting a transfer without enough funds will result in an error: not enough coins to fit the target.

You can see how to check your balance at the checking-balances page.