ogmigo

package module
v7.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

README

ogmigo

ogmigo is a go client for ogmios.

This library is under heavy development, use at your own risk.

Example

package example

import (
	"context"
	"github.com/SundaeSwap-finance/ogmigo"
)

func example(ctx context.Context) error {
	var callback ogmigo.ChainSyncFunc = func(ctx context.Context, data []byte) error {
		// do work
		return nil
	}

	client := ogmigo.New(ogmigo.WithEndpoint("ws://example.com:1337"))
	closer, err := client.ChainSync(ctx, callback)
	if err != nil {
		return err
	}
	if err := closer.Close(); err != nil {
		return err
	}

	return nil
}

Connection reuse

By default, each request/response call (state queries, SubmitTx, EvaluateTx) dials a new WebSocket connection and closes it afterwards. Clients that make frequent calls can keep connections open between calls instead:

client := ogmigo.New(
	ogmigo.WithEndpoint("ws://example.com:1337"),
	ogmigo.WithConnectionPool(4), // keep up to 4 idle connections
)
defer client.CloseIdleConnections()

Each pooled connection carries one call at a time. Idle connections are closed after 30 seconds by default (WithPoolIdleTimeout). Chain sync and mempool monitoring are unaffected; they hold their own connections.

State queries and transaction evaluation retry once on a fresh connection if a reused connection is closed. Transaction submissions return the original connection error unless WithSubmissionRetries(true) is set. Opting in can return a duplicate rejection if the server accepted the first submission before the connection failed.

Submodules

ogmigo imports ogmios as a submodule for testing purposes. To fetch the submodules,

git submodule update --init --recursive

Documentation

Index

Constants

This section is empty.

Variables

View Source
var DefaultLogger = defaultLogger{}

DefaultLogger logs via the log package

View Source
var NopLogger = nopLogger{}

NopLogger logs nothing

Functions

func SlotToElapsedMilliseconds

func SlotToElapsedMilliseconds(history *EraHistory, slot uint64) uint64

Types

type AcquireMempoolResponse

type AcquireMempoolResponse struct {
	Method string
	Result struct {
		Acquired string
		Slot     uint64
	}
}

type ChainSync

type ChainSync struct {
	// contains filtered or unexported fields
}

ChainSync provides control over a given ChainSync connection

func (*ChainSync) Close

func (c *ChainSync) Close() error

Close the ChainSync connection

func (*ChainSync) Done

func (c *ChainSync) Done() <-chan struct{}

Done indicates the ChainSync has terminated prematurely

func (*ChainSync) Err

func (c *ChainSync) Err() <-chan error

type ChainSyncFunc

type ChainSyncFunc func(ctx context.Context, data []byte) error

ChainSyncFunc callback containing json encoded chainsync.Response

type ChainSyncOption

type ChainSyncOption func(opts *ChainSyncOptions)

ChainSyncOption provides functional options for ChainSync

func WithMinSlot

func WithMinSlot(slot uint64) ChainSyncOption

WithMinSlot ignores any activity prior to the specified slot

func WithPoints

func WithPoints(points ...chainsync.Point) ChainSyncOption

WithPoints allows starting from an optional point

func WithReconnect

func WithReconnect(enabled bool) ChainSyncOption

WithReconnect attempt to reconnect to ogmios if connection drops

func WithStore

func WithStore(store Store) ChainSyncOption

WithStore specifies store to persist points to; defaults to no persistence

type ChainSyncOptions

type ChainSyncOptions struct {
	// contains filtered or unexported fields
}

ChainSyncOptions configuration parameters

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides a client for the chain sync protocol only

func New

func New(opts ...Option) *Client

New returns a new Client

func (*Client) BlockHeight

func (c *Client) BlockHeight(ctx context.Context) (uint64, error)

func (*Client) ChainSync

func (c *Client) ChainSync(
	ctx context.Context,
	callback ChainSyncFunc,
	opts ...ChainSyncOption,
) (*ChainSync, error)

ChainSync replays the blockchain by invoking the callback for each block By default, ChainSync stores no checkpoints and always restarts from origin. These can be overridden via WithPoints and WithStore

func (*Client) ChainTip

func (c *Client) ChainTip(ctx context.Context) (chainsync.Point, error)

func (*Client) ChainTipV5

func (c *Client) ChainTipV5(ctx context.Context) (v5.PointV5, error)

func (*Client) CloseIdleConnections added in v7.0.2

func (c *Client) CloseIdleConnections()

CloseIdleConnections closes the connections a pooled client is holding open between calls. The client stays usable: later calls dial and pool connections again. It does nothing for a client without a pool.

func (*Client) CurrentEpoch

func (c *Client) CurrentEpoch(ctx context.Context) (uint64, error)

func (*Client) CurrentProtocolParameters

func (c *Client) CurrentProtocolParameters(
	ctx context.Context,
) (json.RawMessage, error)

func (*Client) CurrentProtocolParametersV5

func (c *Client) CurrentProtocolParametersV5(
	ctx context.Context,
) (json.RawMessage, error)

func (*Client) EraStart

func (c *Client) EraStart(ctx context.Context) (statequery.EraStart, error)

func (*Client) EraSummaries

func (c *Client) EraSummaries(ctx context.Context) (*EraHistory, error)

func (*Client) EvaluateTxWithAdditionalUtxos

func (c *Client) EvaluateTxWithAdditionalUtxos(
	ctx context.Context,
	data string,
	additionalUtxos []shared.Utxo,
) (response *EvaluateTxResponse, err error)

func (*Client) GenesisConfig

func (c *Client) GenesisConfig(
	ctx context.Context,
	era string,
) (json.RawMessage, error)

func (*Client) GetDelegation

func (c *Client) GetDelegation(
	ctx context.Context,
	rewardAddress string,
) (Delegation, error)

func (*Client) MonitorMempool

func (c *Client) MonitorMempool(
	ctx context.Context,
	callback MonitorMempoolFunc,
	opts ...MonitorMempoolOption,
) (*MonitorMempool, error)

func (*Client) StartTime

func (c *Client) StartTime(ctx context.Context) (string, error)

func (*Client) SubmitTx

func (c *Client) SubmitTx(
	ctx context.Context,
	data string,
) (s *SubmitTxResponse, err error)

SubmitTx submits the transaction via ogmios https://ogmios.dev/mini-protocols/local-tx-submission/

func (*Client) SubmitTxV5

func (c *Client) SubmitTxV5(ctx context.Context, data string) (err error)

func (*Client) UtxosByAddress

func (c *Client) UtxosByAddress(
	ctx context.Context,
	addresses ...string,
) ([]shared.Utxo, error)

func (*Client) UtxosByTxIn

func (c *Client) UtxosByTxIn(
	ctx context.Context,
	txIns ...chainsync.TxInQuery,
) ([]shared.Utxo, error)

type Delegation

type Delegation struct {
	PoolID  string  `json:"poolId"`
	Rewards num.Int `json:"rewards"`
}

type EraBound

type EraBound struct {
	Time  statequery.EraSeconds `json:"time"`
	Slot  uint64                `json:"slot"`
	Epoch uint64                `json:"epoch"`
}

type EraHistory

type EraHistory struct {
	Summaries []EraSummary
}

type EraParameters

type EraParameters struct {
	EpochLength uint64                     `json:"epochLength"`
	SlotLength  statequery.EraMilliseconds `json:"slotLength"`
	SafeZone    uint64                     `json:"safeZone"`
}

type EraSummary

type EraSummary struct {
	Start      EraBound      `json:"start"`
	End        EraBound      `json:"end"`
	Parameters EraParameters `json:"parameters"`
}

type Error

type Error struct {
	Type        string `json:"type,omitempty"`
	Version     string `json:"version,omitempty"`
	ServiceName string `json:"servicename,omitempty"`
	Fault       Fault  `json:"fault,omitempty"`
}

Error encapsulates errors from ogmios

func (Error) Error

func (e Error) Error() string

Error implements error interface

type EvaluateResponse

type EvaluateResponse struct {
	Type        string
	Version     string
	ServiceName string `json:"servicename"`
	MethodName  string `json:"methodname"`
	Reflection  any
	Result      json.RawMessage
}

type EvaluateTx

type EvaluateTx struct {
	Cbor string `json:"cbor"`
}

type EvaluateTxError

type EvaluateTxError struct {
	Code    int
	Message string
	Data    json.RawMessage
}

type EvaluateTxResponse

type EvaluateTxResponse struct {
	ExUnits []ExUnits
	Error   *EvaluateTxError
}

type ExUnits

type ExUnits struct {
	Validator Validator     `json:"validator"`
	Budget    ExUnitsBudget `json:"budget"`
}

type ExUnitsBudget

type ExUnitsBudget struct {
	Memory uint64 `json:"memory"`
	Cpu    uint64 `json:"cpu"`
}

type Fault

type Fault struct {
	Code   string `json:"code,omitempty"`   // Code identifies error
	String string `json:"string,omitempty"` // String provides human readable description
}

Fault provides additional context for ogmios errors

type KeyValue

type KeyValue struct {
	Key   string
	Value string
}

func KV

func KV(key, value string) KeyValue

type Logger

type Logger interface {
	Debug(message string, kvs ...KeyValue)
	Info(message string, kvs ...KeyValue)
	With(kvs ...KeyValue) Logger
}

type Map

type Map map[string]any

Map provides a simple type alias

type MonitorMempool

type MonitorMempool struct {
	// contains filtered or unexported fields
}

func (*MonitorMempool) Close

func (c *MonitorMempool) Close() error

func (*MonitorMempool) Done

func (c *MonitorMempool) Done() <-chan struct{}

func (*MonitorMempool) Err

func (c *MonitorMempool) Err() <-chan error

type MonitorMempoolFunc

type MonitorMempoolFunc func(ctx context.Context, data []*chainsync.Tx, slot uint64) error

type MonitorMempoolOption

type MonitorMempoolOption func(opts *MonitorMempoolOptions)

func WithMempoolReconnect

func WithMempoolReconnect(enabled bool) MonitorMempoolOption

type MonitorMempoolOptions

type MonitorMempoolOptions struct {
	// contains filtered or unexported fields
}

type MonitorState

type MonitorState int
const (
	AcquireMempool MonitorState = iota
	NextTransaction
)

type NextTransactionResponse

type NextTransactionResponse struct {
	Method string
	Result struct {
		Transaction *chainsync.Tx
	}
}

type Option

type Option func(*Options)

Option to cardano client

func WithConnectionPool added in v7.0.2

func WithConnectionPool(n int) Option

WithConnectionPool makes request/response calls (state queries, transaction submission and evaluation) reuse WebSocket connections instead of dialing a new one per call. Up to n idle connections are kept open between calls; concurrent calls beyond that dial extra connections, which are closed once the pool is full again. Each connection carries one call at a time. n <= 0 leaves pooling off, the default.

A pooled client holds connections open after a call returns. Call Client.CloseIdleConnections when the client is no longer needed.

State queries and transaction evaluation retry once on a new connection when a reused connection is closed. Transaction submissions do not retry unless WithSubmissionRetries(true) is also set.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint allows ogmios endpoint to set; defaults to ws://127.0.0.1:1337

func WithInterval

func WithInterval(n int) Option

WithInterval specifies how frequently to save checkpoints when reading

func WithLogger

func WithLogger(logger Logger) Option

WithLogger allows custom logger to be specified

func WithPipeline

func WithPipeline(n int) Option

WithPipeline allows number of pipelined ogmios requests to be provided

func WithPoolIdleTimeout added in v7.0.2

func WithPoolIdleTimeout(d time.Duration) Option

WithPoolIdleTimeout sets how long a pooled connection may sit idle before it is closed rather than reused; defaults to 30 seconds. Keep it below any idle timeout of a proxy or load balancer in front of Ogmios. It has no effect unless WithConnectionPool is also set.

func WithSubmissionRetries added in v7.0.2

func WithSubmissionRetries(enabled bool) Option

WithSubmissionRetries allows SubmitTx and SubmitTxV5 to retry once on a new connection when a reused connection fails. It defaults to false and has no effect unless WithConnectionPool is also set. Calls on fresh connections and cancelled calls are never retried.

The server may have accepted the first submission before the connection failed. In that case a retry can return a duplicate rejection instead of the original success. When retries are disabled, the original connection error is returned and the submission outcome remains uncertain.

type Options

type Options struct {
	// contains filtered or unexported fields
}

Options available to ogmios client

type Response

type Response struct {
	Transaction ResponseTx `json:"transaction" dynamodbav:"transaction,omitempty"`
}

type ResponseTx

type ResponseTx struct {
	ID string `json:"id,omitempty" dynamodbav:"id,omitempty"`
}

type Store

type Store interface {
	// Save the point; save will be called multiple times and should only
	// keep track of the most recent points
	Save(ctx context.Context, point chainsync.Point) error
	// Load saved points
	Load(ctx context.Context) (chainsync.Points, error)
}

Store allows points to be saved and retrieved to allow graceful recovery after shutdown

func NewLoggingStore

func NewLoggingStore(logger Logger) Store

NewLoggingStore logs Save requests, but does not actually save points

type SubmitTx

type SubmitTx struct {
	Cbor string `json:"cbor"`
}

type SubmitTxError

type SubmitTxError struct {
	Code    int
	Message string
	Data    json.RawMessage
}

type SubmitTxErrorV5

type SubmitTxErrorV5 struct {
	// contains filtered or unexported fields
}

SubmitTxError encapsulates the SubmitTx errors and allows the results to be parsed

func (SubmitTxErrorV5) Error

func (s SubmitTxErrorV5) Error() string

Error implements the error interface

func (SubmitTxErrorV5) ErrorCodes

func (s SubmitTxErrorV5) ErrorCodes() (keys []string, err error)

ErrorCodes the list of errors codes

func (SubmitTxErrorV5) HasErrorCode

func (s SubmitTxErrorV5) HasErrorCode(errorCode string) bool

HasErrorCode returns true if the error contains the provided code

func (SubmitTxErrorV5) Messages

func (s SubmitTxErrorV5) Messages() []json.RawMessage

Messages returns the raw messages from SubmitTxErrorV5

type SubmitTxPayload

type SubmitTxPayload struct {
	CBOR string `json:"cbor"`
}

type SubmitTxResponse

type SubmitTxResponse struct {
	ID    string
	Error *SubmitTxError
}

type Validator

type Validator struct {
	Purpose string `json:"purpose"`
	Index   uint64 `json:"index"`
}

Directories

Path Synopsis
logger
ouroboros
chainsync/v6
Package v6 provides the Ogmios v6 chainsync API from the v7 module.
Package v6 provides the Ogmios v6 chainsync API from the v7 module.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址