Ogmios

https://ogmios.dev
Admin
Ogmios is a lightweight bridge interface for cardano-node, offering a WebSockets API that enables...
Tokens:285,525
Snippets:1,246
Trust Score:6.9
Update:9 months ago
Show doc for...
Tokens:
Raw
### Build Documentation with Hugo

Source: https://ogmios.dev/getting-started/building

Instructions for building the project's documentation using Hugo. Requires an extended version of Hugo (>= 0.96.0). The command `hugo serve` can be used for a local development setup.

```shell
hugo

# or, alternatively for a development setup on http://localhost:1313

hugo serve
```

--------------------------------

### Install Ogmios using Homebrew

Source: https://ogmios.dev/getting-started/building

Installs Ogmios by adding the CardanoSolutions/formulas tap and then installing the ogmios package. This is the simplest method for users with Homebrew.

```bash
brew tap CardanoSolutions/formulas
brew install ogmios
```

--------------------------------

### Compile and Install blst crypto library

Source: https://ogmios.dev/getting-started/building

Builds and installs the blst (BLS12-381 crypto) library. This involves cloning the repository, checking out a specific version, building the library, and then copying the necessary files and configuration to system directories.

```bash
git clone https://github.com/supranational/blst
cd blst
git checkout v0.3.10
./build.sh
cat > libblst.pc << EOF
prefix=/usr/local
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include

Name: libblst
Description: Multilingual BLS12-381 signature library
URL: https://github.com/supranational/blst
Version: 0.3.10
Cflags: -I${includedir}
Libs: -L${libdir} -lblst
EOF
sudo cp libblst.pc /usr/local/lib/pkgconfig/
sudo cp bindings/blst_aux.h bindings/blst.h bindings/blst.hpp  /usr/local/include/
sudo cp libblst.a /usr/local/lib
sudo chmod u=rw,go=r /usr/local/{lib/{libblst.a,pkgconfig/libblst.pc},include/{blst.{h,hpp},blst_aux.h}}
```

--------------------------------

### Run Cardano Ogmios Tests

Source: https://ogmios.dev/typescript/api

Starts the testnet environment for running tests. Requires a separate terminal to be running the testnet.

To run tests:
1. Start the testnet in one terminal.
2. Execute the test command in another terminal.

Dependencies: Requires yarn to be installed.

```bash
yarn testnet:up
```

```bash
yarn test
```

--------------------------------

### Start Cardano Ogmios REPL

Source: https://ogmios.dev/typescript/api

Starts the Read-Eval-Print Loop (REPL) for interacting with the Ogmios server. It can be started on the default port for mainnet or a specified port for testnet.

```bash
yarn repl:start
```

```bash
yarn repl:start --port 1337
```

--------------------------------

### Query Network Start Time using Ogmios Schema

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_schema.QueryNetworkStartTime

This snippet demonstrates how to query the network start time using the Ogmios schema. It requires specifying the method and other properties like jsonrpc and id. The output will be the network's start time.

```javascript
const query = {
  "id": 1,
  "jsonrpc": "2.0",
  "method": "queryNetwork/startTime"
};

// Assuming you have a running Ogmios instance and a way to send requests
// sendRequest(query).then(response => {
//   console.log('Network start time:', response.result);
// });
```

--------------------------------

### Install Ogmios Server Executable using Cabal

Source: https://ogmios.dev/getting-started/building

Installs the compiled Ogmios server executable to a location where it can be run directly. The `--install-method=copy` and `--overwrite-policy=always` flags ensure the executable is placed in a user-accessible path and updated if already present.

```bash
cabal install ogmios:exe:ogmios --install-method=copy --overwrite-policy=always
ogmios --help
```

--------------------------------

### Compile and Install secp256k1 library

Source: https://ogmios.dev/getting-started/building

Compiles and installs a custom revision of bitcoin-core's secp256k1 library with Schnorr signature support. Requires autoconf and libtool. Includes macOS specific command for library path.

```bash
git clone https://github.com/bitcoin-core/secp256k1.git
cd secp256k1
git reset --hard ac83be33d0956faf6b7f61a60ab524ef7d6a473a
./autogen.sh
./configure --prefix=/usr/local/lib --libdir=/usr/local/lib --enable-module-schnorrsig --enable-experimental
make
make check
sudo make install

# macOS specific command if needed:
install_name_tool -id /usr/local/lib/libsecp256k1.0.dylib /usr/local/lib/libsecp256k1.0.dylib
```

--------------------------------

### Start Cardano Node and Ogmios Server

Source: https://ogmios.dev/typescript/api

Starts the Cardano node and Ogmios server for either the mainnet or testnet environment. This command is used to set up the necessary backend for interacting with the Cardano blockchain.

```bash
yarn mainnet:up
```

```bash
yarn testnet:up
```

--------------------------------

### Query Ledger State Era Start

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_client.Schema.QueryLedgerStateEraStart

Retrieves the start information for the current era in the Cardano ledger.

```APIDOC
## POST /queryLedgerState/eraStart

### Description
This endpoint queries the Ogmios node to retrieve the start block and timestamp of the current ledger era.

### Method
POST

### Endpoint
/queryLedgerState/eraStart

### Parameters

#### Query Parameters
None

#### Request Body
```json
{
  "id": unknown,
  "jsonrpc": "2.0",
  "method": "queryLedgerState/eraStart"
}
```

### Request Example
```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "queryLedgerState/eraStart"
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the era start details.
  - **block** (integer) - The block number at the start of the era.
  - **timestamp** (string) - The ISO 8601 timestamp of the era start.

#### Response Example
```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "block": 123456,
    "timestamp": "2023-01-01T00:00:00Z"
  }
}
```
```

--------------------------------

### Clone and Build TypeScript Client

Source: https://ogmios.dev/getting-started/building

This section details how to clone the Ogmios TypeScript client repository from GitHub and then use Yarn to install dependencies and build the project. Ensure you have Git and Yarn installed.

```shell
$ git clone --depth 1 --recursive --shallow-submodules git@github.com:cardanosolutions/ogmios.git
$ cd ogmios/clients/TypeScript
$ yarn && yarn build
```

--------------------------------

### Query Network Start Time API

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_client.Schema.QueryNetworkStartTime

Retrieves the start time of the Cardano network.

```APIDOC
## POST /queryNetwork/startTime

### Description
This endpoint retrieves the start time of the Cardano network.

### Method
POST

### Endpoint
/queryNetwork/startTime

### Parameters
#### Request Body
- **id** (unknown) - Optional - An identifier for the request.
- **jsonrpc** (string) - Required - The JSON-RPC version, must be "2.0".
- **method** (string) - Required - The method to call, must be "queryNetwork/startTime".

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "queryNetwork/startTime",
  "id": 1
}
```

### Response
#### Success Response (200)
- **result** (string) - The network start time in ISO 8601 format.
- **id** (unknown) - The identifier for the response, matching the request id.
- **jsonrpc** (string) - The JSON-RPC version, "2.0".

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": "2017-06-20T07:10:00Z",
  "id": 1
}
```
```

--------------------------------

### Run Ogmios Server using Cabal

Source: https://ogmios.dev/getting-started/building

Executes the compiled Ogmios server directly using Cabal's run command. This is useful for testing or running the server without a separate installation step. The '-- --help' flag is used here to demonstrate how to pass arguments to the executable.

```bash
cabal run ogmios:exe:ogmios -- --help
```

--------------------------------

### Run Unit Tests with Cabal

Source: https://ogmios.dev/getting-started/building

This command executes all unit tests for the Ogmios project using the Cabal build tool. Ensure Cabal is installed and configured correctly.

```shell
$ cabal test all
```

--------------------------------

### Get Cardano Network Start Time

Source: https://ogmios.dev/typescript/api/modules/_cardano_ogmios_client.LedgerStateQuery

Retrieves the start date of the Cardano network. This function requires an InteractionContext.

```typescript
import { InteractionContext } from "@cardano-ogmios/client";

async function getNetworkStartTime(context: InteractionContext): Promise<Date> {
  // Assume context is already established
  const networkStartTime = await context.ledgerStateQuery.networkStartTime();
  return networkStartTime;
}
```

--------------------------------

### Query Network Start Time

Source: https://ogmios.dev/mini-protocols/local-state-query

Retrieves the current start time of the network. This is a simple GET request with no parameters.

```json
{
  "jsonrpc": "2.0",
  "method": "queryNetwork/startTime"
}
```

--------------------------------

### Start Ogmios and Cardano Node with Docker Compose

Source: https://ogmios.dev/getting-started/docker

This command starts the Ogmios server and a Cardano node connected to the mainnet using Docker Compose. It assumes the repository has been cloned and the user is in the project directory.

```bash
docker-compose up
```

--------------------------------

### Install and Build Cardano Ogmios Packages

Source: https://ogmios.dev/typescript/api

Installs project dependencies and builds all packages within the Yarn Workspace. This is a prerequisite for development and testing.

```bash
yarn install && \
yarn build
```

--------------------------------

### WebSocket Connection and Request Example

Source: https://ogmios.dev/getting-started/basics

Demonstrates how to establish a WebSocket connection to Ogmios and send a JSON-RPC request using Node.js.

```APIDOC
## WebSocket Communication Example

### Description
An example of establishing a WebSocket connection to Ogmios and sending a JSON-RPC request.

### Method
WebSocket

### Endpoint
`ws://localhost:1337` (Default local instance)

### Parameters
#### Request Body (Sent over WebSocket)
- **jsonrpc** (string) - Required - "2.0"
- **method** (string) - Required - The Ogmios method to call (e.g., "findIntersection").
- **params** (object) - Optional - Parameters for the method.
- **id** (string | number) - Optional - Identifier for the request.

### Request Example (Node.js)
```javascript
const WebSocket = require('ws');
const client = new WebSocket("ws://localhost:1337");

client.once('open', () => {
    const request = {
        "jsonrpc": "2.0",
        "method": "findIntersection",
        "params": { "points": [ "origin" ] }
    };
    client.send(JSON.stringify(request));
});

client.on('message', function(msg) {
  const response = JSON.parse(msg);
  console.log('Received response:', response);
  // Process the response here
});

client.on('error', (error) => {
  console.error('WebSocket error:', error);
});
```
```

--------------------------------

### Query Network Start Time

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_schema.QueryNetworkStartTime

This endpoint allows you to query the network start time. It returns the time when the Cardano network was initiated.

```APIDOC
## POST /query/network/startTime

### Description
Query the network start time.

### Method
POST

### Endpoint
/query/network/startTime

### Parameters
#### Request Body
- **id** (unknown) - Optional - The ID for the JSON-RPC request.
- **jsonrpc** (string) - Optional - The JSON-RPC protocol version, defaults to "2.0".
- **method** (string) - Required - The method to call, must be "queryNetwork/startTime".

### Request Example
```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "queryNetwork/startTime"
}
```

### Response
#### Success Response (200)
- **result** (string) - The network start time in a string format.
- **id** (number) - The ID of the JSON-RPC request.
- **jsonrpc** (string) - The JSON-RPC protocol version.

#### Response Example
```json
{
  "result": "2017-06-09T11:40:04Z",
  "id": 1,
  "jsonrpc": "2.0"
}
```
```

--------------------------------

### Run End-to-End Tests

Source: https://ogmios.dev/getting-started/building

Steps to set up and run end-to-end tests for the TypeScript client. This requires a synchronized node on the preview network and Ogmios running on port 1337. Dependencies are installed using Yarn.

```shell
cd clients/TypeScript
yarn
yarn test
```

--------------------------------

### Ogmios State Query: System Start Time

Source: https://ogmios.dev/changelog

Retrieves the blockchain's start time in UTC. This is a new state-query feature available in recent versions of Ogmios.

```json
{
  "query": "systemStart"
}

```

--------------------------------

### QueryLedgerStateEraStart

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_schema.QueryLedgerStateEraStart

Queries the start of the current ledger era. This endpoint is part of the @cardano-ogmios/schema.

```APIDOC
## POST /queryLedgerState/eraStart

### Description
Queries the start of the current ledger era.

### Method
POST

### Endpoint
/queryLedgerState/eraStart

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - The JSON-RPC version, should be "2.0".
- **method** (string) - Required - The method name, should be "queryLedgerState/eraStart".
- **id** (unknown) - Optional - An identifier for the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/eraStart",
  "id": 1
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the query, containing the era start information.
  - **eraStart** (string) - The timestamp indicating the start of the current ledger era.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "eraStart": "2023-01-01T00:00:00Z"
  },
  "id": 1
}
```
```

--------------------------------

### Query Ledger State Era Start

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_client.Schema.QueryLedgerStateEraStartResponse

This API endpoint allows you to query the start of the current era in the Cardano ledger state using the Ogmios client.

```APIDOC
## POST /queryLedgerState/eraStart

### Description
Queries the starting point of the current era in the Cardano ledger state.

### Method
POST

### Endpoint
/queryLedgerState/eraStart

### Parameters

#### Query Parameters
None

#### Request Body
```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/eraStart",
  "id": "some-unique-id"
}
```

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/eraStart",
  "id": "my-request-123"
}
```

### Response
#### Success Response (200)
- **id** (unknown) - The unique identifier for the request.
- **jsonrpc** (string) - The JSON-RPC protocol version, should be "2.0".
- **method** (string) - The method called, which is "queryLedgerState/eraStart".
- **result** (Bound) - The result of the query, indicating the start of the era.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "my-request-123",
  "result": {
    "era": "Shelley",
    "epoch": 200,
    "slot": 1000000
  }
}
```
```

--------------------------------

### Query Ledger State Era Start

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_schema.QueryLedgerStateEraStartResponse

This endpoint allows you to query the start of an era in the Cardano ledger state. It returns information about the initial state of a specific era.

```APIDOC
## POST /queryLedgerState/eraStart

### Description
This endpoint retrieves the start information for a given era in the Cardano ledger state. It is part of the `queryLedgerState` API group.

### Method
POST

### Endpoint
/queryLedgerState/eraStart

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/eraStart",
  "id": 1
}
```

### Response
#### Success Response (200)
- **id** (unknown) - The ID of the request.
- **jsonrpc** (string) - The JSON-RPC version, always "2.0".
- **method** (string) - The method called, "queryLedgerState/eraStart".
- **result** (Bound) - The result of the query, containing information about the start of the ledger state era.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "era": {
      "id": "babbage",
      "start": {
        "slot": 159590390,
        "time": "2020-08-02T16:00:00Z"
      }
    }
  }
}
```
```

--------------------------------

### Get Cardano Era Start Bound

Source: https://ogmios.dev/typescript/api/modules/_cardano_ogmios_client.LedgerStateQuery

Retrieves the Bound representing the start of the current Cardano era. An InteractionContext is necessary for this query.

```typescript
import { InteractionContext } from "@cardano-ogmios/client";
import { Bound } from "@cardano-ogmios/client/dist/types/LedgerStateQuery";

async function getEraStart(context: InteractionContext): Promise<Bound> {
  // Assume context is already established
  const eraStart = await context.ledgerStateQuery.eraStart();
  return eraStart;
}
```

--------------------------------

### Cleanup Cardano Ogmios Project

Source: https://ogmios.dev/typescript/api

Removes build artifacts and installed dependencies, effectively cleaning the project directory. Useful for starting with a fresh state.

```bash
yarn cleanup
```

--------------------------------

### No-Schema CBOR to JSON Conversion Example

Source: https://ogmios.dev/getting-started/configuring

Demonstrates the 'no-schema' conversion of CBOR data to JSON. This method directly translates compatible CBOR objects into their JSON equivalents. It's suitable for simpler data structures but cannot represent all CBOR types due to JSON's key limitations.

```text
[1, 2, 3]

```

```json
{
  "list":
    [ { "int": 1 }
    , { "int": 2 }
    , { "int": 3 }
    ]
}

```

--------------------------------

### Constructor Functions

Source: https://ogmios.dev/typescript/api/modules/_cardano_ogmios_client

Functions for creating clients and contexts for interacting with Ogmios services.

```APIDOC
## Constructor Functions

### createChainSynchronizationClient
`createChainSynchronizationClient(context: InteractionContext, messageHandlers: ChainSynchronizationMessageHandlers, options?: object): Promise<ChainSynchronizationClient>`

Creates a client for chain synchronization.

#### Parameters
- `context`: `InteractionContext` - The interaction context.
- `messageHandlers`: `ChainSynchronizationMessageHandlers` - Handlers for chain synchronization messages.
- `options` (optional): `object`
  - `sequential` (optional): `boolean` - Whether to process messages sequentially.

#### Returns
`Promise<ChainSynchronizationClient>`

### createConnectionObject
`createConnectionObject(config?: ConnectionConfig): Connection`

Creates a connection object.

#### Parameters
- `config` (optional): `ConnectionConfig` - The connection configuration.

#### Returns
`Connection`

### createInteractionContext
`createInteractionContext(errorHandler: WebSocketErrorHandler, closeHandler: WebSocketCloseHandler, options?: object): Promise<InteractionContext>`

Creates an interaction context for managing WebSocket connections.

#### Parameters
- `errorHandler`: `WebSocketErrorHandler` - The function to handle errors.
- `closeHandler`: `WebSocketCloseHandler` - The function to handle connection closure.
- `options` (optional): `object`
  - `connection` (optional): `ConnectionConfig` - The connection configuration.
  - `maxEventListeners` (optional): `number` - The maximum number of event listeners.

#### Returns
`Promise<InteractionContext>`

### createLedgerStateQueryClient
`createLedgerStateQueryClient(context: InteractionContext, options?: object): Promise<LedgerStateQueryClient>`

Initializes a `LedgerStateQueryClient` from an `InteractionContext`.

#### Parameters
- `context`: `InteractionContext` - The interaction context.
- `options` (optional): `object`
  - `point` (optional): `Point | Origin` - The ledger point to query from.

#### Returns
`Promise<LedgerStateQueryClient>`

### createMempoolMonitoringClient
`createMempoolMonitoringClient(context: InteractionContext): Promise<MempoolMonitoringClient>`

Creates a client for inspecting the node’s local mempool.

#### Parameters
- `context`: `InteractionContext` - The interaction context.

#### Returns
`Promise<MempoolMonitoringClient>`

### createTransactionSubmissionClient
`createTransactionSubmissionClient(context: InteractionContext): Promise<TransactionSubmissionClient>`

Creates a client for submitting signed transactions to the underlying Cardano chain.

#### Parameters
- `context`: `InteractionContext` - The interaction context.

#### Returns
`Promise<TransactionSubmissionClient>`
```

--------------------------------

### Clone Ogmios Server Repository

Source: https://ogmios.dev/getting-started/building

Clones the Ogmios server repository from GitHub, ensuring recursive and shallow submodule downloads for efficiency. This is the first step in building Ogmios manually.

```bash
git clone --depth 1 --recursive --shallow-submodules git@github.com:cardanosolutions/ogmios.git
cd ogmios/server
```

--------------------------------

### Query Network Start Time

Source: https://ogmios.dev/ogmios

Queries the current network start time. This endpoint is part of the network information retrieval capabilities.

```APIDOC
## POST /queryNetworkStartTime

### Description
Query the network start time.

### Method
POST

### Endpoint
/queryNetworkStartTime

### Parameters
#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - Required - Must be "2.0".
- **method** (string) - Required - Must be "queryNetwork/startTime".
- **id** (any) - Optional - An arbitrary JSON value that will be mirrored back in the response.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "queryNetwork/startTime",
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version, must be "2.0".
- **method** (string) - The method called, will be "queryNetwork/startTime".
- **result** (string) - The network start time in UTC.
- **id** (any) - The value of the `id` field from the request.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "method": "queryNetwork/startTime",
  "result": "2021-01-01T00:00:00Z",
  "id": 1
}
```
```

--------------------------------

### Compile Ogmios Server using Cabal

Source: https://ogmios.dev/getting-started/building

Compiles the Ogmios server executable using the Cabal build tool. This command updates Cabal's package index and then builds the specified executable. The first build may take a significant amount of time due to dependency downloads.

```bash
cabal update
cabal build ogmios:exe:ogmios
```

--------------------------------

### Submit Transaction Example

Source: https://ogmios.dev/mini-protocols/local-tx-submission

An example demonstrating how to submit a transaction to the Cardano mainnet via Ogmios using WebSockets.

```APIDOC
## POST /submitTransaction

### Description
Submits a Cardano transaction to the Ogmios node for processing. This endpoint is typically used with a WebSocket connection.

### Method
POST (via WebSocket)

### Endpoint
`ws://localhost:1337` (or your Ogmios WebSocket endpoint)

### Parameters
#### Request Body
- **method** (string) - Required - The RPC method to call, e.g., "submitTransaction".
- **params** (object) - Required - An object containing the parameters for the method.
  - **transaction** (object) - Required - An object containing transaction details.
    - **cbor** (string) - Required - The CBOR-encoded transaction.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "submitTransaction",
  "params": {
    "transaction": {
      "cbor": "83a4008182582000000000000000000000000000000000000000000000000000\n      0000000000000001828258390101010101010101010101010101010101010101\n      0101010101010101010101010101010101010101010101010101010101010101\n      0101010101011a001e8480825839010202020202020202020202020202020202\n      0202020202020202020202020202020202020202020202020202020202020202\n      0202020202021a0078175c021a0001faa403191e46a1008182582001000000\n      000000000000000000000000000000000000000000000000000000005840d7af\n      60ae33d2af351411c1445c79590526990bfa73cbb3732b54ef322daa142e6884\n      023410f8be3c16e9bd52076f2bb36bf38dfe034a9f04658e9f56197ab80ff6"
    }
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (integer) - The ID of the request.
- **result** (object) - The result of the operation.
  - **hash** (string) - The hash of the submitted transaction.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hash": "f123..."
  }
}
```
```

--------------------------------

### Initialize Git Submodules for Testing

Source: https://ogmios.dev/getting-started/building

Before running tests, ensure all Git submodules are pulled and updated. This command initializes and updates any nested submodules within the project.

```shell
$ git submodule update --init
```

--------------------------------

### Ogmios Nix Build Artifacts for Static Binaries

Source: https://ogmios.dev/changelog

Static binaries for Linux are now generated by the Nix build process and uploaded as artifacts for corresponding GitHub workflows, simplifying deployment and usage.

```nix
# Example Nix build expression snippet (conceptual)
...
buildGoApplication {
  pname = "ogmios";
  version = "5.0.0";
  src = ...;
  # ... other build inputs and phases
  installPhase = ''
    mkdir -p $out/bin
    cp ./ogmios $out/bin/ogmios
  '';
}
...

```

--------------------------------

### Node.js WebSocket Client for Ogmios

Source: https://ogmios.dev/getting-started/basics

Example of a Node.js WebSocket client using the 'ws' package to connect to Ogmios, send a JSON-RPC request, and process incoming messages. This demonstrates a basic asynchronous communication pattern.

```javascript
const WebSocket = require('ws');
const client = new WebSocket("ws://localhost:1337");

client.once('open', () => {
    const request = {
        "jsonrpc": "2.0",
        "method": "findIntersection",
        "params": { "points": [ "origin" ] }
    };
    client.send(JSON.stringify(request));
});

client.on('message', function(msg) {
  const response = JSON.parse(msg);

  // do something with 'response'
});

```

--------------------------------

### Create Chain Synchronization Client

Source: https://ogmios.dev/typescript/api/modules/_cardano_ogmios_client.ChainSynchronization

This function initializes a client for chain synchronization. It requires an InteractionContext and returns a promise that resolves with the ChainSynchronizationClient.

```typescript
createChainSynchronizationClient(context: InteractionContext): Promise<ChainSynchronizationClient>
```

--------------------------------

### Query Ledger Era Start Time

Source: https://ogmios.dev/mini-protocols/local-state-query

Retrieves the start time of the current era in the ledger. Understanding era transitions is important for various on-chain operations.

```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/eraStart"
}
```

--------------------------------

### Search Index Preparation

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_client.Schema.MetadataLabels

This section details the process and status of preparing the search index. It indicates whether the index is ready for use or is currently being prepared.

```APIDOC
## Search Index Status

### Description
Provides information about the status of the search index preparation.

### Method
GET

### Endpoint
/websites/ogmios_dev/search

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the current state of the search index (e.g., "Preparing search index...", "The search index is not available").

#### Response Example
```json
{
  "status": "Preparing search index..."
}
```
```

--------------------------------

### Querying Cardano Network: Start Time

Source: https://ogmios.dev/mini-protocols/local-state-query

This snippet demonstrates how to retrieve the start time of the Cardano chain in UTC using Ogmios. This is an era-independent network query identified by the method 'queryNetwork/startTime'.

```json
{
    "jsonrpc": "2.0",
    "method": "queryNetwork/startTime"
}
```

--------------------------------

### Generate TypeScript API Reference

Source: https://ogmios.dev/getting-started/building

This command generates the TypeScript API reference documentation, which is then copied to the correct folder for Hugo to process. This is done from within the `client/TypeScript` directory.

```shell
yarn docs
```

--------------------------------

### Schema and Index Documentation

Source: https://ogmios.dev/typescript/api/interfaces/_cardano_ogmios_client.Schema.ClauseSome

Details the available schema elements and index properties for querying the Cardano blockchain via Ogmios.

```APIDOC
## Schema and Index Properties

### Description
This section details the available schema elements and index properties for querying the Cardano blockchain via the Ogmios client. It includes definitions for search capabilities and specific indexing criteria.

### Method
N/A (Documentation Only)

### Endpoint
N/A (Documentation Only)

### Parameters
N/A

### Request Example
N/A

### Response
#### Schema Definitions
- **ClauseSome** (object) - Represents a 'some' clause within a query.
  - **atLeast** (bigint) - Minimum number of elements required.
  - **clause** (string) - Specifies the type of clause, expected to be "some".
  - **from** (ScriptNative[]) - An array of native script types.

#### Index Properties
- **search** (object) - Information about the search index status.
  - **status** (string) - Indicates the status of the search index preparation (e.g., "Preparing search index...", "The search index is not available").

### Response Example
```json
{
  "schema": {
    "ClauseSome": {
      "atLeast": 1000000000000,
      "clause": "some",
      "from": [
        "ScriptNative"
      ]
    }
  },
  "index": {
    "search": {
      "status": "The search index is not available"
    }
  }
}
```
```

--------------------------------

### Full Example: Stake Distribution of All Stake Pools

Source: https://ogmios.dev/mini-protocols/local-state-query

This example demonstrates how to retrieve the stake distribution of all stake pools on the Cardano mainnet by first querying the network tip, then acquiring the ledger state, and finally requesting the live stake distribution.

```APIDOC
## WebSocket API Usage

### Description
This section details a practical example of using the WebSocket API to fetch the live stake distribution of all stake pools.

### Method
WebSocket (Client-side implementation)

### Endpoint
`ws://localhost:1337`

### Flow
1. **Open WebSocket Connection:** Establishes a connection to the Ogmios WebSocket server.
2. **Query Network Tip:** Sends a `queryNetwork/tip` request to get the current chain tip.
3. **Acquire Ledger State:** Uses the received tip to request the ledger state using `acquireLedgerState`.
4. **Query Live Stake Distribution:** Once the ledger state is acquired, requests the live stake distribution using `queryLedgerState/liveStakeDistribution`.

### Request Example (Initial Connection)
```javascript
const WebSocket = require('ws');
const client = new WebSocket("ws://localhost:1337");

function rpc(method, params = {}, id) {
    client.send(JSON.stringify({
        jsonrpc: "2.0",
        method,
        params,
        id
    }));
}

client.once('open', () => {
    rpc("queryNetwork/tip", {})
});

client.on('message', function(msg) {
    const response = JSON.parse(msg);

    switch (response.method) {
        case "queryNetwork/tip":
            const point = response.result;
            rpc("acquireLedgerState", { point });
            break;

        case "acquireLedgerState":
            rpc("queryLedgerState/liveStakeDistribution");
            break;

        default:
            console.log(response.result);
            client.close();
            break;
    }
});
```

### Response Example (Network Tip)
```json
{
    "jsonrpc": "2.0",
    "method": "queryNetwork/tip",
    "result": {
        "tip": {
            "hash": "dbafebb0146b2ec45186dfba6c287ad69c83d3fd9a186b39d99ab955631539e0",
            "slot": 12526684
        }
    },
    "id": "get-network-tip"
}
```

### Response Example (Acquired Ledger State)
```json
{
    "jsonrpc": "2.0",
    "method": "acquireLedgerState",
    "result": {
      "acquired": "ledgerState",
      "point": {
          "id": "dbafebb0146b2ec45186dfba6c287ad69c83d3fd9a186b39d99ab955631539e0",
          "slot": 12526684
      }
    },
    "id": "acquire-network-tip"
}
```

### Response Example (Live Stake Distribution - Truncated)
```json
{
    "jsonrpc": "2.0",
    "method": "queryLedgerState/liveStakeDistribution",
    "result": {
        "liveStakeDistribution": {
            "pool1w3s6gk83y2g3670emy3yfjw9myz3u4whph7peah653rmsfegyj3": {
                "stake": 0,
                "vrf": "29c1a293c550beea756bc0c01416bacd7030ae8992e13ca242d4d6c2aebaac0d"
            },
            "pool1n5shd9xdt4s2gm27fxcnuejaqhhmpepn6chw2c82kqnuzdtpsem": {
                "stake": 0.00003058882418046271,
                "vrf": "7e363eb8bfd8fef018da4c397d6a6ec25998363434e92276e40ee6c706da3ae5"
            },
            "..."
        }
    }
}
```

### Notes
- Error handling for `acquireLedgerState` might be necessary in production applications due to potential chain rollbacks.
```

--------------------------------

### Ogmios JSON-RPC Request Example

Source: https://ogmios.dev/getting-started/basics

A standard JSON-RPC 2.0 request message format for interacting with Ogmios. It includes the required 'jsonrpc' version, the 'method' to be called, and optional 'params' and 'id' fields.

```json
{
    "jsonrpc": "2.0",
    "method": "findIntersection",
    "params": { "points": [ "origin" ] },
    "id": "init-1234-5678"
}
```

--------------------------------

### POST /

Source: https://ogmios.dev/http-api

The JSON-RPC entrypoint for HTTP operations, supporting local transaction submission and state queries.

```APIDOC
## POST /

### Description
The JSON-RPC entrypoint for HTTP. Supports operations like local transaction submission and local state queries.

### Method
POST

### Endpoint
http://127.0.0.1:1337/

### Request Body
- **jsonrpc** (string) - Required. Value: "2.0"
- **method** (string) - Required. Example: "submitTransaction"
- **params** (object) - Required.
- **id** (any) - Optional. An arbitrary JSON value that will be mirrored back in the response.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "submitTransaction",
  "params": { ... },
  "id": 1
}
```

### Responses
#### Success Response (200)
- **jsonrpc** (string) - Value: "2.0"
- **result** (object) - The result of the JSON-RPC call.
  - **id** (any) - Any value that was set by a client request in the 'id' field.
- **error** (object) - An error object if the call failed.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/constitution",
  "result": {
    "metadata": {
      "url": "",
      "hash": "0000000000000000000000000000000000000000000000000000000000000000"
    },
    "guardrails": null
  },
  "id": null
}
```
```

--------------------------------

### Run Combined Cardano-Node and Ogmios Docker Image

Source: https://ogmios.dev/getting-started/docker

This command starts a Docker container that includes both a Cardano node and an Ogmios server. It maps port 1337 for Ogmios access and creates a persistent volume for the Cardano node's database. The `-it` flags enable interactive mode and signal handling.

```bash
$ docker run -it \
  --name cardano-node-ogmios \
  -p 1337:1337 \
  -v cardano-node-ogmios-mainnet-db:/db \
  cardanosolutions/cardano-node-ogmios:latest

```

--------------------------------

### QueryLedgerStateConstitutionalCommittee API

Source: https://ogmios.dev/ogmios

Get the state of the constitutional committee. This endpoint is only available from the Conway era onwards.

```APIDOC
## POST /queryLedgerState/constitutionalCommittee

### Description
Get the state of the constitutional committee (only available from Conway onwards).

### Method
POST

### Endpoint
/queryLedgerState/constitutionalCommittee

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Must be "2.0".
- **method** (string) - Required - Must be "queryLedgerState/constitutionalCommittee".
- **id** (any) - Optional - An arbitrary JSON value that will be mirrored back in the response.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/constitutionalCommittee",
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON RPC version.
- **method** (string) - The method called.
- **result** (object | null) - The state of the constitutional committee, or null if not applicable.
- **id** (any) - The arbitrary JSON value from the request.

#### Error Responses
- **QueryLedgerStateEraMismatch**: The ledger state query is not available in the current era.
- **QueryLedgerStateUnavailableInCurrentEra**: The requested ledger state is not available in the current era.
- **QueryLedgerStateAcquiredExpired**: The previously acquired ledger state is no longer available.

#### Response Example (Success)
```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/constitutionalCommittee",
  "result": { ... Committee state object ... },
  "id": 1
}
```
```json
{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/constitutionalCommittee",
  "result": null,
  "id": 1
}
```
```

--------------------------------

### Run Ogmios on Preprod Network with Custom Port

Source: https://ogmios.dev/getting-started/docker

This command demonstrates configuring Ogmios and the Cardano node for the preprod network. It sets the NETWORK environment variable to 'preprod', the OGMIOS_PORT to '1338', and uses `--project-name` to isolate the project's resources.

```bash
NETWORK=preprod OGMIOS_PORT=1338 docker-compose --project-name cardano-ogmios-preprod up
```

--------------------------------

### GET /metrics

Source: https://ogmios.dev/http-api

Retrieves Prometheus metrics for Ogmios.

```APIDOC
## GET /metrics

### Description
Retrieves Prometheus metrics for Ogmios. This endpoint provides key-value metrics compatible with Prometheus.

### Method
GET

### Endpoint
http://127.0.0.1:1337/metrics

### Responses
#### Success Response (200)
- **content** (string) - Prometheus metrics in text/plain format.
  - `connected` and `disconnected` status are encoded as `1.0` and `0.0` respectively.
  - `tip_at_genesis` is set to `1.0` when the networking tip is unknown / at genesis.

#### Response Example
```
# TYPE ogmios_active_connections gauge
ogmios_active_connections  0.0

# TYPE ogmios_connected gauge
ogmios_connected  1.0

# TYPE ogmios_cpu_time counter
ogmios_cpu_time  0

# TYPE ogmios_current_heap_size gauge
ogmios_current_heap_size  0.0

# TYPE ogmios_gc_cpu_time counter
ogmios_gc_cpu_time  0

# TYPE ogmios_max_heap_size gauge
ogmios_max_heap_size  0.0

# TYPE ogmios_session_duration_max gauge
ogmios_session_duration_max  0.0

# TYPE ogmios_session_duration_mean gauge
ogmios_session_duration_mean  0.0

# TYPE ogmios_session_duration_min gauge
ogmios_session_duration_min  0.0

# TYPE ogmios_tip_at_genesis gauge
ogmios_tip_at_genesis 1.0
```
```
Tokens:
Raw