# Transactions

## Build Transaction

Every change on the Blockchain requires a transaction. A transaction wraps function calls in the form of clauses. Each clause sends instructions to an address that are encoded as hex string.

To send a transaction you will need to do multiple steps:

1. Have Private Key at hand that will sign the transaction
2. Encode the function calls into data calls
3. Calculate how much gas the transaction will cost
4. Build a transaction object with all the previous information
5. Sign the transaction
6. Send the transaction to the network

### Collecting Function Calls in Clauses

The instructions for executing a function on the blockchain needs to be encoded in a certain way. There are different functions to help create the right format, one is the `callFunction` that will call `increment`, a function of the smart contract available a the given address:

```typescript
const clauses = [
    Clause.callFunction(
        '0x8384738c995d49c5b692560ae688fc8b51af1059',
        new ABIFunction({
            name: 'increment',
            inputs: [],
            outputs: [],
            constant: false,
            payable: false,
            type: 'function',
        })
    ),
];
```

A clause can also send VET in the same action. Check the [type definition](https://vechain.github.io/vechain-sdk-js/interfaces/_vechain_sdk_core.TransactionClause.html) to also learn more about the internals.

### Calculate Gas

While reading on the blockchain is free, writing requires to pay the so-called gas fees to cover the cost of the transaction. Gas is paid in VTHO, the secondary token on VeChain.

To calculate the right amount of gas for your transaction, you can use `estimateGas`.

```typescript
const gasResult = await thor.transactions.estimateGas(clauses, senderAddress);
```

{% hint style="info" %}
If you expect your contracts to have different results based on the sender, you can also pass in the sender address as optional second parameter.
{% endhint %}

### Build Transaction

Once you have instructions + costs, you'll wrap them together into a transaction object with `buildTransactionBody`.

```typescript
const txBody = await thor.transactions.buildTransactionBody(
    clauses,
    gasResult.totalGas
);

```

{% hint style="info" %}
There are [several options](https://vechain.github.io/vechain-sdk-js/interfaces/_vechain_sdk_network.TransactionBodyOptions.html) that can optionally be passed as third argument to enable fee delegation, dependency on other transactions, priority and an expiration. You will learn more about them in other sections.
{% endhint %}

### Sign Transaction

Once a transaction is built, it needs to be signed by an entity that will execute all the code. This also makes the origin verifiable.

It is a four steps process, of getting a signer first:

#### Get Signer

```typescript
const wallet = new ProviderInternalBaseWallet(
  [{ privateKey, address: senderAddress }]
);

const provider = new VeChainProvider(
  // Thor client used by the provider
  thorClient,

  // Internal wallet used by the provider (needed to call the getSigner() method)
  wallet,

  // Enable fee delegation
  false
);

const signer = await provider.getSigner(senderAddress);
```

#### Sign Transaction

And using the signer to sign the transaction:

```javascript
const rawSignedTx = await signer.signTransaction(tx, privateKey);
```

#### Build Signed Transaction Object

`signTransaction` returns the fully signed transaction that can already be published using a POST request to the `/transactions` endpoint of a VeChain node:

```typescript
await fetch(`${nodeUrl}/transactions`, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    raw: rawSignedTx,
  }),
})
```

For submission by SDK, the raw hex string needs to be restored into a transaction object:

```typescript
const signedTx = Transaction.decode(
  HexUInt.of(rawSignedTx).bytes,
  true
);
```

### Send Transaction

The signed transaction can be published to the network using `sendTransaction`, which will post the data to the connected node:

```javascript
const sendTransactionResult = await thor.transactions.sendTransaction(signedTx);
```

### Wait for Results

`sendTransaction` returns a transaction id that can be used to track the status of the newly published transaction. `waitForTransaction` will resolve with the full receipt as soon as the result is available:

```javascript
const txReceipt = await thor.transactions.waitForTransaction(
  sendTransactionResult.id
);
```

### Example Project

{% embed url="<https://stackblitz.com/edit/vechain-academy-build-transaction-example?embed=1&file=index.mjs&hideExplorer=1&hideNavigation=1&view=editor>" %}

## Execute Transactions

### Transfer Token

Using `executeTransaction` the signed transaction will directly be published to the network

```javascript
const tokenContract = '0x5ef79995fe8a89e0812330e4378eb2660cede699'; // B3TR
const amount = 1.234 * 10**18; // 1.234 B3TR 

const transferAbi = new ABIFunction("function transfer(address to, uint256 value) public returns (bool)")

const transactionResult = await thorClient.transactions.executeTransaction(
  signer,
  tokenContract,
  transferAbi,
  [receiverAddress,amount]
)
```

### Delegated transaction - Transfer Token

If your transaction is delegated, you need to enable the fee delegation on your provider,

```typescript
const provider = new VeChainProvider(
  // Thor client used by the provider
  thorClient,
  // Internal wallet used by the provider (needed to call the getSigner() method)
  wallet,
  // Enable fee delegation
  true
);
```

and the `delegationUrl` must be provided.

```typescript
const transactionResult = await thorClient.transactions.executeTransaction(
  signer,
  tokenContract,
  transferAbi,
  [receiverAddress,amount],
  {delegationUrl:'https://sponsor-testnet.vechain.energy/by/441'}
)
```

### Example Project

{% embed url="<https://stackblitz.com/edit/vechain-academy-transfer-token?embed=1&file=index.mjs&hideExplorer=1&hideNavigation=1&view=editor>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vechain.org/developer-resources/how-to-build-on-vechain/write-data/transactions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.