> ## Documentation Index
> Fetch the complete documentation index at: https://docs.near.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle of a Transaction

> Learn how NEAR transactions are executed and finalized

`Transactions` are constructed by users to express the intent of performing actions in the network. Once in the network, transactions are converted into `Receipts`, which are messages exchanged between network nodes.

On this page, we will explore the lifecycle of a transaction, from its creation to its final status.

<Tip>
  **Recommended Reading**

  To dig deeper into transaction routing, we recommend reading the [nearcore documentation](https://near.github.io/nearcore/architecture/how/tx_routing.html)
</Tip>

***

## Receipts & Finality

Let's walk through the lifecycle of a complex transaction and see how it is processed by the network using blocks as **time units**.

#### Block #1: The Transaction Arrives

After a transaction arrives, the network takes one block to validate it and transform it into a single `Receipt` that contains all the [actions](./transaction-anatomy) to be executed.

While creating the `Receipt`, the `signer` gets `$NEAR` deducted from its balance to **pay for the gas** and **any attached NEAR**.

If the `signer` and `receiver` coincide - e.g. the `signer` is adding a Key - the `Receipt` is immediately processed in this first block and the transaction is considered final.

#### Block #2: The Receipt is Processed

If the `signer` and `receiver` differs - e.g. the `signer` transfers NEAR to the `receiver` - the `Receipt` is processed in a second block.

During this process a `FunctionCall` could span a **cross-contract call**, creating one or multiple new `Receipts`.

#### Block #3...: Function Calls

Each `Receipt` created from the function call take an additional block to be processed. Notice that, if those `Receipts` are `FunctionCall` they could spawn new `Receipts` and so on.

#### Final Block: Gas is Refunded

A final `Receipt` is processed in a new block, refunding any extra gas paid by the user.

### Waiting for a Transaction

When using our libraries (or directly contacting the RPC), you can specify how long you want to wait for a transaction to be processed using a `wait_until` parameter.

After a transaction is submitted, it first gets validated by the RPC node. If the transaction fails structural checks it will be immediately rejected. Otherwise, two things progress independently:

* **Execution**: the receipts spawned by the transaction are executed across shards
* **Finality**: the blocks containing the transaction and its receipts are finalized by consensus

These two axes combine to give you the following `wait_until` levels:

| `wait_until`         | Receipts executed?           | Tx block final?  | Receipt outcomes in response? |
| -------------------- | ---------------------------- | ---------------- | ----------------------------- |
| `None`               | —                            | —                | No                            |
| `Included`           | —                            | —                | No                            |
| `ExecutedOptimistic` | Yes (non-refund)             | No               | Yes                           |
| `IncludedFinal`      | Not necessarily              | Yes              | Partial                       |
| `Executed`           | Yes (non-refund)             | Yes              | Yes                           |
| `Final`              | Yes (all, including refunds) | Yes (all blocks) | Yes                           |

Notice that `ExecutedOptimistic` and `IncludedFinal` are not ordered relative to each other — they represent progress on different axes. `ExecutedOptimistic` guarantees all non-refund receipt outcomes are available but the blocks aren’t final yet. `IncludedFinal` guarantees the transaction’s block is final but some receipts may still be pending, so you may only get a partial set of receipt outcomes.

#### Refund receipts

When a receipt executes with leftover gas, NEAR generates a refund receipt to return the unused payment to the sender. These always succeed and don’t affect application logic, so `ExecutedOptimistic` and `Executed` don’t wait for them — only `Final` does.

<Tip>
  Most transactions will just spawn a receipt to process the actions, and a receipt to refund the gas, being final in 1-3 blocks (\~1-3 seconds):

  * [One block](https://testnet.nearblocks.io/txns/8MAvH96aMfDxPb3kVDrgj8nvJS7CAXP1GgtiivKAMGkF#execution) if the `signer` and `receiver` coincide - e.g. when adding a key
  * [Three blocks](https://testnet.nearblocks.io/txns/B7gxJNxav1A9WhWvaNWYLrSTub1Mkfj3tAudoASVM5tG#) if the `signer` and `receiver` differ, since the first block creates the `Receipt`, and the last reimburses gas

  Function calls might take longer, as they can spawn multiple receipts. Network congestion can also increase the time to process a receipt and, thus, a transaction.
</Tip>

***

## Transaction Status

As the `Receipts` of a `Transaction` are processed, they get a status:

* `Success`: the actions on the receipt were executed successfully
* `Failed`: an action on the receipt failed
* `Unknown`: the receipt is not known by the network

If an action in a `Receipt` fails, all the actions in that `Receipt` are rolled back. Notice that we are talking about the `Receipt` status, and not the `Transaction` status.

The status of a transaction is determined by its first receipt, which contains all its actions. If any of the actions in the first receipt fail, the transaction is marked as failed.

Notice that, it could happen that a transaction is marked as successful, but some of its receipt fails. This happens when a `FunctionCall` successfully spawns a new receipt, but the consequent function call fails. In this case, the transaction is marked as successful because the original function call was successful.

See the examples below for more details.

<Accordion title="Status Examples">
  #### Example: Transaction with Transfer

  1. `bob.near` creates a transaction to transfer 10 NEAR to `alice.near`
  2. The transaction is converted into a receipt
  3. The conversion fails because `bob.near` does not have enough balance
  4. The transaction is marked as failed ⛔

  #### Example: Deploying a Contract

  1. `bob.near` creates a transaction to:
     * create the account `contract.bob.near`
     * transfer 5 NEAR to `contract.bob.near`
     * deploy a contract in `contract.bob.near`
  2. The transaction is transformed into one receipt
  3. The account is created, the money transfer and the contract deployed
  4. The transaction is marked as successful ✅

  #### Example: Deploying a Contract Fails

  1. `bob.near` creates a transaction to:
     * create the account `contract.bob.near`
     * transfer 5 NEAR to `contract.bob.near`
     * deploy a contract in `contract.bob.near`
  2. The transaction is transformed into one receipt
  3. The account is created, but the transfer fails because `bob.near` does not have enough balance
  4. The whole process is reverted (i.e. no account is created)
  5. The transaction is marked as failed ⛔

  #### Example: Calling a Function

  1. `bob.near` creates a transaction to call the function `cross-call` in `contract.near`
  2. The transaction is transformed into one receipt
  3. The function `cross-call` creates a promise to call the function `external-call` in `external.near`
  4. The function finishes correctly and the transaction is marked as successful ✅
  5. A new receipt is created to call the function `external-call` in `external.near`
  6. The function `external-call` fails
  7. The original transaction is still marked as successful ✅ because the first receipt was successful
</Accordion>

<Tip>
  You can check the status of a transaction using the [NearBlocks explorer](https://nearblocks.io/)
</Tip>

***

## Nonce values

The `nonce` is a number that is incremented for each transaction sent by the transaction's `Signer`.
On a valid transaction, the `nonce` value should follow these rules:

* When adding a key, the `nonce` is automatically assigned - particularly, it is given the value `block height * 10^6` - so the value in the `ADD_KEY` action is ignored
* A transaction is accepted only if the `nonce` value is in the range of:
  * `[(current_nonce_of_access_key + 1) .. (block_height * 10^6)]`
* Once a transaction is accepted, the access key's `nonce` is set to the `nonce` value of the included transaction