# Protocol

The YAR protocol implements a network for delivering on-chain transactions to external networks.\
It consists of the following elements:

1. A standard EVM transaction that needs to be delivered
2. The `YarRequest` smart contract, which serves as the entry point
3. The `YarResponse` smart contract, responsible for on-chain transaction delivery
4. The `YarHub` the smart contract, located only in YarChain, represents a mempool of cross-chain transactions
5. The Solidity structure `YarLib.YarTX`, a wrapper around a standard EVM transaction with additional metadata
6. The EVM-compatible blockchain YarChain
7. A network of validators known as Relayers

These elements are combined in the following sequence:

1. The initiator (EOA wallet or smart contract) calls `YarRequest.send(...)`
2. `YarRequest` generates a `Send` event
3. Upon receiving the `Send` event, Relayers add the pending transaction to `YarHub`
4. After adding the transaction to the queue, Relayers move transactions into execution, locking a sufficient amount of fees
5. Relayers call `YarResponse.deliver(...)`, which executes the transaction to the destination address
6. After executing the transaction, Relayers update the transaction status and return any unspent fees

### 0. Standard EVM Transaction

There are no restrictions on the transactions being sent:

1. The address in the external network does not need to conform to any specific interface; transactions can be delivered even to EOA wallets
2. The transaction can transfer the native token, i.e., use the \[value] parameter
3. The transaction can represent another cross-chain call, allowing complex sequences of data transfers across multiple networks

### 1. `YarRequest` Smart Contract

The starting point of the protocol. It is responsible for sending events to validators.

There are 3 types of unique events:

1. `Send` - sends a cross-chain transaction

```solidity
event Send(
    YarLib.YarTX yarTx
);
```

2. `Deposit` - replenishes the balance, which is debited to pay for cross-chain transactions

```solidity
event Deposit(
    address depositor,
    address feesToken,
    uint256 amount
);
```

3. `Approve` - similar to `EIP20.approve`. Allows applications to debit the user's balance to pay for their cross-chain transaction

```solidity
event Approve(
    address account,
    uint256 initialChainId,
    address spender,
    uint256 amount
);
```

Each event corresponds to a function of the same name:

1. `send` - accepts `YarLib.YarTX` and sends it to the Relayers network

```solidity
function send(YarLib.YarTX memory yarTX) external returns (YarLib.YarTX memory);
```

2. `deposit` - accepts tokens (native or EIP20) from the user

```solidity
function deposit(uint256 amount) public payable;
```

3. `approve` - allows the \[spender] to debit \[amount] YarToken from the user's deposit

```solidity
function approve(address spender, uint256 amount) public;
```

### 2. `YarResponse` Smart Contract

Acts as the entry point for sending transactions by the Relayers network. This is done via the `deliver` function, which deploys the cross-chain transaction \[yarTx] and delivers it to the recipient.

```solidity
function deliver(YarLib.YarTX calldata yarTx) external payable {
    ...
    yarTx.target.call{ value: yarTx.value }(yarTx.data);
    ...
}
```

Additionally, this smart contract is used by applications for authorization if their recipient function should only accept calls from Relayers and not any address.

Temporarily, it stores the metadata of the current cross-chain transaction, which can be accessed in the `trustedYarTx` function. The metadata is recorded before the call and deleted immediately afterward.

```solidity
function trustedYarTx() external view returns (YarLib.YarTX memory);
```

!!! Passing flags to enable/disable writing `trustedYarTx` fields to storage can save gas.

### 3. `YarHub` Smart Contract

`YarHub` stores all pending, executed, and unexecuted cross-chain transactions, which are accessible in the `wrappedYarTXs` mapping.

```solidity
function wrappedYarTXs(bytes32 yarTxHash) external view returns (WrappedYarTX);
```

To access a specific transaction `[yarTx]`, the key used is the keccak hash of the entire `YarLib.YarTx` model.

```solidity
keccak256(abi.encode(yarTX))
```

You can also obtain the identifying hash of a cross-chain transaction using the `[YarHub.getYarTxHash]` method.

```solidity
function getYarTxHash(YarLib.YarTX calldata yarTX) public pure returns (bytes32);
```

`YarHub` also stores user deposits in Yar tokens, which are used to pay for transaction fees.\
The balance is credited to the deposit only from the relayer’s address after processing the `Deposit` event.\
To view the current balance:

```solidity
uint256 balance = yarHub.deposits(account);
```

### 4. Solidity Structure `YarLib.YarTX`

```solidity
library YarLib {
    struct YarTX {
        uint256 initialChainId; // Identifier of the current network
        address sender; // Your smart contract [Example]
        address payer; // User who calls the Example contract and pays the fee in Yar
        uint256 targetChainId; // Identifier of the network where the transaction will be delivered
        address target; // Address in the [TARGET] network where the transaction will be called
        uint256 value; // Amount of the native token of the [TARGET] network that will be sent with the transaction
        bytes data; // Encoded transaction data (bytes4 for the function signature + function arguments)
        uint256 _nonce; // This parameter will be redefined in YarRequest; set it to 0
    }
}
```


---

# 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.yarchain.org/dev-docs/protocol.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.