api3dao · dcroote · Feb 2, 2023 · Jan 20, 2023 · Jan 23, 2023 · Jan 23, 2023
diff --git a/.changeset/swift-kangaroos-cross.md b/.changeset/swift-kangaroos-cross.md
@@ -0,0 +1,8 @@
+---
+'@api3/airnode-adapter': minor
+'@api3/airnode-deployer': minor
+'@api3/airnode-node': minor
+'@api3/airnode-validator': minor
+---
+
+Add new \_minConfirmations reserved parameter to allow minConfirmations to be specified by a requester
diff --git a/packages/airnode-adapter/src/types.ts b/packages/airnode-adapter/src/types.ts
@@ -62,7 +62,8 @@ export type BaseResponseType = typeof baseResponseTypes[number];
 // Use might pass a complex type (e.g. int256[3][]) which we cannot type
 export type ResponseType = string;
 
-// Reserved parameters specific for response processing i.e. excludes _gasPrice
+// Reserved parameters specific for response processing
+// i.e. excludes _gasPrice and _minConfirmations
 export interface ResponseReservedParameters {
   _path?: string;
   _times?: string;

diff --git a/packages/airnode-adapter/test/fixtures/ois.ts b/packages/airnode-adapter/test/fixtures/ois.ts
@@ -78,6 +78,7 @@ export function buildOIS(overrides?: Partial<OIS>): OIS {
             default: '100000',
           },
           { name: '_gasPrice' },
+          { name: '_minConfirmations' },
         ],
         parameters: [
           {

diff --git a/packages/airnode-deployer/test/fixtures/config.aws.valid.json b/packages/airnode-deployer/test/fixtures/config.aws.valid.json
@@ -206,6 +206,9 @@
             },
             {
               "name": "_gasPrice"
+            },
+            {
+              "name": "_minConfirmations"
             }
           ],
           "parameters": [

diff --git a/packages/airnode-deployer/test/fixtures/config.gcp.valid.json b/packages/airnode-deployer/test/fixtures/config.gcp.valid.json
@@ -206,6 +206,9 @@
             },
             {
               "name": "_gasPrice"
+            },
+            {
+              "name": "_minConfirmations"
             }
           ],
           "parameters": [

diff --git a/packages/airnode-node/src/adapters/http/parameters.ts b/packages/airnode-node/src/adapters/http/parameters.ts
@@ -29,6 +29,7 @@ export function getReservedParameters(endpoint: Endpoint, requestParameters: Api
   const _times = getReservedParameterValue('_times', endpoint, requestParameters);
   const _type = getReservedParameterValue('_type', endpoint, requestParameters);
   const _gasPrice = getReservedParameterValue('_gasPrice', endpoint, requestParameters);
+  const _minConfirmations = getReservedParameterValue('_minConfirmations', endpoint, requestParameters);
 
-  return { _type, _path, _times, _gasPrice };
+  return { _type, _path, _times, _gasPrice, _minConfirmations };
 }
diff --git a/packages/airnode-node/src/api/index.test.ts b/packages/airnode-node/src/api/index.test.ts
@@ -14,7 +14,14 @@ describe('callApi', () => {
     const spy = jest.spyOn(adapter, 'buildAndExecuteRequest') as any;
     spy.mockResolvedValueOnce({ data: { price: 1000 } });
     const requestedGasPrice = '100000000';
-    const parameters = { _type: 'int256', _path: 'price', from: 'ETH', _gasPrice: requestedGasPrice };
+    const requestedMinConfirmations = '9';
+    const parameters = {
+      _type: 'int256',
+      _path: 'price',
+      from: 'ETH',
+      _gasPrice: requestedGasPrice,
+      _minConfirmations: requestedMinConfirmations,
+    };
 
     const [logs, res] = await callApi({
       type: 'regular',
@@ -32,6 +39,7 @@ describe('callApi', () => {
       },
       reservedParameterOverrides: {
         gasPrice: requestedGasPrice,
+        minConfirmations: requestedMinConfirmations,
       },
     });
     expect(spy).toHaveBeenCalledTimes(1);

diff --git a/packages/airnode-node/src/api/index.ts b/packages/airnode-node/src/api/index.ts
@@ -226,7 +226,7 @@ export async function processSuccessfulApiCall(
   const { endpointName, oisTitle, parameters } = aggregatedApiCall;
   const ois = config.ois.find((o) => o.title === oisTitle)!;
   const endpoint = ois.endpoints.find((e) => e.name === endpointName)!;
-  const { _type, _path, _times, _gasPrice } = getReservedParameters(endpoint, parameters);
+  const { _type, _path, _times, _gasPrice, _minConfirmations } = getReservedParameters(endpoint, parameters);
 
   const goPostProcessApiSpecifications = await go(() => postProcessApiSpecifications(rawResponse.data, endpoint));
   if (!goPostProcessApiSpecifications.success) {
@@ -263,7 +263,9 @@ export async function processSuccessfulApiCall(
         {
           success: true,
           data: { encodedValue: response.encodedValue, signature: goSignWithRequestId.data },
-          reservedParameterOverrides: _gasPrice ? { gasPrice: _gasPrice } : undefined,
+          reservedParameterOverrides:
+            // TODO is this exactly what we want? i.e. undefined behavior
+            _gasPrice || _minConfirmations ? { gasPrice: _gasPrice, minConfirmations: _minConfirmations } : undefined,
         },
       ];
     }

diff --git a/packages/airnode-node/src/evm/handlers/fetch-pending-requests.ts b/packages/airnode-node/src/evm/handlers/fetch-pending-requests.ts
@@ -15,6 +15,7 @@ export async function fetchPendingRequests(state: ProviderState<EVMProviderState
     blockHistoryLimit: state.settings.blockHistoryLimit,
     currentBlock: state.currentBlock!,
     minConfirmations: state.settings.minConfirmations,
+    mayOverrideMinConfirmations: state.settings.mayOverrideMinConfirmations,
     provider: state.provider,
     chainId,
   };

diff --git a/packages/airnode-node/src/evm/handlers/initialize-provider.ts b/packages/airnode-node/src/evm/handlers/initialize-provider.ts
@@ -53,6 +53,7 @@ async function fetchTransactionCounts(currentState: ProviderState<EVMProviderSta
     masterHDNode: currentState.masterHDNode,
     provider: currentState.provider,
     minConfirmations: currentState.settings.minConfirmations,
+    mayOverrideMinConfirmations: currentState.settings.mayOverrideMinConfirmations,
   };
   // This should not throw
   const [logs, res] = await transactionCounts.fetchBySponsor(sponsors, fetchOptions);

diff --git a/packages/airnode-node/src/evm/requests/event-logs.test.ts b/packages/airnode-node/src/evm/requests/event-logs.test.ts
@@ -54,6 +54,7 @@ describe('EVM event logs - fetch', () => {
       blockHistoryLimit: 300,
       currentBlock: 10716084,
       minConfirmations: 1,
+      mayOverrideMinConfirmations: false,
       provider: new ethers.providers.JsonRpcProvider(),
       chainId: '31137',
     };
@@ -109,6 +110,7 @@ describe('EVM event logs - fetch', () => {
       blockHistoryLimit: 30,
       currentBlock: 10716084,
       minConfirmations: 0,
+      mayOverrideMinConfirmations: false,
       provider: new ethers.providers.JsonRpcProvider(),
       chainId: '31137',
     };
@@ -139,6 +141,7 @@ describe('EVM event logs - fetch', () => {
       blockHistoryLimit: 300,
       currentBlock: 10716084,
       minConfirmations: 0,
+      mayOverrideMinConfirmations: false,
       provider: new ethers.providers.JsonRpcProvider(),
       chainId: '31137',
     };
@@ -154,6 +157,7 @@ describe('EVM event logs - fetch', () => {
       blockHistoryLimit: 99999999,
       currentBlock: 10716084,
       minConfirmations: 10,
+      mayOverrideMinConfirmations: false,
       provider: new ethers.providers.JsonRpcProvider(),
       chainId: '31137',
     };
@@ -177,6 +181,7 @@ describe('EVM event logs - fetch', () => {
       blockHistoryLimit: 30,
       currentBlock: 10716084,
       minConfirmations: 99999999,
+      mayOverrideMinConfirmations: false,
       provider: new ethers.providers.JsonRpcProvider(),
       chainId: '31137',
     };

diff --git a/packages/airnode-node/src/evm/requests/event-logs.ts b/packages/airnode-node/src/evm/requests/event-logs.ts
@@ -16,6 +16,7 @@ export interface FetchOptions {
   readonly blockHistoryLimit: number;
   readonly currentBlock: number;
   readonly minConfirmations: number;
+  readonly mayOverrideMinConfirmations: boolean;
   readonly provider: ethers.providers.JsonRpcProvider;
   readonly chainId: string;
 }
@@ -37,7 +38,10 @@ export async function fetch(options: FetchOptions): Promise<EVMEventLog[]> {
   // Protect against a potential negative fromBlock value
   const fromBlock = Math.max(0, options.currentBlock - options.blockHistoryLimit);
   // toBlock should always be >= fromBlock
-  const toBlock = Math.max(fromBlock, options.currentBlock - options.minConfirmations);
+  const toBlock = Math.max(
+    fromBlock,
+    options.currentBlock - (options.mayOverrideMinConfirmations ? 0 : options.minConfirmations)
+  );
 
   const filter: ethers.providers.Filter = {
     fromBlock,

diff --git a/packages/airnode-node/src/evm/transaction-counts.test.ts b/packages/airnode-node/src/evm/transaction-counts.test.ts
@@ -25,6 +25,7 @@ describe('fetchBySponsor', () => {
       masterHDNode: wallet.getMasterHDNode(config),
       provider: new ethers.providers.JsonRpcProvider(),
       minConfirmations: 0,
+      mayOverrideMinConfirmations: false,
     };
     const addresses = ['0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181', '0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181'];
     const [logs, res] = await transactions.fetchBySponsor(addresses, options);
@@ -41,6 +42,7 @@ describe('fetchBySponsor', () => {
       masterHDNode: wallet.getMasterHDNode(config),
       provider: new ethers.providers.JsonRpcProvider(),
       minConfirmations: 2,
+      mayOverrideMinConfirmations: false,
     };
     const addresses = ['0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181', '0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181'];
     const [logs, res] = await transactions.fetchBySponsor(addresses, options);
@@ -61,6 +63,7 @@ describe('fetchBySponsor', () => {
       masterHDNode: wallet.getMasterHDNode(config),
       provider: new ethers.providers.JsonRpcProvider(),
       minConfirmations: 0,
+      mayOverrideMinConfirmations: false,
     };
     const addresses = ['0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181', '0x99bd3a5A045066F1CEf37A0A952DFa87Af9D898E'];
     const [logs, res] = await transactions.fetchBySponsor(addresses, options);
@@ -84,6 +87,7 @@ describe('fetchBySponsor', () => {
       masterHDNode: wallet.getMasterHDNode(config),
       provider: new ethers.providers.JsonRpcProvider(),
       minConfirmations: 0,
+      mayOverrideMinConfirmations: false,
     };
     const addresses = ['0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181', '0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181'];
     const [logs, res] = await transactions.fetchBySponsor(addresses, options);
@@ -104,6 +108,7 @@ describe('fetchBySponsor', () => {
       masterHDNode: wallet.getMasterHDNode(config),
       provider: new ethers.providers.JsonRpcProvider(),
       minConfirmations: 0,
+      mayOverrideMinConfirmations: false,
     };
     const addresses = ['0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181', '0x69e2B095fbAc6C3f9E528Ef21882b86BF1595181'];
     const [logs, res] = await transactions.fetchBySponsor(addresses, options);

diff --git a/packages/airnode-node/src/evm/transaction-counts.ts b/packages/airnode-node/src/evm/transaction-counts.ts
@@ -16,6 +16,7 @@ interface FetchOptions {
   readonly masterHDNode: ethers.utils.HDNode;
   readonly provider: ethers.providers.JsonRpcProvider;
   readonly minConfirmations: number;
+  readonly mayOverrideMinConfirmations: boolean;
 }
 
 async function getWalletTransactionCount(
@@ -24,7 +25,10 @@ async function getWalletTransactionCount(
 ): Promise<LogsData<TransactionCountBySponsorAddress | null>> {
   const address = wallet.deriveSponsorWallet(options.masterHDNode, sponsorAddress).address;
   const operation = () =>
-    options.provider.getTransactionCount(address, options.currentBlock - options.minConfirmations);
+    options.provider.getTransactionCount(
+      address,
+      options.currentBlock - (options.mayOverrideMinConfirmations ? 0 : options.minConfirmations)
+    );
   const goCount = await go(operation, { retries: 1, attemptTimeoutMs: BLOCKCHAIN_CALL_ATTEMPT_TIMEOUT });
   if (!goCount.success) {
     const log = logger.pend('ERROR', `Unable to fetch transaction count for wallet:${address}`, goCount.error);

diff --git a/packages/airnode-node/src/providers/actions.test.ts b/packages/airnode-node/src/providers/actions.test.ts
@@ -150,6 +150,7 @@ describe('initialize', () => {
             logFormat: 'plain',
             logLevel: 'DEBUG',
             minConfirmations: 0,
+            mayOverrideMinConfirmations: true,
             name: 'Pocket Ethereum Mainnet',
             cloudProvider: {
               type: 'local',
@@ -204,6 +205,7 @@ describe('initialize', () => {
             logFormat: 'plain',
             logLevel: 'DEBUG',
             minConfirmations: 0,
+            mayOverrideMinConfirmations: true,
             name: 'Infura Sepolia',
             cloudProvider: {
               type: 'local',

diff --git a/packages/airnode-node/src/providers/state.test.ts b/packages/airnode-node/src/providers/state.test.ts
@@ -1,6 +1,7 @@
 import { ethers } from 'ethers';
 import * as state from './state';
 import * as fixtures from '../../test/fixtures';
+import { BLOCK_MIN_CONFIRMATIONS } from '../constants';
 import { EVMProviderState, ProviderState } from '../types';
 import { ChainConfig } from '../config';
 
@@ -79,6 +80,7 @@ describe('create', () => {
         logFormat: 'plain',
         logLevel: 'DEBUG',
         minConfirmations: 0,
+        mayOverrideMinConfirmations: true,
         name: 'Ganache test',
         cloudProvider: {
           type: 'local',
@@ -174,6 +176,7 @@ describe('create', () => {
         logFormat: 'plain',
         logLevel: 'DEBUG',
         minConfirmations: 3,
+        mayOverrideMinConfirmations: true,
         name: 'Ganache test',
         cloudProvider: {
           type: 'local',
@@ -339,3 +342,19 @@ describe('splitStatesBySponsorAddress', () => {
     ]);
   });
 });
+
+it('checks for the presence of a _minConfirmations reserved parameter', () => {
+  const newState = fixtures.buildEVMProviderState();
+
+  // buildEVMProviderState() doesn't set minConfirmations in chainConfig
+  expect(newState.settings.minConfirmations).toEqual(BLOCK_MIN_CONFIRMATIONS);
+
+  // _minConfirmations reserved parameter is set in buildOIS()
+  expect(newState.settings.mayOverrideMinConfirmations).toBe(true);
+
+  // Remove _minConfirmations reserved parameter
+  newState.config!.ois[0].endpoints[0].reservedParameters =
+    newState.config!.ois[0].endpoints[0].reservedParameters.filter((param) => param.name !== '_minConfirmations');
+
+  expect(state.checkForMinConfirmationsReservedParam(newState.config!)).toBe(false);
+});
diff --git a/packages/airnode-node/src/providers/state.ts b/packages/airnode-node/src/providers/state.ts
@@ -33,6 +33,11 @@ export function buildEVMState(
     logFormat: config.nodeSettings.logFormat,
     logLevel: config.nodeSettings.logLevel,
     minConfirmations: chain.minConfirmations || BLOCK_MIN_CONFIRMATIONS,
+    // If the _minConfirmations reserved parameter is set for one or more endpoints,
+    // a request may override minConfirmations, but we don't know if it will or the value
+    // until we actually fetch the requests, perform API calls, and extract reserved
+    // parameter overrides in processSuccessfulApiCall
+    mayOverrideMinConfirmations: checkForMinConfirmationsReservedParam(config),
     name: chainProviderName,
     cloudProvider: config.nodeSettings.cloudProvider,
     stage: config.nodeSettings.stage,
@@ -58,6 +63,14 @@ export function buildEVMState(
   };
 }
 
+// Checks all OIS endpoints for the presence of a _minConfirmations reserved parameter
+// which means that a requester may use a parameter to override the value.
+export function checkForMinConfirmationsReservedParam(config: Config): boolean {
+  return config.ois.some((ois) =>
+    ois.endpoints.some((endpoint) => endpoint.reservedParameters.some((param) => param.name === '_minConfirmations'))
+  );
+}
+
 export function update<T>(state: ProviderState<T>, newState: Partial<ProviderState<T>>): ProviderState<T> {
   return { ...state, ...newState };
 }

diff --git a/packages/airnode-node/src/types.ts b/packages/airnode-node/src/types.ts
@@ -140,6 +140,7 @@ export interface ProviderSettings extends CoordinatorSettings {
   readonly chainType: ChainType;
   readonly chainOptions: ChainOptions;
   readonly minConfirmations: number;
+  readonly mayOverrideMinConfirmations: boolean;
   readonly name: string;
   readonly url: string;
   readonly xpub: string;
@@ -231,6 +232,7 @@ export interface RegularApiCallSuccessResponse {
   data: { encodedValue: string; signature: string };
   reservedParameterOverrides?: {
     gasPrice?: string;
+    minConfirmations?: string;
   };
 }
 
@@ -249,6 +251,7 @@ export interface ApiCallErrorResponse {
   errorMessage: string;
   reservedParameterOverrides?: {
     gasPrice?: string;
+    minConfirmations?: string;
   };
 }
 

diff --git a/packages/airnode-node/test/e2e/requester-fulfill.feature.ts b/packages/airnode-node/test/e2e/requester-fulfill.feature.ts
@@ -84,5 +84,5 @@ it('submits fulfillment with the gas price overridden', async () => {
     tx.gasPrice?.toString() === requestedGasPrice;
   });
 
-  expect(fulfillmentLog).not.toBeUndefined();
+  expect(fulfillmentLog).toBeDefined();
 });
diff --git a/packages/airnode-node/test/fixtures/config/config.valid.json b/packages/airnode-node/test/fixtures/config/config.valid.json
@@ -189,6 +189,9 @@
             },
             {
               "name": "_gasPrice"
+            },
+            {
+              "name": "_minConfirmations"
             }
           ],
           "parameters": [

diff --git a/packages/airnode-node/test/fixtures/config/ois.ts b/packages/airnode-node/test/fixtures/config/ois.ts
@@ -68,6 +68,7 @@ export function buildOIS(ois?: Partial<OIS>): OIS {
             default: '100000',
           },
           { name: '_gasPrice' },
+          { name: '_minConfirmations' },
         ],
         parameters: [
           {

diff --git a/packages/airnode-validator/src/config/config.ts b/packages/airnode-validator/src/config/config.ts
@@ -194,7 +194,9 @@ export const chainConfigSchema = z
     blockHistoryLimit: z.number().int().optional(), // Defaults to BLOCK_COUNT_HISTORY_LIMIT defined in airnode-node
     contracts: chainContractsSchema,
     id: z.string(),
-    minConfirmations: z.number().int().optional(), // Defaults to BLOCK_MIN_CONFIRMATIONS defined in airnode-node
+    // Defaults to BLOCK_MIN_CONFIRMATIONS defined in airnode-node but may be overridden
+    // by a requester if the _minConfirmations reserved parameter is configured
+    minConfirmations: z.number().int().optional(),
     type: chainTypeSchema,
     options: chainOptionsSchema,
     providers: providersSchema,

diff --git a/packages/airnode-validator/test/fixtures/config.valid.json b/packages/airnode-validator/test/fixtures/config.valid.json
@@ -195,6 +195,9 @@
             },
             {
               "name": "_gasPrice"
+            },
+            {
+              "name": "_minConfirmations"
             }
           ],
           "parameters": [