Executor contracts

Table of Contents

• Overview
• Structure and Usage
  • EVM
    • Smart-contracts overview
    • Setup
  • AVM
    • Smart-contracts overview
    • Setup
• Quote

Overview

PuyaPy implementation of Executor and TokenPaymentExecutor, solidity implementation of TokenPaymentExecutor.

TokenPaymentExecutor extends functionality of Wormhole Executor to support of paying Executor fee both in native and in custom tokens (default Wormhole Executor support only native token payments).

Before proceeding with this repository is highly recommended to get known with Wormhole executor integration notes. This document explain logic of integration of wormhole executor.

Structure and usage

EVM

Smart-contracts overview

EVM smart-contracts located in contracts/evm directory.

TokenPaymentExecutor and NttManagerWithTokenPaymentExecutor contracts extend functionality of default Wormhole VAA and NTT executor, allowing to take executor fee in custom token.

SafeMultiReceiveWithGasDropOff and SafeVAAv1ReceiveWithGasDropOff contracts are wrappers on default Wormhole receiver contracts to avoid extra gas consumption by receiver contracts and ensure parent call is succeed. In simple words returnLengthBoundedCall works as try/catch on default Wormhole receiver contract.

Setup

Install git submodules:

git submodule update --init --recursive

Install foundry:

curl -L https://foundry.paradigm.xyz | bash
foundryup -i v1.5.0

Install required packages:

npm install

Build the project:

npm run build:evm

Run tests:

npm run test:evm

AVM

Smart-contracts overview

AVM smart-contracts located in contracts/avm directory.

Executor and NttManagerWithExecutor are analogs of Wormhole smart-contracts written for Algorand.

TokenPaymentExecutor and NttManagerWithTokenPaymentExecutor contracts extend functionality of Executor and NttManagerWithExecutor, allowing to take executor fee in custom token.

NttV1ReceiveWithGasDropOff and VAAv1ReceiveWithGasDropOff are analogs of default Wormhole receiver contracts on Algorand.

Setup

Activate virtual environment and install required packages:

python3 -m venv venv
source venv/bin/activate
python3 -m pip install -r requirements.txt

Build the project:

npm run build:avm

Make sure to run the compilation commands before testing.

Run tests (Algokit is required):

algokit localnet start
npm run test:avm

Quote

To recognize payment in custom token - specific quote prefix used: EQC1. Also there is additional parameter in quote body for EQC1, named tokenAddress. The difference between quote bodies bytes for different prefixes listed below:

Signed Quote Header

bytes4  prefix;           // 4-byte prefix for this struct
address quoterAddress;    // The public key of the quoter. Used to identify an execution provider.
bytes32 payeeAddress;     // UniversalAddress of a payee for the quoter on the sending chain.
uint16  sourceChain;      // Wormhole Chain ID
uint16  destinationChain; // Wormhole Chain ID
uint64  expiryTime;       // The unix time, in seconds, after which this quote should no longer be considered valid for requesting an execution

Signed Quote (for native token payments)

Header   header              // prefix = "EQ01"
uint64   baseFee             // The base fee, in sourceChain native currency, required by the quoter to perform an execution on the destination chain
uint64   destinationGasPrice // The current gas price on the destination chain
uint64   sourcePrice         // The USD price, in 10^10, of the sourceChain native currency
uint64   destinationPrice    // The USD price, in 10^10, of the destinationChain native currency
[65]byte signature           // Quoter's signature of the previous bytes

Signed Quote (for custom token payments)

Header   header              // prefix = "EQC1"
uint64   baseFee             // The base fee, in sourceChain custom token, required by the quoter to perform an execution on the destination chain
uint64   destinationGasPrice // The current gas price on the destination chain
uint64   sourcePrice         // The USD price, in 10^10, of the sourceChain custom token
uint64   destinationPrice    // The USD price, in 10^10, of the destinationChain native currency
bytes32  tokenAddress        // UniversalAddress of the custom token on the sourceChain
[65]byte signature           // Quoter's signature of the previous bytes