@o1-labs/mina-archive-node-graphql 0.0.6 → 2.0.0

package/src/server/rate-limit.ts

@@ -0,0 +1,274 @@
+import type { Plugin } from 'graphql-yoga';
+
+export {
+  useRateLimit,
+  createRateLimiter,
+  resolveRateLimitConfig,
+  RATE_LIMIT_DEFAULTS,
+};
+export type { RateLimitConfig };
+
+/** Probes must never be throttled, so orchestrators keep working. */
+const EXEMPT_PATHS = new Set(['/healthcheck', '/readiness']);
+
+/**
+ * Global, per-client-IP request rate limiting. A public GraphQL endpoint with no
+ * throttle lets one client monopolise the server and the backing Postgres. This
+ * is a coarse first line of defence applied before any GraphQL work happens.
+ *
+ * The counter is in-memory and therefore per-instance: behind multiple replicas
+ * each enforces its own share of the limit. A shared store (e.g. Redis) is the
+ * follow-up for exact cross-replica limits — see the deployment hardening issue.
+ */
+interface RateLimitConfig {
+  /** Max requests allowed per client per window. `0` disables rate limiting. */
+  max: number;
+  /** Length of the fixed window in milliseconds. */
+  windowMs: number;
+  /**
+   * Number of trusted proxy hops in front of this server. `0` ignores
+   * forwarding headers entirely and keys on the socket address, which is the
+   * only safe reading when the server is directly exposed.
+   */
+  trustProxy: number;
+  /**
+   * Whether TRUST_PROXY was explicitly and validly set. No default is correct
+   * for both topologies: socket-keying behind a load balancer puts every client
+   * in one bucket, while trusting X-Forwarded-For without a hop count lets any
+   * caller mint a fresh bucket.
+   */
+  trustProxyConfigured: boolean;
+}
+
+const RATE_LIMIT_DEFAULTS: RateLimitConfig = {
+  max: 600,
+  windowMs: 60_000,
+  trustProxy: 0,
+  trustProxyConfigured: false,
+};
+
+type EnvSource = Record<string, string | undefined>;
+
+/**
+ * Parse a non-negative integer from an env value, falling back to `fallback` when
+ * it is missing or malformed. We never throw, so a typo can't disable the limiter
+ * by accident — it reverts to the safe default.
+ */
+function intFromEnv(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === '') return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) return fallback;
+  return parsed;
+}
+
+/**
+ * Parse TRUST_PROXY strictly. Missing or malformed means "not configured", not
+ * "directly exposed", so a typo cannot turn into a global shared bucket behind
+ * a load balancer.
+ */
+function hopsFromEnv(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === '') return undefined;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) return undefined;
+  return parsed;
+}
+
+function resolveRateLimitConfig(env: EnvSource = process.env): RateLimitConfig {
+  const hops = hopsFromEnv(env.TRUST_PROXY);
+  return {
+    max: intFromEnv(env.RATE_LIMIT_MAX, RATE_LIMIT_DEFAULTS.max),
+    windowMs: Math.max(
+      1,
+      intFromEnv(env.RATE_LIMIT_WINDOW_MS, RATE_LIMIT_DEFAULTS.windowMs)
+    ),
+    trustProxy: hops ?? RATE_LIMIT_DEFAULTS.trustProxy,
+    trustProxyConfigured: hops !== undefined,
+  };
+}
+
+interface RateLimitResult {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  resetAt: number;
+}
+
+/**
+ * Fixed-window counter keyed by client id. `now` is injectable so the windowing
+ * logic can be tested deterministically. Counting is independent of how the id
+ * is derived, so this takes only the window options.
+ */
+function createRateLimiter(
+  config: Pick<RateLimitConfig, 'max' | 'windowMs'>,
+  now: () => number = Date.now
+) {
+  const buckets = new Map<string, { count: number; resetAt: number }>();
+
+  function check(id: string): RateLimitResult {
+    const time = now();
+    let bucket = buckets.get(id);
+    if (!bucket || time >= bucket.resetAt) {
+      bucket = { count: 0, resetAt: time + config.windowMs };
+      buckets.set(id, bucket);
+    }
+    bucket.count += 1;
+    return {
+      allowed: bucket.count <= config.max,
+      limit: config.max,
+      remaining: Math.max(0, config.max - bucket.count),
+      resetAt: bucket.resetAt,
+    };
+  }
+
+  /** Drop expired buckets so memory doesn't grow with unique client count. */
+  function prune(): void {
+    const time = now();
+    for (const [id, bucket] of buckets) {
+      if (time >= bucket.resetAt) buckets.delete(id);
+    }
+  }
+
+  return { check, prune, size: () => buckets.size };
+}
+
+type MaybeNodeSocket = {
+  req?: { socket?: { remoteAddress?: string } };
+  socket?: { remoteAddress?: string };
+};
+
+function socketAddress(serverContext: unknown): string {
+  const ctx = serverContext as MaybeNodeSocket;
+  return ctx?.req?.socket?.remoteAddress ?? ctx?.socket?.remoteAddress ?? 'unknown';
+}
+
+/**
+ * Identify the client, trusting forwarding headers only as far as `trustProxy`
+ * hops allow.
+ *
+ * `X-Forwarded-For` is client-supplied and every proxy *appends* to it, so the
+ * left-hand entries are whatever the caller sent and cannot be trusted: reading
+ * the first hop lets one source rotate the header to mint a fresh bucket per
+ * request and evade the limit entirely (while growing the bucket Map). Only the
+ * rightmost entries — appended by proxies we actually control — are meaningful,
+ * so with N trusted hops the real client is the Nth entry from the right.
+ *
+ * Honouring the header at all still matters: it is what keeps NAT'd and
+ * LB-fronted clients in their own buckets instead of collapsing onto one shared
+ * address. Hence a hop count rather than a blanket on/off.
+ */
+function clientId(
+  request: Request,
+  serverContext: unknown,
+  trustProxy: number
+): string {
+  if (trustProxy <= 0) return socketAddress(serverContext);
+
+  const forwarded = request.headers
+    .get('x-forwarded-for')
+    ?.split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (forwarded?.length) {
+    // Undefined when the chain is shorter than the configured hop count (a
+    // misconfiguration, or a request injected inside the trust boundary) —
+    // fall through to the socket rather than trust an attacker-chosen entry.
+    const client = forwarded[forwarded.length - trustProxy];
+    if (client) return client;
+  }
+
+  // Single-valued and overwritten by the adjacent proxy, so it carries no hop
+  // structure; only meaningful once we've established there is a proxy at all.
+  const realIp = request.headers.get('x-real-ip')?.trim();
+  if (realIp) return realIp;
+
+  return socketAddress(serverContext);
+}
+
+/**
+ * Yoga plugin that rejects over-limit requests with HTTP 429 before they reach
+ * GraphQL parsing/execution. Returns a no-op plugin when `max` is 0 (disabled).
+ */
+function useRateLimit(
+  env: EnvSource = process.env,
+  warn: (message: string) => void = console.warn
+): Plugin {
+  const config = resolveRateLimitConfig(env);
+  if (config.max <= 0) return {};
+
+  if (!config.trustProxyConfigured) {
+    warn(
+      '[rate-limit] TRUST_PROXY is not set — rate limiting is DISABLED. No ' +
+        'default is safe: keying on the socket address behind a load balancer ' +
+        'puts every client in one bucket, and trusting X-Forwarded-For without ' +
+        'a hop count lets any caller bypass the limit. Set TRUST_PROXY=0 for ' +
+        'a directly-exposed server, or to the number of proxy hops in front of ' +
+        'this API. NOTE: a GCP external Application Load Balancer appends TWO ' +
+        'entries (client IP, then forwarding-rule IP), so a bare GCP LB is 2, ' +
+        'plus 1 per extra in-cluster proxy. Set RATE_LIMIT_MAX=0 to silence this.'
+    );
+    return {};
+  }
+
+  const limiter = createRateLimiter(config);
+
+  // TRUST_PROXY=0 is the safe default, but it's wrong for the expected
+  // production topology, and the symptom — every client sharing one bucket
+  // behind the LB — otherwise appears only as unexplained throttling. Warn
+  // once on the first forwarded request rather than per request.
+  let warnedAboutProxy = config.trustProxy > 0;
+  const warnIfProxied = (request: Request) => {
+    const chain = request.headers.get('x-forwarded-for');
+    if (warnedAboutProxy || chain === null) return;
+    warnedAboutProxy = true;
+    const hops = chain.split(',').filter((part) => part.trim()).length;
+    warn(
+      '[rate-limit] TRUST_PROXY=0 but requests carry X-Forwarded-For — every ' +
+        'client behind the proxy shares one rate-limit bucket. Set TRUST_PROXY ' +
+        `to the number of proxy hops in front of this API (observed chain ` +
+        `length: ${hops}) to bucket clients individually.`
+    );
+  };
+  // Periodically reclaim memory from expired buckets; unref'd so it never keeps
+  // the process alive on shutdown.
+  const sweep = setInterval(() => limiter.prune(), config.windowMs);
+  if (typeof sweep.unref === 'function') sweep.unref();
+
+  return {
+    onRequest({ request, serverContext, url, endResponse, fetchAPI }) {
+      if (EXEMPT_PATHS.has(url.pathname)) return;
+      // Yoga's CORS plugin answers OPTIONS before user-land plugins today, but
+      // keep the exemption local too: a throttled preflight is an opaque browser
+      // CORS error rather than a useful 429.
+      if (request.method === 'OPTIONS') return;
+      warnIfProxied(request);
+
+      const result = limiter.check(
+        clientId(request, serverContext, config.trustProxy)
+      );
+      if (result.allowed) return;
+
+      const retryAfter = Math.max(1, Math.ceil((result.resetAt - Date.now()) / 1000));
+      endResponse(
+        new fetchAPI.Response(
+          JSON.stringify({
+            errors: [
+              {
+                message: 'Too many requests. Please retry later.',
+                extensions: { code: 'RATE_LIMITED' },
+              },
+            ],
+          }),
+          {
+            status: 429,
+            headers: {
+              'content-type': 'application/json',
+              'retry-after': String(retryAfter),
+              'x-ratelimit-limit': String(result.limit),
+              'x-ratelimit-remaining': String(result.remaining),
+            },
+          }
+        )
+      );
+    },
+  };
+}

package/src/server/readiness.ts

@@ -0,0 +1,78 @@
+import type { Plugin } from 'graphql-yoga';
+import type { DatabaseAdapter } from '../db/archive-node-adapter/archive-node-adapter.interface.js';
+
+export { useReadiness, READINESS_PATH };
+
+/**
+ * Readiness endpoint path. Distinct from Yoga's built-in `/healthcheck`, which is
+ * a *liveness* probe (the process is up). Readiness additionally checks that the
+ * database is reachable, so an orchestrator can stop routing traffic to an
+ * instance whose Postgres is down without killing the pod outright.
+ */
+const READINESS_PATH = '/readiness';
+
+/**
+ * Upper bound on one readiness ping. Keep it below the orchestrator probe
+ * timeout so the server answers 503 itself instead of letting the probe hang.
+ */
+const DEFAULT_PING_TIMEOUT_MS = 2000;
+
+function pingTimeoutFromEnv(value: string | undefined): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0
+    ? parsed
+    : DEFAULT_PING_TIMEOUT_MS;
+}
+
+/** Resolves, never rejects: the probe endpoint must not return 500. */
+async function pingWithin(
+  db: Pick<DatabaseAdapter, 'ping'>,
+  timeoutMs: number
+): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<boolean>((resolve) => {
+    timer = setTimeout(() => {
+      console.warn(`[readiness] database ping exceeded ${timeoutMs}ms`);
+      resolve(false);
+    }, timeoutMs);
+  });
+  const answered = Promise.resolve()
+    .then(() => db.ping())
+    .catch(() => false);
+
+  try {
+    return await Promise.race([answered, timedOut]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/**
+ * Yoga plugin serving a readiness probe at `READINESS_PATH`. Returns 200 when the
+ * database answers a trivial query, 503 otherwise. Registered ahead of other
+ * request hooks so probes are never throttled or otherwise interfered with.
+ */
+function useReadiness(
+  db: Pick<DatabaseAdapter, 'ping'>,
+  timeoutMs = pingTimeoutFromEnv(process.env.READINESS_PING_TIMEOUT_MS)
+): Plugin {
+  return {
+    async onRequest({ url, endResponse, fetchAPI }) {
+      if (url.pathname.replace(/\/$/, '') !== READINESS_PATH) return;
+
+      const ready = await pingWithin(db, timeoutMs);
+      endResponse(
+        new fetchAPI.Response(
+          JSON.stringify({ status: ready ? 'ready' : 'not ready' }),
+          {
+            status: ready ? 200 : 503,
+            headers: {
+              'content-type': 'application/json',
+              'cache-control': 'no-store',
+            },
+          }
+        )
+      );
+    },
+  };
+}

package/src/server/request-logging.ts

@@ -0,0 +1,83 @@
+import { randomUUID } from 'node:crypto';
+import type { Plugin } from 'graphql-yoga';
+import { logger as defaultLogger } from './logger.js';
+import type { Logger } from './logger.js';
+
+export { useRequestLogging, requestIdFor };
+
+/** Paths whose requests are not access-logged (frequent orchestrator probes). */
+const QUIET_PATHS = new Set(['/healthcheck', '/readiness']);
+/** Max characters kept from an inbound X-Request-Id. */
+const MAX_REQUEST_ID_LENGTH = 128;
+/** Printable ASCII only, minus quote and backslash. */
+const UNSAFE_REQUEST_ID_CHARS = /[^\x20-\x7e]|["\\]/g;
+
+/**
+ * Correlation id per in-flight request. Stored in a WeakMap so it is dropped
+ * automatically once the request is garbage-collected. Other log sites (e.g. the
+ * GraphQL error logger) can look it up to tie their lines to the access log.
+ */
+const requestIds = new WeakMap<Request, string>();
+
+function requestIdFor(request: Request): string | undefined {
+  return requestIds.get(request);
+}
+
+function sanitizeRequestId(raw: string | null): string {
+  if (!raw) return randomUUID();
+  const cleaned = raw
+    .replace(UNSAFE_REQUEST_ID_CHARS, '')
+    .slice(0, MAX_REQUEST_ID_LENGTH)
+    .trim();
+  return cleaned.length > 0 ? cleaned : randomUUID();
+}
+
+function pathOf(rawUrl: string): string {
+  try {
+    return new URL(rawUrl).pathname;
+  } catch {
+    return rawUrl;
+  }
+}
+
+/**
+ * Yoga plugin that assigns each request a correlation id (honouring an inbound
+ * bounded `X-Request-Id`) and emits one structured access-log line per request
+ * with the id, method, path, status, and duration. Probe endpoints are skipped
+ * to avoid log spam. `log` is injectable for tests.
+ */
+function useRequestLogging(log: Logger = defaultLogger): Plugin {
+  const startTimes = new WeakMap<Request, number>();
+  return {
+    onRequest({ request }) {
+      const id = sanitizeRequestId(request.headers.get('x-request-id'));
+      requestIds.set(request, id);
+      startTimes.set(request, Date.now());
+    },
+    onResponse({ request, response }) {
+      const path = pathOf(request.url);
+      if (QUIET_PATHS.has(path)) return;
+
+      let id = requestIds.get(request);
+      let start = startTimes.get(request);
+      if (id === undefined || start === undefined) {
+        // CORS and health-check plugins can short-circuit before onRequest, but
+        // onResponse still runs. Backfill so access lines remain correlated.
+        id = sanitizeRequestId(request.headers.get('x-request-id'));
+        start = Date.now();
+        requestIds.set(request, id);
+        startTimes.set(request, start);
+      }
+      log.info(
+        {
+          requestId: id,
+          method: request.method,
+          path,
+          status: response.status,
+          durationMs: Date.now() - start,
+        },
+        'request completed'
+      );
+    },
+  };
+}

package/src/server/server.ts

@@ -1,30 +1,85 @@
-import { createYoga, LogLevel } from 'graphql-yoga';
+import { inspect } from 'node:util';
+import { createYoga } from 'graphql-yoga';
 import { createServer } from 'http';
 import { Plugin } from '@envelop/core';
 import { schema } from '../resolvers.js';
 import type { GraphQLContext } from '../context.js';
+import { parseBoolean } from '../config.js';
+import { useReadiness } from './readiness.js';
+import { resolveCorsOptions, warnIfCorsDisabled } from './cors.js';
+import { logger, resolveYogaLogLevel } from './logger.js';
 
-export { BLOCK_RANGE_SIZE, ENABLE_BLOCK_TRANSACTION_DETAILS, buildServer };
+export {
+  BLOCK_RANGE_SIZE,
+  ZKAPP_COMMAND_RANGE_SIZE,
+  ZKAPP_COMMAND_ACCOUNT_UPDATE_LIMIT,
+  ENABLE_BLOCK_TRANSACTION_DETAILS,
+  ENABLE_ZKAPP_COMMANDS_QUERY,
+  buildYoga,
+  buildServer,
+};
 
-const LOG_LEVEL = (process.env.LOG_LEVEL as LogLevel) || 'info';
 const BLOCK_RANGE_SIZE = Number(process.env.BLOCK_RANGE_SIZE) || 10000;
-const ENABLE_BLOCK_TRANSACTION_DETAILS =
-  process.env.ENABLE_BLOCK_TRANSACTION_DETAILS === 'true';
+const ENABLE_BLOCK_TRANSACTION_DETAILS = parseBoolean(
+  process.env.ENABLE_BLOCK_TRANSACTION_DETAILS
+);
+// The zkappCommands range query is far heavier than block transaction detail —
+// it expands account updates — so it gets its own switch rather than riding on
+// that flag. Default off: an operator opts in deliberately.
+const ENABLE_ZKAPP_COMMANDS_QUERY = parseBoolean(
+  process.env.ENABLE_ZKAPP_COMMANDS_QUERY
+);
+const ZKAPP_COMMAND_RANGE_SIZE =
+  Number(process.env.ZKAPP_COMMAND_RANGE_SIZE) || 1000;
+const ZKAPP_COMMAND_ACCOUNT_UPDATE_LIMIT =
+  Number(process.env.ZKAPP_COMMAND_ACCOUNT_UPDATE_LIMIT) || 5000;
+const YOGA_LOG_LEVEL = resolveYogaLogLevel();
 
-function buildServer(context: GraphQLContext, plugins: Plugin[]) {
-  const yoga = createYoga<GraphQLContext>({
+const yogaLog =
+  (level: 'debug' | 'info' | 'warn' | 'error') =>
+  (...args: unknown[]) => {
+    const err = args.find((arg): arg is Error => arg instanceof Error);
+    const msg = args
+      .filter((arg) => !(arg instanceof Error))
+      .map((arg) =>
+        typeof arg === 'string' ? arg : inspect(arg, { depth: 3 })
+      )
+      .join(' ');
+    logger[level](err ? { err } : {}, msg || 'yoga');
+  };
+
+function buildYoga(context: GraphQLContext, plugins: Plugin[]) {
+  const cors = resolveCorsOptions();
+
+  return createYoga<GraphQLContext>({
     schema,
-    logging: LOG_LEVEL,
+    logging:
+      YOGA_LOG_LEVEL === false
+        ? false
+        : {
+            debug: yogaLog('debug'),
+            info: yogaLog('info'),
+            warn: yogaLog('warn'),
+            error: yogaLog('error'),
+          },
     graphqlEndpoint: '/',
     landingPage: false,
+    // Liveness — the process is up and serving HTTP.
     healthCheckEndpoint: '/healthcheck',
-    graphiql: process.env.ENABLE_GRAPHIQL === 'true' ? true : false,
-    plugins,
-    cors: {
-      origin: process.env.CORS_ORIGIN ?? '*',
-      methods: ['GET', 'POST'],
-    },
+    graphiql: parseBoolean(process.env.ENABLE_GRAPHIQL),
+    // Mask unexpected (non-GraphQLError) errors so internal details — SQL,
+    // connection strings, stack traces — never reach clients. `isDev: false`
+    // keeps Envelop from attaching original errors when NODE_ENV=development.
+    maskedErrors: { isDev: false },
+    // Readiness (DB reachable) is prepended so probes short-circuit before any
+    // other request hook (e.g. rate limiting) can interfere with them.
+    plugins: [useReadiness(context.db_client), ...plugins],
+    cors,
     context,
   });
-  return createServer(yoga);
+}
+
+function buildServer(context: GraphQLContext, plugins: Plugin[]) {
+  warnIfCorsDisabled(resolveCorsOptions());
+  return createServer(buildYoga(context, plugins));
 }

package/src/services/actions-service/actions-service.ts

@@ -12,7 +12,7 @@ import { DEFAULT_TOKEN_ID } from '../../blockchain/constants.js';
 import { createBlockInfo } from '../../blockchain/utils.js';
 import {
   getActionsQuery,
-  checkActionState,
+  resolveActionStateBoundary,
 } from '../../db/sql/events-actions/queries.js';
 import {
   partitionBlocks,
@@ -28,6 +28,7 @@ import {
 } from '../../tracing/tracer.js';
 import {
   throwActionStateError,
+  throwActionStateOutOfRangeError,
   throwBlockRangeError,
 } from '../../errors/error.js';
 import { BLOCK_RANGE_SIZE } from '../../server/server.js';
@@ -70,32 +71,73 @@ class ActionsService implements IActionsService {
     return actionsData;
   }
 
-  async executeActionsQuery(input: ActionFilterOptionsInput) {
-    const { address, to, from, endActionState, fromActionState } = input;
+  /**
+   * Resolves an action state to the block height at which this account's action
+   * state first became that value, and raises a typed error when the request
+   * cannot be answered completely.
+   *
+   * The filter has to use a position on the chain. It used to compare
+   * `zkapp_field.id`, the interning key of the value, which records when a value
+   * was first written to the archive and not where it sits on the chain. Those
+   * two orders disagree on any archive that was filled out of chain order, and
+   * the filter then dropped real actions.
+   */
+  async resolveBoundaryHeight(
+    argumentName: 'fromActionState' | 'endActionState',
+    actionState: string,
+    address: string,
+    tokenId: string,
+    from?: number,
+    to?: number
+  ): Promise<string | undefined> {
+    const [boundary] = await resolveActionStateBoundary(
+      this.client,
+      address,
+      tokenId,
+      actionState,
+      from?.toString(),
+      to?.toString()
+    );
 
-    // Check if action states exist.
-    if (fromActionState) {
-      const fromActionStateExists = await checkActionState(
-        this.client,
-        fromActionState
+    if (!boundary || boundary.boundary_height === null) {
+      throwActionStateError(
+        `${argumentName} ${actionState} is not an action state of account ${address}`
       );
-      if (!fromActionStateExists || !fromActionStateExists.length) {
-        throwActionStateError(
-          `fromActionState ${fromActionState} does not exist`
-        );
-      }
+      return undefined;
     }
-    if (endActionState) {
-      const endActionStateExists = await checkActionState(
-        this.client,
-        endActionState
+
+    const boundaryHeight = Number(boundary.boundary_height);
+    const windowStart = Number(boundary.window_start);
+
+    // The checkpoint is older than the block range this query covers. For
+    // `fromActionState` that alone does not make the answer wrong: if the account
+    // emitted no action between the checkpoint and the start of the window, every
+    // action in the window is still the complete answer, and
+    // `state_entering_window` says so. Rejecting in that case would break the
+    // common case of a quiet zkApp folding from its genesis action state, which
+    // is the default o1js path because o1js sends no `from`/`to`.
+    //
+    // `endActionState` gets no such rescue. It bounds the request from above, so
+    // a checkpoint below the window means the whole requested span is below the
+    // window and every action in it is missing. An empty answer would be silently
+    // wrong, which is the failure this change exists to remove.
+    const answerIsStillComplete =
+      argumentName === 'fromActionState' && boundary.state_entering_window === true;
+    if (boundaryHeight < windowStart && !answerIsStillComplete) {
+      throwActionStateOutOfRangeError(
+        `${argumentName} ${actionState} is at block height ${boundaryHeight}, which is below the ` +
+          `queried block range starting at ${windowStart}, and this account emitted actions in ` +
+          `between. The answer would be missing them. Retry with from: ${boundaryHeight} ` +
+          `(at most ${BLOCK_RANGE_SIZE} blocks per query, so paginate if needed).`
       );
-      if (!endActionStateExists || !endActionStateExists.length) {
-        throwActionStateError(
-          `endActionState ${endActionState} does not exist`
-        );
-      }
     }
+
+    return boundary.boundary_height;
+  }
+
+  async executeActionsQuery(input: ActionFilterOptionsInput) {
+    const { address, to, from, endActionState, fromActionState } = input;
+
     let { tokenId, status } = input;
 
     tokenId ||= DEFAULT_TOKEN_ID;
@@ -109,6 +151,27 @@ class ActionsService implements IActionsService {
       );
     }
 
+    const fromActionStateHeight = fromActionState
+      ? await this.resolveBoundaryHeight(
+          'fromActionState',
+          fromActionState.toString(),
+          address,
+          tokenId,
+          from ?? undefined,
+          to ?? undefined
+        )
+      : undefined;
+    const endActionStateHeight = endActionState
+      ? await this.resolveBoundaryHeight(
+          'endActionState',
+          endActionState.toString(),
+          address,
+          tokenId,
+          from ?? undefined,
+          to ?? undefined
+        )
+      : undefined;
+
     return getActionsQuery(
       this.client,
       address,
@@ -116,8 +179,8 @@ class ActionsService implements IActionsService {
       status,
       to?.toString(),
       from?.toString(),
-      fromActionState?.toString(),
-      endActionState?.toString()
+      fromActionStateHeight,
+      endActionStateHeight
     );
   }