adding docs, tests, cleaning up a bit

schema.graphql

@@ -1,24 +1,66 @@
+"""
+Filter for the consensus status of the block
+"""
 enum BlockStatusFilter {
+  """
+  All blocks
+  """
   ALL
+  """
+  Only pending blocks
+  """
   PENDING
+  """
+  Only canonical (finalized) blocks
+  """
   CANONICAL
 }
 
+"""
+Filter events from a specific account
+
+**WARNING**: The graphQL schema server will limit the block scan range to a fixed number of blocks.  The default is 10,000 blocks, but can be changed by the host.
+It is the responsibility of the client to use a block range that is within the limit, which will guarantee that all events are eventually returned.  It is possible to get a partial result if you do not specify both a `from` and a `to` parameter.
+"""
 input EventFilterOptionsInput {
   address: String!
   tokenId: String
   status: BlockStatusFilter
+  """
+  Mina block height to filter events to, exclusive
+  """
   to: Int
+  """
+  Mina block height to filter events from, inclusive
+  """
   from: Int
 }
 
+"""
+Filter actions from a specific account
+
+**WARNING**: The graphQL schema server will limit the block scan range to a fixed number of blocks.  The default is 10,000 blocks, but can be changed by the host.
+It is the responsibility of the client to use a block range that is within the limit, which will guarantee that all actions are eventually returned.  It is possible to get a partial result if you do not specify both a `from` and a `to` parameter.
+"""
 input ActionFilterOptionsInput {
   address: String!
   tokenId: String
   status: BlockStatusFilter
+  """
+  Mina block height to filter actions to, exclusive
+  """
   to: Int
+  """
+  Mina block height to filter actions from, inclusive
+  """
   from: Int
+  """
+  Filter for actions that happened after this action state, inclusive
+  """
   fromActionState: String
+  """
+  Filter for actions that happened before this action state, inclusive
+  """
   endActionState: String
 }
 
@@ -56,7 +98,7 @@ type TransactionInfo {
   hash: String!
   memo: String!
   authorizationKind: String!
-  sequenceNumber: Int! # TODO: Is it ok to make this required?
+  sequenceNumber: Int!
   zkappAccountUpdateIds: [Int]!
 }
 
@@ -80,7 +122,13 @@ type ActionOutput {
   actionState: ActionStates!
 }
 
+"""
+Metadata about the network
+"""
 type NetworkStateOutput {
+  """
+  Returns the latest pending and canonical block heights that are synced by the archive node.  If the archive node is not fully synced, the pending block height will be lower than the actual network state.  Wait some time for the archive node to get back in sync.
+  """
   maxBlockHeight: MaxBlockHeightInfo
 }
 

src/db/sql/events-actions/queries.ts

@@ -1,8 +1,7 @@
 import type postgres from 'postgres';
 import { ArchiveNodeDatabaseRow } from './types.js';
 import { BlockStatusFilter } from '../../../blockchain/types.js';
-
-const BLOCK_RANGE_SIZE = Number(process.env.BLOCK_RANGE_SIZE) || 10000;
+import { BLOCK_RANGE_SIZE } from '../../../server/server.js';
 
 function fullChainCTE(db_client: postgres.Sql, from?: string, to?: string) {
   let toAsNum = to ? Number(to) : undefined;
@@ -53,7 +52,7 @@ function fullChainCTE(db_client: postgres.Sql, from?: string, to?: string) {
             // If fromAsNum is not undefined, then we have also set toAsNum and can safely query the range
             // If no params ar provided, then we query the last BLOCK_RANGE_SIZE blocks
             fromAsNum
-              ? db_client`AND b.height >= ${fromAsNum} AND b.height >= ${toAsNum!}`
+              ? db_client`AND b.height >= ${fromAsNum} AND b.height < ${toAsNum!}`
               : db_client`AND b.height >= (
                 SELECT MAX(b2.height)
                 FROM blocks b2

src/errors/error.ts

@@ -1,6 +1,6 @@
 import { GraphQLError } from 'graphql';
 
-export { throwGraphQLError, throwActionStateError };
+export { throwGraphQLError, throwActionStateError, throwBlockRangeError };
 
 function throwGraphQLError(message: string, code?: string, status?: number) {
   throw new GraphQLError(message, {
@@ -14,3 +14,7 @@ function throwGraphQLError(message: string, code?: string, status?: number) {
 function throwActionStateError(message: string) {
   throwGraphQLError(message, 'ACTION_STATE_NOT_FOUND', 400);
 }
+
+function throwBlockRangeError(message: string) {
+  throwGraphQLError(message, 'BLOCK_RANGE_ERROR', 400);
+}

src/resolvers.ts

@@ -1,6 +1,7 @@
 import { makeExecutableSchema } from '@graphql-tools/schema';
 import { loadSchemaSync } from '@graphql-tools/load';
 import { GraphQLFileLoader } from '@graphql-tools/graphql-file-loader';
+import { GraphQLError } from 'graphql';
 
 import { Resolvers } from './resolvers-types.js';
 import {

src/server/server.ts

@@ -4,9 +4,10 @@ import { Plugin } from '@envelop/core';
 import { schema } from '../resolvers.js';
 import type { GraphQLContext } from '../context.js';
 
-export { buildServer };
+export { BLOCK_RANGE_SIZE, buildServer };
 
 const LOG_LEVEL = (process.env.LOG_LEVEL as LogLevel) || 'info';
+const BLOCK_RANGE_SIZE = Number(process.env.BLOCK_RANGE_SIZE) || 10000;
 
 function buildServer(context: GraphQLContext, plugins: Plugin[]) {
   const yoga = createYoga<GraphQLContext>({

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

@@ -26,7 +26,14 @@ import {
   TracingState,
   extractTraceStateFromOptions,
 } from '../../tracing/tracer.js';
-import { throwActionStateError } from '../../errors/error.js';
+import {
+  throwActionStateError,
+  throwBlockRangeError,
+} from '../../errors/error.js';
+import dotenv from 'dotenv';
+import { BLOCK_RANGE_SIZE } from '../../server/server.js';
+
+dotenv.config();
 
 export { ActionsService };
 
@@ -97,7 +104,12 @@ class ActionsService implements IActionsService {
     tokenId ||= DEFAULT_TOKEN_ID;
     status ||= BlockStatusFilter.all;
     if (to && from && to < from) {
-      throw new Error('to must be greater than from');
+      throwBlockRangeError('to must be greater than from');
+    }
+    if (to && from && to - from > BLOCK_RANGE_SIZE) {
+      throwBlockRangeError(
+        `The block range is too large. The maximum range is ${BLOCK_RANGE_SIZE}`
+      );
     }
 
     return getActionsQuery(

src/services/events-service/events-service.ts

@@ -22,6 +22,8 @@ import {
   TracingState,
   extractTraceStateFromOptions,
 } from '../../tracing/tracer.js';
+import { BLOCK_RANGE_SIZE } from '../../server/server.js';
+import { throwBlockRangeError } from '../../errors/error.js';
 
 export { EventsService };
 
@@ -67,7 +69,12 @@ class EventsService implements IEventsService {
     tokenId ||= DEFAULT_TOKEN_ID;
     status ||= BlockStatusFilter.all;
     if (to && from && to < from) {
-      throw new Error('to must be greater than from');
+      throwBlockRangeError('to must be greater than from');
+    }
+    if (to && from && to - from > BLOCK_RANGE_SIZE) {
+      throwBlockRangeError(
+        `The block range is too large. The maximum range is ${BLOCK_RANGE_SIZE}`
+      );
     }
 
     return getEventsQuery(