README
¶
optimum-common
Shared Go SDK for Optimum services. Provides configuration, networking, logging, concurrency primitives, and other foundational utilities used across the Optimum ecosystem.
Installation
go get github.com/getoptimum/optimum-common
Requires Go 1.26.5 or later.
Packages
| Package | Description |
|---|---|
pkg/chain |
Blockchain chain helpers for generic usage |
pkg/config |
Runtime configuration with env/flag/YAML binding and hot-reload |
pkg/entities |
Shared domain types for P2P and dynamic config |
pkg/hash |
Hashing utilities (SHA-256, xxHash) |
pkg/identity |
Node identity key management |
pkg/io |
I/O utilities including rotating file writer |
pkg/jwks |
JWKS key cache with disk fallback and background refresh |
pkg/logger |
Structured logging interface and helpers |
pkg/maps |
Generic map utilities |
pkg/math |
Safe integer conversions with overflow protection |
pkg/net |
Networking: external IP detection, multiaddr builder, HTTP client |
pkg/pointers |
Generic pointer helpers |
pkg/rand |
Cryptographic random utilities |
pkg/slices |
Generic slice operations (unique, filter, chunk, flatten) |
pkg/sql |
SQL query builders for bulk insert and upsert |
pkg/syncx |
Concurrency: TTL map, read-write map, broadcaster, balancer |
pkg/telemetry |
Geolocation service client |
pkg/test_utils |
Test helpers and fixtures |
pkg/version |
Build version and commit metadata |
Usage
import (
"github.com/getoptimum/optimum-common/pkg/config"
"github.com/getoptimum/optimum-common/pkg/logger"
commonnet "github.com/getoptimum/optimum-common/pkg/net"
)
// Detect public IP (falls back to interface inspection in hermetic environments)
ipv4, ipv6, err := commonnet.GetExternalIPs()
// Safe integer conversion
import "github.com/getoptimum/optimum-common/pkg/math"
val, err := math.SafeIntToUint32(someInt)
Development
The project uses a Makefile for common tasks:
make test # Run unit tests with coverage (81% threshold)
make lint # Run golangci-lint
make fuzz # Run fuzz tests
make vulcheck # Run govulncheck
make bench # Run benchmarks
make fmt # Format code
make vet # Run go vet
make tidy # Run go mod tidy
Contributing
See CONTRIBUTING.md for guidelines on filing issues, submitting pull requests, and code standards.
Security
To report a vulnerability, see SECURITY.md.
Code of Conduct
This project follows the Contributor Covenant.
License
Licensed under the BSD 3-Clause License; see LICENSE. BSD-3-Clause
is permissive and GPL-compatible, so this shared library links into both copyleft
and proprietary Optimum products without imposing copyleft on them.
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
pkg
|
|
|
chain
Package chain provides blockchain chain ID helpers and validation utilities.
|
Package chain provides blockchain chain ID helpers and validation utilities. |
|
config
Package config provides a tiny loader that populates a configuration struct from multiple sources with clear precedence:
|
Package config provides a tiny loader that populates a configuration struct from multiple sources with clear precedence: |
|
entities
Package entities defines shared domain types for P2P messaging and dynamic configuration.
|
Package entities defines shared domain types for P2P messaging and dynamic configuration. |
|
hash
Package hash provides SHA-256 and xxHash helpers for message and content hashing.
|
Package hash provides SHA-256 and xxHash helpers for message and content hashing. |
|
identity
Package identity manages libp2p node identity keys on disk.
|
Package identity manages libp2p node identity keys on disk. |
|
io
Package io provides atomic file I/O and rotating file writer utilities.
|
Package io provides atomic file I/O and rotating file writer utilities. |
|
jwks
Package jwks implements a JWKS cache with disk fallback and background refresh.
|
Package jwks implements a JWKS cache with disk fallback and background refresh. |
|
logger
Package logger defines the structured AppLogger interface and slog-backed helpers.
|
Package logger defines the structured AppLogger interface and slog-backed helpers. |
|
maps
Package maps provides generic map utility functions.
|
Package maps provides generic map utility functions. |
|
math
Package math provides safe integer conversions with overflow protection.
|
Package math provides safe integer conversions with overflow protection. |
|
net
Package net provides external IP detection, multiaddr builders, and HTTP client helpers.
|
Package net provides external IP detection, multiaddr builders, and HTTP client helpers. |
|
pointers
Package pointers provides generic pointer conversion helpers.
|
Package pointers provides generic pointer conversion helpers. |
|
rand
Package rand provides cryptographic random byte and integer utilities.
|
Package rand provides cryptographic random byte and integer utilities. |
|
slices
Package slices provides generic slice operations such as unique, filter, chunk, and flatten.
|
Package slices provides generic slice operations such as unique, filter, chunk, and flatten. |
|
sql
Package sql provides bulk insert and upsert SQL query builders with retry helpers.
|
Package sql provides bulk insert and upsert SQL query builders with retry helpers. |
|
syncx
Package syncx provides concurrency primitives including TTL maps, RW maps, broadcasters, and balancers.
|
Package syncx provides concurrency primitives including TTL maps, RW maps, broadcasters, and balancers. |
|
telemetry
Package telemetry provides geolocation lookup and Prometheus metric registry helpers.
|
Package telemetry provides geolocation lookup and Prometheus metric registry helpers. |
|
test_utils
Package test_utils provides shared test helpers and fixtures for Optimum services.
|
Package test_utils provides shared test helpers and fixtures for Optimum services. |
|
version
Package version exposes build version and commit metadata injected at compile time.
|
Package version exposes build version and commit metadata injected at compile time. |
Click to show internal directories.
Click to hide internal directories.