06 docs (#1260)

docs/pages/0_6/_meta.ts

@@ -0,0 +1,10 @@
+export default {
+  docs: {
+    display: "children",
+    theme: {
+      breadcrumb: false,
+      sidebar: true,
+      toc: true,
+    },
+  },
+};

docs/pages/0_6/docs/_meta.ts

@@ -0,0 +1,62 @@
+export default {
+  "why-ponder": {
+    title: "Why Ponder",
+    display: "hidden",
+  },
+
+  "-- Get started": {
+    type: "separator",
+    title: "Get started",
+  },
+  "getting-started": { display: "children", title: "Get started" },
+  "migration-guide": "Migration guide",
+
+  "-- Config": {
+    type: "separator",
+    title: "Config",
+  },
+  "contracts-and-networks": "Contracts & networks",
+  "block-intervals": "Block intervals",
+
+  "-- Schema": {
+    type: "separator",
+    title: "Schema",
+  },
+  schema: "Design your schema",
+
+  "-- Indexing": {
+    type: "separator",
+    title: "Indexing",
+  },
+  indexing: { display: "children", title: "Indexing" },
+
+  "-- Query": {
+    type: "separator",
+    title: "Query",
+  },
+  query: { display: "children", title: "Query" },
+
+  "-- Production": {
+    type: "separator",
+    title: "Production",
+  },
+  production: { display: "children", title: "Production" },
+
+  "-- Utilities": {
+    type: "separator",
+    title: "Utilities",
+  },
+  utilities: { display: "children", title: "Utilities" },
+
+  "-- API reference": {
+    type: "separator",
+    title: "API reference",
+  },
+  "api-reference": { display: "children", title: "API reference" },
+
+  "-- Advanced": {
+    type: "separator",
+    title: "Advanced",
+  },
+  advanced: { display: "children", title: "Advanced" },
+};

docs/pages/0_6/docs/advanced/_meta.ts

@@ -0,0 +1,7 @@
+export default {
+  foundry: "Foundry",
+  logging: "Logging",
+  metrics: "Metrics",
+  status: "Status",
+  telemetry: "Telemetry"
+};

docs/pages/0_6/docs/advanced/foundry.mdx

@@ -0,0 +1,139 @@
+---
+title: "Integrate with Foundry"
+description: "A guide for using Ponder with the Foundry smart contract development toolchain."
+---
+
+import { Callout, Steps } from "nextra/components";
+
+<Callout type="warning">
+  This documentation is for versions `0.1 – 0.6`. You may want to view the
+  [latest version](/docs/getting-started/new-project).
+</Callout>
+
+# Foundry
+
+This guide describes how to integrate Ponder and Foundry during local development.
+
+Foundry projects follow various development workflows (test-driven, deploy to a fresh chain, deploy to a fork, etc). Rather than a one-size-fits-all integration, this page offers patterns that you can adapt to your workflow.
+
+## Configure the `anvil` network
+
+### Disable caching
+
+Ponder's RPC request cache works well for live networks where the chain is generally immutable, but causes issues when indexing a local chain that "resets".
+
+Use the `disableCache` option to **disable RPC request caching** for the Anvil network. With this option set to true, Ponder will clear the cache on start up and between hot reloads.
+
+```ts filename="ponder.config.ts" {9}
+import { createConfig } from "@ponder/core";
+import { http } from "viem";
+
+export default createConfig({
+  networks: {
+    anvil: {
+      chainId: 31337,
+      transport: http("http://127.0.0.1:8545"),
+      disableCache: true,
+    },
+  },
+  // ...
+});
+```
+
+### Chain ID
+
+We recommend using `31337` (the default Anvil chain ID) even when forking a live chain. This avoids common footguns when working with multiple networks.
+
+### Mining mode
+
+We recommend using [interval mining](https://book.getfoundry.sh/reference/anvil/#mining-modes) with a block time of ~2 seconds. This better simulates a live network.
+
+<Callout type="warning">
+  Known issue: When indexing Anvil with auto mining enabled in an app with
+  multiple networks, indexing progress will get "stuck" at the timestamp of the
+  latest Anvil block.{" "}
+</Callout>
+
+## Generate ABI files
+
+To enable end-to-end type safety, the contract ABIs generated by Foundry must be copied into TypeScript (`.ts`) source files.
+
+### Wagmi CLI
+
+The Wagmi CLI [Foundry plugin](https://wagmi.sh/cli/api/plugins/foundry) is an excellent tool to automate tedious ABI file management. For more information, visit the [Wagmi CLI documentation](https://wagmi.sh/cli/getting-started).
+
+Here is the Wagmi CLI config file used by the Foundry [example project](https://github.com/ponder-sh/ponder/tree/main/examples/with-foundry).
+
+```ts filename="wagmi.config.ts"
+import { defineConfig } from "@wagmi/cli";
+import { foundry } from "@wagmi/cli/plugins";
+
+export default defineConfig({
+  out: "abis/CounterAbi.ts",
+  plugins: [
+    foundry({
+      project: "foundry",
+      include: ["Counter.sol/**"],
+    }),
+  ],
+});
+```
+
+## Import broadcast files
+
+Foundry scripts write transaction inputs and receipts to JSON files in the `broadcast` directory. You can import these files directly into `ponder.config.ts` to automate address management and enable hot reloading.
+
+<Callout type="info">
+  Remember to enable
+  [broadcast](https://book.getfoundry.sh/tutorials/solidity-scripting?highlight=deploy#deploying-locally)
+  so that `forge script` submits transactions to Anvil.
+</Callout>
+
+### Automate address management
+
+To read the contract address and deployment block number from a broadcast file, import the file directly into `ponder.config.ts` and access properties from the JSON object.
+
+The `ponder.config.ts` file from the Foundry [example project](https://github.com/ponder-sh/ponder/tree/main/examples/with-foundry) demonstrates this pattern. Here, the first transaction in the broadcast file deployed the `Counter.sol` contract. The location of the contract address and start block within the broadcast file depends on the order and number of transactions in your deployment script.
+
+```ts filename="ponder.config.ts" {4, 6-7, 21-22}
+import { createConfig } from "@ponder/core";
+import { http, getAddress, hexToNumber } from "viem";
+import { counterABI } from "../abis/CounterAbi";
+import CounterDeploy from "../foundry/broadcast/Deploy.s.sol/31337/run-latest.json";
+
+const address = getAddress(CounterDeploy.transactions[0]!.contractAddress);
+const startBlock = hexToNumber(CounterDeploy.receipts[0]!.blockNumber);
+
+export default createConfig({
+  networks: {
+    anvil: {
+      chainId: 31337,
+      transport: http("http://127.0.0.1:8545"),
+      disableCache: true,
+    },
+  },
+  contracts: {
+    Counter: {
+      network: "anvil",
+      abi: counterABI,
+      address,
+      startBlock,
+    },
+  },
+});
+```
+
+### Enable hot reloading
+
+If you import a JSON broadcast file in `ponder.config.ts`, the dev server will reload each time that file changes. This is a simple way to ensure that Ponder reloads every time you run a Foundry deployment script.
+
+```ts filename="ponder.config.ts" {3-4}
+import { createConfig } from "@ponder/core";
+import { http } from "viem";
+import CounterDeploy from "../foundry/broadcast/Deploy.s.sol/31337/run-latest.json";
+// ^ The development server detects changes to this file and triggers a hot reload.
+
+export default createConfig({
+  // ...
+});
+```

docs/pages/0_6/docs/advanced/logging.mdx

@@ -0,0 +1,99 @@
+---
+title: "Logging"
+description: "An overview of how to configure the Ponder logger."
+---
+
+import { Callout } from "nextra/components";
+
+<Callout type="warning">
+  This documentation is for versions `0.1 – 0.6`. You may want to view the
+  [latest version](/docs/getting-started/new-project).
+</Callout>
+
+# Logging
+
+Ponder produces logs to help you understand and debug your application.
+
+![Dev server logs screenshot](/logs.gif)
+
+<div className="caption">Dev server terminal UI (v0.0.75).</div>
+
+## Log level
+
+There are two ways to configure the minimum log level. If specified, the environment variable takes precedence over the CLI flag.
+
+- Set the `PONDER_LOG_LEVEL` environment variable
+- Use the `--log-level <LEVEL>`, `-v` (debug) or `-vv` (trace) CLI option
+
+<div className="code-columns">
+
+{/* prettier-ignore */}
+```js filename=".env.local"
+PONDER_LOG_LEVEL=trace
+```
+
+{/* prettier-ignore */}
+```bash filename="bash"
+ponder dev --log-level warn
+# or, use the shortcut flag for debug
+ponder dev -v
+```
+
+</div>
+
+### Levels
+
+| Log level        | Example                                           |
+| :--------------- | :------------------------------------------------ |
+| `silent`         |                                                   |
+| `error`          | Unrecoverable RPC error, SQL constraint violation |
+| `warn`           | Reorg reconciliation, malformed config            |
+| `info` (default) | Indexing progress, real-time block processing     |
+| `debug`          | Internal service lifecycle events                 |
+| `trace`          | Query-level database logs                         |
+
+### User logs
+
+Logs produced by your code (e.g. `console.log` statements in `ponder.config.ts` or indexing functions) will always be written to the console. Note that Ponder _does_ catch **errors** thrown by your code and emits an `error` log including the original error message and stack trace.
+
+## Log format
+
+Use the `--log-format <FORMAT>` CLI option to set the log format.
+
+<Callout type="info">
+  The auto-updating terminal UI is always enabled during development (`ponder
+  dev`) regardless of the log level or format.
+</Callout>
+
+### Pretty (default)
+
+{/* prettier-ignore */}
+```bash filename="bash"
+ponder start --log-format pretty
+```
+
+```bash filename="bash"
+11:54:36 AM INFO  build      Using SQLite database at .ponder/sqlite (default)
+11:54:36 AM INFO  database   Created table 'Account' in 'public.db'
+11:54:36 AM INFO  server     Started listening on port 42069
+11:54:36 AM INFO  historical Started syncing 'optimism' logs for 'weth9' with 0.0% cached
+11:54:36 AM INFO  historical Started syncing 'base' logs for 'weth9' with 0.0% cached
+11:54:36 AM INFO  historical Started syncing 'polygon' logs for 'weth9' with 0.0% cached
+```
+
+### JSON
+
+```bash filename="bash"
+ponder start --log-format json
+```
+
+The JSON log format emits newline-delimited JSON objects with properties `level`, `time`, `service`, `msg`, and (optionally) `error`.
+
+```json filename="bash"
+{"level":30,"time":1717170664426,"service":"build","msg":"Using SQLite database at .ponder/sqlite (default)"}
+{"level":30,"time":1717170664454,"service":"database","msg":"Created table 'Account' in 'public.db'"}
+{"level":30,"time":1717170664458,"service":"server","msg":"Started listening on port 42069"}
+{"level":30,"time":1717170664625,"service":"historical","msg":"Started syncing 'base' logs for 'weth9' with 0.0% cached"}
+{"level":30,"time":1717170664628,"service":"historical","msg":"Started syncing 'optimism' logs for 'weth9' with 0.0% cached"}
+{"level":30,"time":1717170664683,"service":"historical","msg":"Started syncing 'polygon' logs for 'weth9' with 0.0% cached"}
+```

docs/pages/0_6/docs/advanced/metrics.mdx

@@ -0,0 +1,53 @@
+---
+title: "Metrics"
+description: "An overview of the metrics that Ponder exposes."
+---
+
+import { Callout } from "nextra/components";
+
+<Callout type="warning">
+  This documentation is for versions `0.1 – 0.6`. You may want to view the
+  [latest version](/docs/getting-started/new-project).
+</Callout>
+
+# Metrics 🚧
+
+This page is under construction.
+
+<Callout type="warning">
+  Metrics are not part of the public API, so these are subject to change without
+  notice. Do not rely on these metrics for anything important (yet).
+</Callout>
+
+Ponder apps publish Prometheus metrics at the `/metrics` path.
+
+| name                                   | description                                                           | type      |
+| :------------------------------------- | :-------------------------------------------------------------------- | --------- |
+| ponder_indexing_total_seconds          | Total number of seconds required for indexing                         | gauge     |
+| ponder_indexing_completed_seconds      | Number of seconds that have been completed                            | gauge     |
+| ponder_indexing_completed_events       | Number of events that have been processed                             | gauge     |
+| ponder_indexing_completed_timestamp    | Timestamp through which all events have been completed                | gauge     |
+| ponder_indexing_has_error              | Boolean (0 or 1) indicating if there is an indexing error             | gauge     |
+| ponder_indexing_function_duration      | Duration of indexing function execution                               | histogram |
+| ponder_indexing_function_error_total   | Total number of errors encountered during indexing function execution | counter   |
+| ponder_historical_start_timestamp      | Unix timestamp (ms) when the historical sync service started          | gauge     |
+| ponder_historical_total_blocks         | Number of blocks required for the historical sync                     | gauge     |
+| ponder_historical_cached_blocks        | Number of blocks that were found in the cache for the historical sync | gauge     |
+| ponder_historical_completed_blocks     | Number of blocks that have been processed for the historical sync     | gauge     |
+| ponder_realtime_is_connected           | Boolean (0 or 1) indicating if the realtime sync service is connected | gauge     |
+| ponder_realtime_latest_block_number    | Block number of the latest synced block                               | gauge     |
+| ponder_realtime_latest_block_timestamp | Block timestamp of the latest synced block                            | gauge     |
+| ponder_realtime_reorg_total            | Count of how many re-orgs have occurred                               | counter   |
+| ponder_database_method_duration        | Duration of database operations                                       | histogram |
+| ponder_database_method_error_total     | Total number of errors encountered during database operations         | counter   |
+| ponder_http_server_port                | Port that the server is listening on                                  | gauge     |
+| ponder_http_server_active_requests     | Number of active HTTP server requests                                 | gauge     |
+| ponder_http_server_request_duration_ms | Duration of HTTP responses served by the server                       | histogram |
+| ponder_http_server_request_size_bytes  | Size of HTTP requests received by the server                          | histogram |
+| ponder_http_server_response_size_bytes | Size of HTTP responses served by the server                           | histogram |
+| ponder_rpc_request_duration            | Duration of RPC requests                                              | histogram |
+| ponder_rpc_request_lag                 | Time RPC requests spend waiting in the request queue                  | histogram |
+| ponder_postgres_pool_connections       | Gauge of current connections for PostgreSQL pools                     | gauge     |
+| ponder_postgres_query_queue_size       | Current size of the query queue for PostgreSQL                        | gauge     |
+| ponder_postgres_query_total            | Total number of queries processed by PostgreSQL                       | counter   |
+| ponder_sqlite_query_total              | Total number of queries processed by SQLite                           | counter   |