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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Mina Foundation
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,28 +1,25 @@
-# Archive Node Events GraphQL Server
+# Mina Archive Node GraphQL API
 
 [![Unit Tests](https://github.com/o1-labs/Archive-Node-API/actions/workflows/unit-tests.yaml/badge.svg)](https://github.com/o1-labs/Archive-Node-API/actions/workflows/unit-tests.yaml)
 [![codecov](https://codecov.io/gh/o1-labs/Archive-Node-API/branch/main/graph/badge.svg)](https://codecov.io/gh/o1-labs/Archive-Node-API)
+[![npm](https://img.shields.io/npm/v/@o1-labs/mina-archive-node-graphql.svg)](https://www.npmjs.com/package/@o1-labs/mina-archive-node-graphql)
+[![ghcr.io](https://img.shields.io/badge/ghcr.io-archive--node--api-2496ED?logo=docker&logoColor=white)](https://github.com/o1-labs/Archive-Node-API/pkgs/container/archive-node-api)
 
-This GraphQL server is built to expose information from [Mina's Archive Node](https://docs.minaprotocol.com/node-operators/archive-node).
+**Client SDKs** —
+[![TypeScript](https://img.shields.io/npm/v/%40o1-labs%2Fmina-archive-sdk?label=TypeScript&logo=npm)](https://www.npmjs.com/package/@o1-labs/mina-archive-sdk)
+[![Rust](https://img.shields.io/crates/v/mina-archive-sdk.svg?label=Rust&logo=rust)](https://crates.io/crates/mina-archive-sdk)
+[![Go](https://img.shields.io/github/v/tag/o1-labs/mina-archive-sdk-go?label=Go&sort=semver&logo=go)](https://pkg.go.dev/github.com/o1-labs/mina-archive-sdk-go)
 
-## Description
-
-The server aims to expose zkApp related information to be used by developers and o1js. Users can query for events and actions related to their zkApp. In addition, users can filter for specific events and actions by public key, tokenId, to/from block ranges, and chain status.
-
-An example query for events and actions looks like this:
+A GraphQL server that exposes [Mina archive-node](https://docs.minaprotocol.com/node-operators/archive-node) data — blocks, events, actions, transactions — for o1js / zkApp developers. It does **not** run an archive node itself; it queries an existing archive-node Postgres database.
 
 ```graphql
-query getEvents {
+query {
   events(input: { address: "B62..." }) {
     blockInfo {
+      height
       stateHash
       timestamp
-      ledgerHash
-      height
-      parentHash
       chainStatus
-      distanceFromMaxBlockHeight
-      globalSlotSinceGenesis
     }
     eventData {
       data
@@ -34,288 +31,115 @@ query getEvents {
     }
   }
 }
-
-query getActions {
-  actions(input: { address: "B62..." }) {
-    blockInfo {
-      stateHash
-      timestamp
-      ledgerHash
-      height
-      parentHash
-      chainStatus
-      distanceFromMaxBlockHeight
-      globalSlotSinceGenesis
-    }
-    actionState {
-      actionStateOne
-      actionStateTwo
-      actionStateThree
-      actionStateFour
-      actionStateFive
-    }
-    actionData {
-      data
-      transactionInfo {
-        status
-        hash
-        memo
-      }
-    }
-  }
-}
-```
-
-To see the data exposed, see the [GraphQL schema](./schema.graphql).
-
-The server lets operators connect to an existing Archive Node Postgres database and provides application monitoring with [Jaeger](https://github.com/jaegertracing/jaeger).
-
-Finally, the server provides a set of environment variables to configure runtime options such as database connections, CORS origin, logging behaviour, etc.
-
-## Connecting to a Postgres database
-
-The server will use the `PG_CONN` environment variable to establish a connection to a running Archive Node. Note that `PG_CONN` is a connection string, so the expected format looks like `'postgres://postgres:password@localhost:5432/archive'`
-
-The server additionally supports multi-host connections for high availability if you are running multiple Archive Nodes. For example, numerous connection strings can be passed to `PG_CONN` as `'postgres://localhost:5432,localhost:5433'`. This works the same as the native `psql` command. Read more at [multiple host URIs](https://www.postgresql.org/docs/13/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS).
-
-Connections will be attempted in order of the specified hosts/ports. On a successful connection, all retries will be reset. This ensures that hosts can come up and down seamlessly.
-
-## Connecting to a Jaeger server for logging
-
-To run an instance of Jaeger locally, see the [init_jaeger script](./scripts/init_jaeger.sh). By running the script, a local instance of Jaeger will be instantiated with Docker with default environment variables. If you run it as is, you can access the Jaeger dashboard by visiting `http://localhost:16686`.
-
-To enable logging to Jaeger, set the following environment variables:
-
-```sh
-ENABLE_JAEGER="true"
-JAEGER_SERVICE_NAME="archive-api"
-JAEGER_ENDPOINT='http://localhost:14268/api/traces'
-```
-
-`ENABLE_JAEGER`: Tells the server to allow Jaeger logging. If Jaeger logging is not enabled, all logs will be printed to stdout.
-
-`JAEGER_ENDPOINT`: The specified URL for the running Jaeger service.
-
-`JAEGER_SERVICE_NAME`: Specifies the service name to be used by Jaeger. The service name will be what identifies the service in the Jaeger logs.
-
-Also, note that Jaeger supports distributed logging. This means that if you're running multiple instances of this server, you can specify the same Jaeger endpoint. All your logs will be consolidated in one place for simplified logging across all your server instances.
-
-## Environment Variables
-
-This section aims to describe all the environment variables exposed to configure runtime behaviour:
-
-- `APP_COMMAND`: The command to run the server. A sensible default is `npm run start`.
-
-- `PG_CONN`: The connection string used to connect to either a single or multiple Archive Nodes.
-
-- `ENABLE_INTROSPECTION`: Enable or disable [GraphQL introspection](https://graphql.org/learn/introspection/). GraphQL introspection is a feature of GraphQL that allows clients to inspect the capabilities of a GraphQL server. It enables clients to discover the types, fields, and other metadata available on the server and query it using this information.
-
-- `ENABLE_GRAPHIQL`: GraphiQL is an in-browser tool for working with GraphQL APIs. It provides a user-friendly interface for constructing and executing GraphQL queries, making it easier for developers to test and debug their GraphQL applications. GraphiQL is an excellent tool for development and testing, but it should be considered disabled in a production environment for security-related reasons.
-
-- `ENABLE_LOGGING`: Enables logging to either Jaeger or to stdout. If `ENABLE_JAEGER` is not defined, but `ENABLE_LOGGING` is, all logs will be directed to stdout. If `ENABLE_JAEGER` is specified, all logs will be directed to the Jaeger server. Logging is done using [OpenTelemetry](https://opentelemetry.io/docs/reference/specification/overview/)
-
-- `ENABLE_JAEGER`: Enable or disable logging to a Jaeger server. If not enabled, all logging is done through stdout.
-
-- `JAEGER_ENDPOINT`: A URL that specifies a running Jaeger instance to send logs to. If the `./scripts/init_jaeger.sh` was run to instantiate a local instance of Jaeger, the endpoint will be `http://localhost:14268/api/traces`.
-
-- `JAEGER_SERVICE_NAME`: The name used to specify your service within Jaeger. This name will be used to identify your specific running server.
-
-- `PORT`: The port to be used when running the server. By default, it will use port `8080`.
-
-- `LOG_LEVEL`: Specifies the level of logs to emit from GraphQL Yoga. [See documentation here](https://the-guild.dev/graphql/yoga-server/docs/features/logging-and-debugging) for more details.
-
-- `CORS_ORIGIN`: Specify the CORS origin if you wish to run this server behind a proxy. By default, the server will return `Access-Control-Allow-Origin: *`.
-
-To see an example of sensible defaults, see the [env.example](./.env.example) configuration file.
-
-## Installing from npm
-
-This package is published to npm and is available for public access
-
-```sh
-npm install mina-archive-node-graphql
-```
-
-## Installing from artifact registry
-
-This package is published to a Google Cloud Artifact Registry and is available for public access.
-
-**Configure npm to use the registry:**
-
-```sh
-npm config set registry https://europe-southwest1-npm.pkg.dev/o1labs-192920/euro-npm/
-```
-
-**Install the package:**
-
-```sh
-# Install the latest stable version
-npm install archive-node-graphql
-
-# Or install a specific version
-npm install archive-node-graphql@1.2.3
-
-# Or install the latest dev version
-npm install archive-node-graphql@dev
-```
-
-## Creating a Release
-
-To create a new release, follow these steps:
-
-1. **Update version in package.json**: `npm version <major|minor|patch>`
-2. **Commit the version change**: `git commit -am "Release v1.2.3"`
-3. **Create and push a tag**: `git tag v1.2.3 && git push origin v1.2.3`
-
-The CI/CD workflow will automatically:
-
-- Build and publish npm package to GCP registry with version from package.json
-- Build and push Docker image to both GCP Artifact Registry and GitHub Container Registry
-- Create semantic version tags (e.g., `1.2.3`, `1.2`, `1`, `latest`)
-
-**Published artifacts:**
-
-- npm: `https://europe-southwest1-npm.pkg.dev/o1labs-192920/euro-npm/`
-- Docker (GCP): `europe-west3-docker.pkg.dev/o1labs-192920/euro-docker-repo/archive-node-api`
-- Docker (GitHub): `ghcr.io/o1-labs/archive-node-api`
-
-## Starting the server
-
-To start the server, run
-
-```sh
-npm run build
-npm run start
 ```
 
-or in development mode, run
+The full surface lives in [`schema.graphql`](./schema.graphql).
 
-```sh
-npm run dev
-```
-
-This will start the server and allow you to interact with the GraphQL API specified with the port defined in your `.env` file or port `8080` by deafult. e.g. `http://localhost:3000`.
-
-In production, we recommend running this with a process control system [pm2](https://pm2.keymetrics.io/) or [Supervisor](http://supervisord.org/). In addition to using these tools, you could utilize the provided [Dockerfile](./Dockerfile) to build and run a container.
+## Quick start
 
-## Running tests
+Pick the path that matches your situation. Each one is fully covered in [`docs/getting-started.md`](./docs/getting-started.md).
 
-To run the tests, you will need a running instance of [Lightnet](https://docs.minaprotocol.com/zkapps/testing-zkapps-lightnet). Lightnet will start a running Postgres instance with a local Mina network and will populate the database with zkApp related data. To run the tests, you will have to run a zkApp script to emit events and actions to the database. To do this, ensure you have Lightnet [running on your local machine](https://docs.minaprotocol.com/zkapps/testing-zkapps-lightnet#start-a-single-node-network) and then run the following commands:
+| Path                                                                                                         | When to use it                                                         |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| **[npm](./docs/getting-started.md#path-a--npm-bring-your-own-database)**                                     | You already have an archive-node Postgres reachable. Lightest weight.  |
+| **[Prebuilt Docker image](./docs/getting-started.md#path-b--prebuilt-docker-image-bring-your-own-database)** | You have a Postgres reachable but don't want a Node toolchain locally. |
+| **[Docker Compose + DB snapshot](./docs/getting-started.md#path-c--docker-compose-with-database-snapshot)**  | No archive-node DB available — Compose stands one up from a snapshot.  |
 
 ```sh
-node --loader ts-node/esm benchmark/setup.ts
-```
-
-This will run a script that will deploy a zkApp and emit events and actions to the database. Once the script is finished, you can run the tests with the following command:
+# the 30-second taste (Path A)
+npm install -g @o1-labs/mina-archive-node-graphql
+PG_CONN='postgres://postgres:postgres@localhost:5432/archive' \
+  ENABLE_GRAPHIQL=true \
+  mina-archive-node-graphql
+# → http://localhost:8080
+```
+
+## Configuration
+
+`PG_CONN` is the only required environment variable. The most common knobs:
+
+| Variable               | Default      | Description                                        |
+| ---------------------- | ------------ | -------------------------------------------------- |
+| `PG_CONN`              | _(required)_ | Postgres connection string for the archive-node DB |
+| `PORT`                 | `8080`       | Port the GraphQL server listens on                 |
+| `ENABLE_GRAPHIQL`      | `false`      | Serve the GraphiQL playground at `/`               |
+| `ENABLE_INTROSPECTION` | `false`      | Allow GraphQL schema introspection                 |
+| `ENABLE_LOGGING`       | `false`      | Emit OpenTelemetry traces                          |
+| `ENABLE_METRICS`       | `false`      | Expose Prometheus metrics at `/metrics`            |
+| `ENABLED_QUERIES`      | _(all)_      | Comma-separated subset of root query fields        |
+| `BLOCK_RANGE_SIZE`     | `10000`      | Max block range a single query may span            |
+| `ENABLE_ZKAPP_COMMANDS_QUERY` | `false` | Expose the `zkappCommands` range query             |
+| `ZKAPP_COMMAND_RANGE_SIZE` | `1000`       | Max block range for `zkappCommands`                |
+| `ZKAPP_COMMAND_ACCOUNT_UPDATE_LIMIT` | `5000`       | Max expanded account updates for one `zkappCommands` query |
+| `ENABLE_JAEGER`        | `false`      | Emit traces to a Jaeger collector                  |
+| `JAEGER_ENDPOINT`      | —            | e.g. `http://localhost:14268/api/traces`           |
+
+Full reference, including HA / multi-host `PG_CONN` syntax, in [`docs/getting-started.md#configuration`](./docs/getting-started.md#configuration).
+
+## Development
+
+| Command             | What it does                                                                                               |
+| ------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `npm run dev`       | Run the server with hot reload (reads `.env`)                                                              |
+| `npm run build`     | Compile TypeScript to `build/`                                                                             |
+| `npm run start`     | Run the compiled server                                                                                    |
+| `npm run lint`      | ESLint over `*.ts`                                                                                         |
+| `npm run test:unit` | Unit tests (no DB required)                                                                                |
+| `npm run test`      | Full test suite — needs a running [Lightnet](https://docs.minaprotocol.com/zkapps/testing-zkapps-lightnet) |
+| `npm run codegen`   | Regenerate `src/resolvers-types.ts` from `schema.graphql`                                                  |
+| `npm run benchmark` | Artillery load test against a running server                                                               |
+
+Running the full suite requires Lightnet plus a populated DB:
 
 ```sh
+node --loader ts-node/esm benchmark/setup.ts   # deploys a zkApp and emits events/actions
 npm run test
 ```
 
-## Benchmarking
+## Releasing
 
-To run a benchmark on the Typescript GraphQL server, you will need to have a running Lightnet instance to connect to. See the [Running tests](#running-tests) section if you still need to run the setup.
+Tagged commits trigger CI to publish:
 
-You will also need to run the server to run the benchmarks. For example, to run the server in development mode, run the following command:
+- npm (public): [`@o1-labs/mina-archive-node-graphql`](https://www.npmjs.com/package/@o1-labs/mina-archive-node-graphql)
+- Docker (GHCR): `ghcr.io/o1-labs/archive-node-api`
 
-```sh
-npm run dev
-```
-
-Once the server is up and running, you can run the benchmarking script by using the following command:
-
-```sh
-npm run benchmark
-```
-
-This script will run the config defined in `benchmarking/graphql.yaml` and output a report in the benchmarking folder. The report will contain summarized metrics of the performance testing run against the server.
-
-It is important to note that the benchmarking script requires the server to run to collect performance metrics. The report generated will provide valuable insights into the server's performance and help identify any potential bottlenecks or areas for improvement. Please note that running the benchmark may consume significant resources and should be done cautiously. Ensure that the server runs in a stable environment before running the benchmarking script.
+A release PR bumps `package.json`, then a maintainer tags its merge commit. Do
+not run `npm version` on `main`: `package.json` already carries the version
+being released. Steps and the npm trusted-publishing caveat are in the
+[versioning & schema stability policy](./docs/versioning.md#releasing).
 
-## Hardware Requirements
+CI builds, publishes the npm package with provenance once npm trusted
+publishing is configured, and pushes Docker tags `1.2.3`, `1.2`, `1`,
+`latest`.
 
-Running the Archive Node API requires a hardware configuration that can handle the load placed on the server by user requests, with the primary load being on the database. This API is written to be resource efficient; the main bottleneck is expected to be on the database performance, not the Archive Node API process.
+From 1.0.0 the GraphQL schema, HTTP endpoints, and configuration are a versioned public contract — see the [versioning & schema stability policy](./docs/versioning.md) for what counts as a breaking change and how deprecations work.
 
-### Increased Load on the Database
+## Compatibility
 
-To mitigate the load on the database, it is recommended to use the multi-host connection to utilize multiple Archive Node databases. By supplying additional read-only databases for the API to connect to, queries will be spread evenly across all databases, which will help with response time. Additionally, the use of more powerful hardware on existing Archive Node databases should be considered.
+Clients can ask the server which GraphQL contract it serves with the
+`schemaVersion` query. For the schema version rules and the Mina releases this
+server is known to work with, see
+[docs/versioning.md](docs/versioning.md#schema-version).
 
-To get a real sense of what hardware requirements are needed, you can utilize the [benchmarking suite](#benchmarking) to see how many requests can be handled.
+## Hardware requirements
 
-For example, a benchmark report is shown below and was run with an Archive Node API and Postgres database container running on the same machine with a 12-core processor & 32GB of RAM.
+The bottleneck is the Postgres database, not this server. A recent benchmark on a 12-core / 32 GB box (API + Postgres co-located) sustained ~800 req/s with p99 latency of 39 ms. Use `npm run benchmark` to size your own deployment.
 
-```
---------------------------------------
-Metrics for period to: 19:05:30(-0800) (width: 9.999s)
---------------------------------------
-
-http.codes.200: ................................................................ 7908
-http.request_rate: ............................................................. 794/sec
-http.requests: ................................................................. 7915
-http.response_time:
-  min: ......................................................................... 1
-  max: ......................................................................... 54
-  median: ...................................................................... 15
-  p95: ......................................................................... 30.9
-  p99: ......................................................................... 39.3
-http.responses: ................................................................ 7908
-vusers.completed: .............................................................. 7907
-vusers.created: ................................................................ 7916
-vusers.created_by_name.Get Actions: ............................................ 3885
-vusers.created_by_name.Get Events: ............................................. 4031
-vusers.failed: ................................................................. 0
-vusers.session_length:
-  min: ......................................................................... 2.4
-  max: ......................................................................... 55.5
-  median: ...................................................................... 16
-  p95: ......................................................................... 32.1
-  p99: ......................................................................... 40
-```
+Listing multiple hosts in `PG_CONN` (`postgres://host1:5432,host2:5432/archive`) buys **redundancy, not read throughput**: the client connects to the first host and only moves to the next one when that connection fails, so it fails over rather than spreading queries across replicas. To actually scale reads, load-balance in front of Postgres (PgBouncer, HAProxy, or a managed reader endpoint) and point `PG_CONN` at that.
 
-## Setting Up Local Development Environment Using zkApp-CLI Lightnet
+For SLOs, capacity guidance, what to monitor, and incident response, see the [operations runbook](./docs/runbook.md).
 
-To set up a local development environment, you can use the [zkApp-CLI Lightnet](https://docs.minaprotocol.com/zkapps/testing-zkapps-lightnet). This tool allows you to run a local Mina network with zkApps enabled. The zkApp-CLI Lightnet will also start a running Postgres instance with a local Mina network and will populate the database with zkApp related data. Once you have the zkApp-CLI Lightnet running, you can run the server and interact with the GraphQL API.
+## Deployment
 
-To see how to set up the zkApp-CLI Lightnet, see the [zkApp-CLI Lightnet documentation](https://docs.minaprotocol.com/zkapps/testing-zkapps-lightnet#start-a-local-network).
+Reference Kubernetes and production Docker Compose manifests — with liveness/readiness probes, resource limits, autoscaling, and a hardened pod security context — live in [`deploy/`](./deploy/). Read [`docs/security.md`](./docs/security.md) for the deployment contract (TLS gateway, read-only DB role, private Postgres).
 
-If you wish to populate the database with zkApp related data, you can run the following commands:
+The API is a public, read-only service and is meant to run **behind a TLS-terminating gateway**, against a **read-only** Postgres role. Before exposing it publicly, read [`docs/security.md`](./docs/security.md) — it covers the security model, network architecture, the built-in abuse protections, and a deployment checklist.
 
-```sh
-node --loader ts-node/esm benchmark/setup.ts
-```
+## Contributing
 
-This will run a script that will deploy a zkApp and emit events and actions to the database. Once the script is finished, you can run the server with the following command:
-
-```sh
-npm run dev
-```
+- AI coding agents: read [`AGENTS.md`](./AGENTS.md) first.
+- Issues and PRs: [github.com/o1-labs/Archive-Node-API](https://github.com/o1-labs/Archive-Node-API)
 
-To ensure you have the correct environment variables set up, you can see a copy of the `.env.example.lightnet` file.
-
-Generally, it is recommended that you use Lightnet as your local development environment, as it will provide you with a running Mina network and a Postgres instance with zkApp related data.
-
-## Setting Up Local Development Environment Using Docker Compose
-
-The provided `docker-compose.yml` file simplifies the process of setting up a local development environment. This file orchestrates the creation of a Docker network comprising of Mina daemon, Archive Node, GraphQL server, and Jaeger. Follow the steps below to get everything up and running:
-
-**Step 1: Libp2p Keypair Generation**
-
-You will need a libp2p keypair for the setup. If you don't already have one, you can easily generate a keypair specifically for local development (note: this should not be used in production). Use the script provided in the repository:
-
-```bash
-./scripts/generate_libp2p.sh
-```
-
-**Step 2: Update Environment Variables**
-
-Once you have generated the keypair, make sure to update your `.env` file with the passwords that were used during the keypair generation process.
-
-**Step 3: Launch the Docker Network**
-
-With the prerequisites in place, start the Docker network by running the following command in your terminal:
-
-```bash
-docker compose up
-```
+## License
 
-This command pulls the necessary Docker images and launches them, setting up a local environment ideal for server development. This setup offers a way to connec to a live running Mina network, specified by it's seed peers and Mina daemon build. Use this setup to test the server's functionality and performance against a live running network.
+[Apache-2.0](./LICENSE) — the same license as [`MinaProtocol/mina`](https://github.com/MinaProtocol/mina), [`o1js`](https://github.com/o1-labs/o1js) and the archive SDKs.

package/build/src/blockchain/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/blockchain/utils.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,eAAe,CAAC,GAA2B;IACzD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1B,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,UAAU,EAAE,GAAG,CAAC,WAAW;QAC3B,UAAU,EAAE,GAAG,CAAC,WAAW;QAC3B,WAAW,EAAE,GAAG,CAAC,YAAY;QAC7B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,uBAAuB,EAAE,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC;QAChE,sBAAsB,EAAE,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC;QAC7D,0BAA0B,EAAE,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC;QACtE,aAAa,EAAE,GAAG,CAAC,eAAe;KACnC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,GAA2B;IAE3B,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,iBAAiB,EAAE,GAAG,CAAC,kBAAkB;QACzC,cAAc,EAAE,GAAG,CAAC,eAAe;QACnC,qBAAqB,EAAE,GAAG,CAAC,yBAAyB;KACrD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,eAAuB,EACvB,IAAc,EACd,eAAgC;IAEhC,OAAO;QACL,eAAe;QACf,IAAI;QACJ,eAAe;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,eAAuB,EACvB,IAAc,EACd,eAAgC;IAEhC,OAAO;QACL,eAAe;QACf,IAAI;QACJ,eAAe;KAChB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/blockchain/utils.ts"],"names":[],"mappings":"AA2BA,MAAM,UAAU,eAAe,CAAC,GAAiB;IAC/C,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1B,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,UAAU,EAAE,GAAG,CAAC,WAAW;QAC3B,UAAU,EAAE,GAAG,CAAC,WAAW;QAC3B,WAAW,EAAE,GAAG,CAAC,YAAY;QAC7B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,uBAAuB,EAAE,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC;QAChE,sBAAsB,EAAE,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC;QAC7D,0BAA0B,EAAE,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC;QACtE,aAAa,EAAE,GAAG,CAAC,eAAe;KACnC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,GAAuB;IAEvB,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,iBAAiB,EAAE,GAAG,CAAC,kBAAkB;QACzC,cAAc,EAAE,GAAG,CAAC,eAAe;QACnC,qBAAqB,EAAE,GAAG,CAAC,yBAAyB;KACrD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,eAAuB,EACvB,IAAc,EACd,eAAgC;IAEhC,OAAO;QACL,eAAe;QACf,IAAI;QACJ,eAAe;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,eAAuB,EACvB,IAAc,EACd,eAAgC;IAEhC,OAAO;QACL,eAAe;QACf,IAAI;QACJ,eAAe;KAChB,CAAC;AACJ,CAAC"}