Merge the devel branch into the main branch, v4.0.0

This merge contains the following set of changes:
  - Fix error handler middleware (#157)
  - Introduction of Direct Deposits (#156)
  - Log for batch cache timer expiration and for number of handled deposits (#162)
  - Add header validation to check version of the client library (#163)

.dockerignore

@@ -2,12 +2,13 @@
 **/package-lock.json
 **/target
 **/.git
-**/.env*
+**/*.env*
 build
 tree.db
 txs.db
 dist
-test
+**/test
 test-e2e
 *_key.json
-**/params/
+**/params*/
+**/*.log

.gitignore

@@ -11,7 +11,7 @@ prover.js
 *params.bin
 *_key.json
 
-.env
+*.env
 
 # Log file
 zp.log

CONFIGURATION.md

@@ -1,44 +1,60 @@
 # Configuration
 
 ## Common configuration
+These environment variables are required for all services.
+| name | description | value |
+| - | - | - |
+| COMMON_LOG_LEVEL | Log level | Winston log level |
+| COMMON_POOL_ADDRESS | Address of the pool contract | hexadecimal prefixed with "0x" |
+| COMMON_START_BLOCK | The block number used to start searching for events when the relayer/watcher instance is run for the first time | integer |
+| COMMON_REDIS_URL | Url to redis instance | URL |
+| COMMON_RPC_URL | The HTTPS URL(s) used to communicate to the RPC nodes. Several URLs can be specified, delimited by spaces. If the connection to one of these nodes is lost the next URL is used for connection. | URL |
+| COMMON_REQUIRE_HTTPS | If set to `true`, then RPC URL(s) must be in HTTPS format. HTTP RPC URL(s) should be used in test environment only. | boolean |
+| COMMON_RPC_SYNC_STATE_CHECK_INTERVAL | Interval in milliseconds for checking JSON RPC sync state, by requesting the latest block number. Watcher will switch to the fallback JSON RPC in case sync process is stuck. If this variable is `0` sync state check is disabled. Defaults to `0`.  | integer |
+| COMMON_RPC_REQUEST_TIMEOUT | Timeout in milliseconds for a single RPC request. Defaults to `1000`. | integer |
+| COMMON_JSONRPC_ERROR_CODES | Override default JSON rpc error codes that can trigger RPC fallback to the next URL from the list (or a retry in case of a single RPC URL). Default is `-32603,-32002,-32005`. Should be a comma-separated list of negative integers. | `string` |
+| COMMON_EVENTS_PROCESSING_BATCH_SIZE | Batch size for one `eth_getLogs` request when processing logs. Defaults to `10000` | integer |
+
+## Relayer
 
 | name | description | value |
 | - | - | - |
-| PORT | Relayer port | integer |
+| RELAYER_PORT | Relayer port | integer |
+| RELAYER_TOKEN_ADDRESS | Address of the token contract | hexadecimal prefixed with "0x" |
 | RELAYER_ADDRESS_PRIVATE_KEY | Private key to sign pool transactions | hexadecimal prefixed with "0x" |
-| POOL_ADDRESS | Address of the pool contract | hexadecimal prefixed with "0x" |
 | RELAYER_GAS_LIMIT | Gas limit for pool transactions | integer |
-| RELAYER_FEE | Minimal accepted relayer fee (in tokens | integer |
-| MAX_NATIVE_AMOUNT_FAUCET | Maximal amount of faucet value (in ETH) | integer |
-| TREE_UPDATE_PARAMS_PATH | Local path to tree update circuit parameters | string |
-| TRANSFER_PARAMS_PATH | Local path to transfer circuit parameters | string |
-| TX_VK_PATH | Local path to transaction circuit verification key | string |
+| RELAYER_FEE | Minimal accepted relayer fee (in tokens) | integer |
+| RELAYER_MAX_NATIVE_AMOUNT_FAUCET | Maximal amount of faucet value (in ETH) | integer |
+| RELAYER_TREE_UPDATE_PARAMS_PATH | Local path to tree update circuit parameters | string |
+| RELAYER_TRANSFER_PARAMS_PATH | Local path to transfer circuit parameters | string |
+| RELAYER_TX_VK_PATH | Local path to transaction circuit verification key | string |
 | RELAYER_REQUEST_LOG_PATH | Path to a file where all HTTP request logs will be saved. Default `./zp.log`. | string |
-| STATE_DIR_PATH | Path to persistent state files related to tree and transactions storage. Default: `./POOL_STATE` | string |
-| GAS_PRICE_FALLBACK | Default fallback gas price | integer |
-| GAS_PRICE_ESTIMATION_TYPE | Gas price estimation type | `web3` / `gas-price-oracle` / `eip1559-gas-estimation` / `polygon-gasstation-v2` |
-| GAS_PRICE_SPEED_TYPE | This parameter specifies the desirable transaction speed | `instant` / `fast` / `standard` / `low` |
-| GAS_PRICE_FACTOR | A value that will multiply the gas price of the oracle to convert it to gwei. If the oracle API returns gas prices in gwei then this can be set to `1`. Also, it could be used to intentionally pay more gas than suggested by the oracle to guarantee the transaction verification. E.g. `1.25` or `1.5`. | integer |
-| GAS_PRICE_UPDATE_INTERVAL | Interval in milliseconds used to get the updated gas price value using specified estimation type | integer |
-| GAS_PRICE_SURPLUS | A surplus to be added to fetched `gasPrice` on initial transaction submission. Default `0.1`. | float |
-| MIN_GAS_PRICE_BUMP_FACTOR | Minimum `gasPrice` bump factor to meet RPC node requirements. Default `0.1`. | float |
-| MAX_FEE_PER_GAS_LIMIT | Max limit on `maxFeePerGas` parameter for each transaction in wei | integer |
-| MAX_SENT_QUEUE_SIZE | Maximum number of jobs waiting in the `sentTxQueue` at a time. | integer |
-| START_BLOCK | The block number used to start searching for events when the relayer instance is run for the first time | integer
-| EVENTS_PROCESSING_BATCH_SIZE | Batch size for one `eth_getLogs` request when reprocessing old logs. Defaults to `10000` | integer
-| RELAYER_LOG_LEVEL | Log level | Winston log level |
-| RELAYER_REDIS_URL | Url to redis instance | URL |
-| RPC_URL | The HTTPS URL(s) used to communicate to the RPC nodes. Several URLs can be specified, delimited by spaces. If the connection to one of these nodes is lost the next URL is used for connection. | URL |
+| RELAYER_STATE_DIR_PATH | Path to persistent state files related to tree and transactions storage. Default: `./POOL_STATE` | string |
+| RELAYER_GAS_PRICE_FALLBACK | Default fallback gas price | integer |
+| RELAYER_GAS_PRICE_ESTIMATION_TYPE | Gas price estimation type | `web3` / `gas-price-oracle` / `eip1559-gas-estimation` / `polygon-gasstation-v2` |
+| RELAYER_GAS_PRICE_SPEED_TYPE | This parameter specifies the desirable transaction speed | `instant` / `fast` / `standard` / `low` |
+| RELAYER_GAS_PRICE_FACTOR | A value that will multiply the gas price of the oracle to convert it to gwei. If the oracle API returns gas prices in gwei then this can be set to `1`. Also, it could be used to intentionally pay more gas than suggested by the oracle to guarantee the transaction verification. E.g. `1.25` or `1.5`. | integer |
+| RELAYER_GAS_PRICE_UPDATE_INTERVAL | Interval in milliseconds used to get the updated gas price value using specified estimation type | integer |
+| RELAYER_GAS_PRICE_SURPLUS | A surplus to be added to fetched `gasPrice` on initial transaction submission. Default `0.1`. | float |
+| RELAYER_MIN_GAS_PRICE_BUMP_FACTOR | Minimum `gasPrice` bump factor to meet RPC node requirements. Default `0.1`. | float |
+| RELAYER_MAX_FEE_PER_GAS_LIMIT | Max limit on `maxFeePerGas` parameter for each transaction in wei | integer |
+| RELAYER_MAX_SENT_QUEUE_SIZE | Maximum number of jobs waiting in the `sentTxQueue` at a time. | integer |
 | RELAYER_TX_REDUNDANCY | If set to `true`, instructs relayer to send `eth_sendRawTransaction` requests through all available RPC urls defined in `RPC_URL` variables instead of using first available one. Defaults to `false` | boolean |
-| RELAYER_RPC_SYNC_STATE_CHECK_INTERVAL | Interval in milliseconds for checking JSON RPC sync state, by requesting the latest block number. Relayer will switch to the fallback JSON RPC in case sync process is stuck. If this variable is `0` sync state check is disabled. Defaults to `0`  | integer |
-| INSUFFICIENT_BALANCE_CHECK_TIMEOUT | Interval in milliseconds to check for relayer balance update if transaction send failed with insufficient balance error. Default `60000` | integer |
-| SENT_TX_DELAY | Delay in milliseconds for sentTxWorker to verify submitted transactions | integer |
-| SENT_TX_ERROR_THRESHOLD | Maximum number of re-sends which is considered to be normal. After this threshold each re-send will log a corresponding error (but re-send loop will continue). Defaults to `3`. | integer |
-| PERMIT_DEADLINE_THRESHOLD_INITIAL | Minimum time threshold in seconds for permit signature deadline to be valid (before initial transaction submission) | integer |
-| PERMIT_DEADLINE_THRESHOLD_RESEND | Minimum time threshold in seconds for permit signature deadline to be valid (for re-send attempts) | integer |
+| RELAYER_INSUFFICIENT_BALANCE_CHECK_TIMEOUT | Interval in milliseconds to check for relayer balance update if transaction send failed with insufficient balance error. Default `60000` | integer |
+| RELAYER_SENT_TX_DELAY | Delay in milliseconds for sentTxWorker to verify submitted transactions | integer |
+| RELAYER_SENT_TX_ERROR_THRESHOLD | Maximum number of re-sends which is considered to be normal. After this threshold each re-send will log a corresponding error (but re-send loop will continue). Defaults to `3`. | integer |
+| RELAYER_PERMIT_DEADLINE_THRESHOLD_INITIAL | Minimum time threshold in seconds for permit signature deadline to be valid (before initial transaction submission) | integer |
+| RELAYER_PERMIT_DEADLINE_THRESHOLD_RESEND | Minimum time threshold in seconds for permit signature deadline to be valid (for re-send attempts) | integer |
 | RELAYER_REQUIRE_TRACE_ID | If set to `true`, then requests to relayer (except `/info`, `/version`, `/params/hash/tree`, `/params/hash/tx`) without `zkbob-support-id` header will be rejected. | boolean |
-| RELAYER_REQUIRE_HTTPS | If set to `true`, then RPC URL(s) must be in HTTPS format. HTTP RPC URL(s) should be used in test environment only. | boolean |
 | RELAYER_LOG_IGNORE_ROUTES | List of space separated relayer endpoints for which request logging will be suppressed. E.g. `/fee /version` | string(s) |
 | RELAYER_LOG_HEADER_BLACKLIST | List of space separated HTTP headers which will be suppressed in request logs. E.g. `content-length content-type` | string(s) |
 | RELAYER_SCREENER_URL | Screener service URL | URL |
 | RELAYER_SCREENER_TOKEN | Authorization token for screener service | string |
+
+## Watcher
+
+| name | description | value |
+| - | - | - |
+| WATCHER_EVENT_POLLING_INTERVAL | The interval in milliseconds used to request the RPC node for new blocks. | integer |
+| WATCHER_DIRECT_DEPOSIT_BATCH_SIZE | Maximum size of a single direct deposit batch. Defaults to `16`. | integer |
+| WATCHER_DIRECT_DEPOSIT_BATCH_TTL | Maximum TTL in milliseconds for a new direct deposit batch. After this time batch will be submitted to the queue, even if it has less than `DIRECT_DEPOSIT_BATCH_SIZE` elements. Defaults to `3600000` (1 hour) | integer |

docker-compose.yaml

@@ -32,12 +32,16 @@ services:
       - relayer_tree:/app/tree.db
       - relayer_txs:/app/txs.db
       - $PARAMS_PATH:/app/zp-relayer/params/
-    env_file: zp-relayer/.env
+    env_file: ./zp-relayer/relayer.env
     ports:
       - 8000:8000
-    depends_on:
-      - verifier
-
+  watcher:
+    image: ghcr.io/zkbob/zkbob-relayer:${RELAYER_VERSION:-latest}
+    build:
+      context: .
+      dockerfile: docker/Dockerfile.relayer
+    command: yarn run start:direct-deposit-watcher:prod
+    env_file: ./zp-relayer/watcher.env
 volumes:
   relayer_tree:
   relayer_txs:

test-flow-generator/package.json

@@ -9,8 +9,8 @@
   "dependencies": {
     "@metamask/eth-sig-util": "^4.0.1",
     "http-server": "14.1.1",
-    "libzkbob-rs-node": "0.2.2",
-    "libzkbob-rs-wasm-web": "0.8.0",
+    "libzkbob-rs-node": "1.0.0",
+    "libzkbob-rs-wasm-web": "1.0.0",
     "node-polyfill-webpack-plugin": "^1.1.4",
     "puppeteer": "^19.2.0",
     "web3-utils": "1.8.0",

test-flow-generator/src/config.ts

@@ -1,5 +1,5 @@
 export const config = {
-  tokenAddress: '0xe78A0F7E598Cc8b0Bb87894B0F60dD2a88d6a8Ab',
-  poolAddress: '0xe982E462b094850F12AF94d21D470e21bE9D0E9C',
+  tokenAddress: '0xCfEB869F69431e42cdB54A4F4f105C19C080A601',
+  poolAddress: '0x9b1f7F645351AF3631a656421eD2e40f2802E6c0',
   chainId: 31337,
 }

test-flow-generator/src/generate.ts

@@ -13,7 +13,7 @@ export async function newAccount() {
   const sk = Array.from({ length: 10 }, () => Math.floor(Math.random() * 100))
   const stateId = sk.toString()
   const state = await UserState.init(stateId)
-  const zkAccount = UserAccount.fromSeed(Uint8Array.from(sk), state)
+  const zkAccount = UserAccount.fromSeed(Uint8Array.from(sk), 0n, state)
   return zkAccount
 }
 

yarn.lock

@@ -556,6 +556,11 @@
   dependencies:
     "@types/node" "*"
 
+"@types/semver@^7.3.13":
+  version "7.3.13"
+  resolved "https://registry.yarnpkg.com/@types/semver/-/semver-7.3.13.tgz#da4bfd73f49bd541d28920ab0e2bf0ee80f71c91"
+  integrity sha512-21cFJr9z3g5dW8B0CVI9g2O9beqaThGQ6ZFBqHfwhzLDKUxaqTIy3vnfah/UPkfOiF2pLq+tGz+W8RyCskuslw==
+
 "@types/serve-static@*":
   version "1.13.10"
   resolved "https://registry.yarnpkg.com/@types/serve-static/-/serve-static-1.13.10.tgz#f5e0ce8797d2d7cc5ebeda48a52c96c4fa47a8d9"
@@ -3472,17 +3477,17 @@ libzeropool-rs-wasm-bundler@0.3.8:
   resolved "https://registry.yarnpkg.com/libzeropool-rs-wasm-bundler/-/libzeropool-rs-wasm-bundler-0.3.8.tgz#2b55628a741f4bd0f776d87365c22ed0da63ba6c"
   integrity sha512-b+W6M/gyeaoKZ4LJC2ThtZmXHVOoEtsa3foPezAyfdgbsyNGDHbSMBcqoTIXVHkP6ul7BKxjOP3xvfi3F6klTg==
 
-libzkbob-rs-node@0.2.2:
-  version "0.2.2"
-  resolved "https://registry.yarnpkg.com/libzkbob-rs-node/-/libzkbob-rs-node-0.2.2.tgz#2b176b9c74fd24eb59c2f38cba42d227fc7fb152"
-  integrity sha512-8elJ5FoiZHhnm2Tnu8TLSzC0A4g7+t+UVSIIysn4ZVOVAgFkojTlSniZL9cqgTmjvMxZzySk5DCcKpa6pTp/WQ==
+libzkbob-rs-node@1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/libzkbob-rs-node/-/libzkbob-rs-node-1.0.0.tgz#a65582e2aca8fc8f90e9c501facf5da16709f14a"
+  integrity sha512-WiIAON2Fe+oakYBgh1ajjG9NQkQFZPTAWc2hvs3BEkw8ezgjkkvh1/yZ8ap8QQE2PAm/rSqsAPuQgj7160Ulvg==
   dependencies:
     cargo-cp-artifact "^0.1"
 
-libzkbob-rs-wasm-web@0.8.0:
-  version "0.8.0"
-  resolved "https://registry.yarnpkg.com/libzkbob-rs-wasm-web/-/libzkbob-rs-wasm-web-0.8.0.tgz#b133aa0f1a381567fde082662ce4c4e46ea7aa47"
-  integrity sha512-EIPeDyl2wmpSMx299LnG0UCqg5wy8sr7TqfCdgPDxA8kH5Gu92MF12KOOOx7sfLpoYZ965y7MbkkuUfz5OzVAg==
+libzkbob-rs-wasm-web@1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/libzkbob-rs-wasm-web/-/libzkbob-rs-wasm-web-1.0.0.tgz#74eba1caa2bfc728be8fd1f3161e5089360f2a72"
+  integrity sha512-3xW0BjAZ9NDoNLCwlGHNjg5q1GN7fEpXCVf7+emQxQrt/vey9PNTAQnNIEjWZ/M0Fn52t06Og2P6zgqcGUCz7Q==
 
 lighthouse-logger@^1.0.0:
   version "1.3.0"
@@ -4998,6 +5003,13 @@ secure-compare@3.0.1:
   resolved "https://registry.yarnpkg.com/semver/-/semver-5.7.1.tgz#a954f931aeba508d307bbf069eff0c01c96116f7"
   integrity sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==
 
+semver@7.3.8:
+  version "7.3.8"
+  resolved "https://registry.yarnpkg.com/semver/-/semver-7.3.8.tgz#07a78feafb3f7b32347d725e33de7e2a2df67798"
+  integrity sha512-NB1ctGL5rlHrPJtFDVIVzTyQylMLu9N9VICA6HSFJo8MCGVTMW6gfpicwKmmK/dAjTOrqu5l63JJOpDSrAis3A==
+  dependencies:
+    lru-cache "^6.0.0"
+
 semver@^7.3.4:
   version "7.3.5"
   resolved "https://registry.yarnpkg.com/semver/-/semver-7.3.5.tgz#0b621c879348d8998e4b0e4be94b3f12e6018ef7"

zp-memo-parser/memo.ts

@@ -24,7 +24,11 @@ export interface PermittableDepositTxData extends DefaultTxData {
   holder: Uint8Array
 }
 
-export type TxData = DefaultTxData | WithdrawTxData | PermittableDepositTxData
+export type TxData<T extends TxType> = T extends TxType.WITHDRAWAL
+  ? WithdrawTxData
+  : T extends TxType.PERMITTABLE_DEPOSIT
+  ? PermittableDepositTxData
+  : DefaultTxData
 
 // Size in bytes
 const U256_SIZE = 32
@@ -82,7 +86,7 @@ function getNoteHashes(rawHashes: Buffer, num: number, maxNotes: number): Uint8A
   for (let i = 0; i < num; i++) {
     const start = i * U256_SIZE
     const end = start + U256_SIZE
-    const note_hash = Buffer.from(rawHashes.slice(start, end))
+    const note_hash = Buffer.from(rawHashes.subarray(start, end))
     notes.push(note_hash)
   }
   // Append zero note hashes
@@ -92,7 +96,11 @@ function getNoteHashes(rawHashes: Buffer, num: number, maxNotes: number): Uint8A
   return notes
 }
 
-export function getTxData(data: Buffer, txType: Option<TxType>): TxData {
+function getAddress(data: Buffer, offset: number): Uint8Array {
+  return new Uint8Array(data.subarray(offset, offset + 20))
+}
+
+export function getTxData<T extends TxType>(data: Buffer, txType: Option<T>): TxData<T> {
   function readU64(offset: number) {
     let uint = data.readBigUInt64BE(offset)
     return uint.toString(10)
@@ -103,29 +111,29 @@ export function getTxData(data: Buffer, txType: Option<TxType>): TxData {
   if (txType === TxType.WITHDRAWAL) {
     const nativeAmount = readU64(offset)
     offset += 8
-    const receiver = new Uint8Array(data.slice(offset, offset + 20))
+    const receiver = getAddress(data, offset)
     return {
       fee,
       nativeAmount,
       receiver,
-    }
+    } as TxData<T>
   } else if (txType === TxType.PERMITTABLE_DEPOSIT) {
     const deadline = readU64(offset)
     offset += 8
-    const holder = new Uint8Array(data.slice(offset, offset + 20))
+    const holder = getAddress(data, offset)
     return {
       fee,
       deadline,
       holder,
-    }
+    } as TxData<T>
   }
-  return { fee }
+  return { fee } as TxData<T>
 }
 
-export function decodeMemo(data: Buffer, txType: Option<TxType>, maxNotes = 127) {
+export function decodeMemo(data: Buffer, maxNotes = 127) {
   const reader = new BinaryReader(data)
   const numItems = new DataView(reader.readFixedArray(4).buffer).getUint32(0, true)
-  const memo: Memo = deserialize(clientBorshSchema(numItems - 1), Memo, data.slice(reader.offset))
+  const memo: Memo = deserialize(clientBorshSchema(numItems - 1), Memo, data.subarray(reader.offset))
   memo.numItems = numItems
   memo.noteHashes = getNoteHashes(memo.rawNoteHashes, numItems - 1, maxNotes)
   memo.rawBuf = data

zp-relayer/.env.example

@@ -1,20 +1,22 @@
-PORT=8000
-RELAYER_ADDRESS_PRIVATE_KEY=0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23b1d
-POOL_ADDRESS=0xC89Ce4735882C9F0f0FE26686c53074E09B0D550
+COMMON_POOL_ADDRESS=0x9b1f7F645351AF3631a656421eD2e40f2802E6c0
+COMMON_START_BLOCK=0
+COMMON_LOG_LEVEL=debug
+COMMON_RELAYER_REDIS_URL=127.0.0.1:6379
+COMMON_RPC_URL=http://127.0.0.1:8545
+
+RELAYER_PORT=8000
+RELAYER_ADDRESS_PRIVATE_KEY=0x6370fd033278c143179d81c5526140625662b8daa446c22ee2d73db3707e620c
+RELAYER_TOKEN_ADDRESS=0xCfEB869F69431e42cdB54A4F4f105C19C080A601
 RELAYER_GAS_LIMIT=2000000
 RELAYER_FEE=0
-MAX_NATIVE_AMOUNT_FAUCET=0
+RELAYER_MAX_NATIVE_AMOUNT_FAUCET=0
 
-TREE_UPDATE_PARAMS_PATH="./params/tree_params.bin"
-TX_VK_PATH="./params/transfer_verification_key.json"
+RELAYER_TREE_UPDATE_PARAMS_PATH="./params/tree_params.bin"
+RELAYER_TX_VK_PATH="./params/transfer_verification_key.json"
+RELAYER_STATE_DIR_PATH="./test/STATE_DIR/"
 
-SENT_TX_DELAY=30000
-GAS_PRICE_FALLBACK=
-GAS_PRICE_UPDATE_INTERVAL=
-GAS_PRICE_ESTIMATION_TYPE="web3"
-RELAYER_LOG_LEVEL=debug
-RELAYER_REDIS_URL=127.0.0.1:6379
-RPC_URL=http://127.0.0.1:8545
-LETSENCRYPT_HOST=example.com
-VIRTUAL_HOST=example.com
-LETSENCRYPT_EMAIL=mail@example.com
+RELAYER_INSUFFICIENT_BALANCE_CHECK_TIMEOUT=500
+RELAYER_SENT_TX_DELAY=2000
+RELAYER_GAS_PRICE_FALLBACK=
+RELAYER_GAS_PRICE_UPDATE_INTERVAL=100000
+RELAYER_GAS_PRICE_ESTIMATION_TYPE="eip1559-gas-estimation"