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

event Send(
    YarLib.YarTX yarTx
);

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

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

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

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

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

function deposit(uint256 amount) public payable;

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

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.

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.

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.

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.

keccak256(abi.encode(yarTX))

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

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:

uint256 balance = yarHub.deposits(account);

4. Solidity Structure YarLib.YarTX

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
    }
}