Skip to content

📊 LedgerGr.id

Part of Ecosystem: OpenOS

The Ledger Stack provides an end-to-end telemetry platform for AIOS and agent-based systems. It unifies transactions, metrics, tracing, and logging with SDKs, Kubernetes deployments, and global metrics services - giving you a complete runtime visibility layer.

Key Points of LedgerGrid

  • Optionally Immutable Record: Once data (such as an agent transaction, model update, or compute exchange) is written to the ledger, it can be made immutable, ensuring a permanent history when required. For adaptive systems, records can also be mutable under governed policies, enabling reversible updates, state rollbacks, or controlled evolution.
  • Distributed & Shared: The ledger is not stored in a single location. Every relevant participant in the decentralized AI network can access and maintain copies of ledger entries only tied to their interactions or transactions. With proper permissions, the ledger can extend visibility to larger communities, federations, or the whole network, enabling open auditing and accountability.
  • Consensus-Driven: Updates to the ledger (new records, task results, or agent interactions) occur as part of transaction flows, with final entries confirmed only when involved parties or the broader network reach consensus on validity.
  • Transparent & Verifiable: Since all participating agents and entities share relevant ledger views, any participant can verify the sequence and correctness of interactions, ensuring trust and auditability across the decentralized AI network. Provides auditability for compute contributions, resource usage, AI model sharing, and agent decision-making.

Types of Ledgers in LedgerGrid

  • Public Ledger: Open for access to all participants in the decentralized AI network.
  • Private Ledger: Controlled by a single entity, with restricted visibility.
  • Consortium Ledger: Shared among multiple organizations, with defined permissions for participation and validation.
  • Local ledger:Shared among participatns local to a transaction only.

In Short

A LedgerGrid ledger is a distributed record of AI transactions and states that ensures open auditability, transparency, and coordinated trust for all participants.

Extended Functions of LedgerGrid

Agent Accountability: Records every agent’s actions, decisions, and resource use, enabling traceability and responsibility assignment.

Provenance & Integrity: Tracks the origins, transformations, and usages ensuring trust in shared environment.

Economic & Value Exchange Layer: Supports logging of micro-transactions, resource credits, and service exchanges between agents. Acts as the economic backbone for AI-driven marketplaces within the network.

Policy & Governance Integration: LedgerGrid works with governance frameworks (e.g.,PolicyGrid) to enforce alignment, permissions, and compliance.

Kubernetes Deployment Layer

Inside k8s/ are Helm-based deployment scripts to quickly install observability components:

  • deploy_observability_stack.sh → End-to-end stack (Prometheus, Grafana, Thanos Ruler, etc.)
  • deploy_tracing.sh → Tempo (traces) + OTel Collector
  • deploy_logging.sh → Loki + Promtail + Grafana
  • global-metrics/ → Deploys Redis + global metrics collectors for blocks, clusters, and vDAGs
  • logging-stack/ → Customizable Loki stack with persistence and password scripts
  • k8s_dashboard.sh → Quick install of the Kubernetes dashboard
  • deploy_timescaledb.sh → Installs TimescaleDB (single or multinode) for transactions storage, with optional PgBouncer and backups
  • tx-server.yaml → Deployment with two containers (the tx-server API/worker and a Redis sidecar for the queue) plus a Service on port 8080
  • tx-queue.yaml → Optional shared Redis Streams queue if you prefer a central queue instead of a sidecar

This forms the in-cluster observability backbone, plus a durable transactions pipeline for agent events.

SDK Layer

Inside sdks/ are Python SDKs for embedding observability directly in your applications:

  • Metrics SDK (aios_metrics)
  • Prometheus-native metrics (Counter, Gauge, Histogram)
  • Rolling averages (1m/5m/15m)
  • Optional Redis publishing with batching & backoff

  • JSON snapshots for collectors

  • Tracing SDK (aios_tracing)

  • OpenTelemetry wrapper (OTLP gRPC/HTTP)
  • Decorators for sync/async spans
  • Context propagation (W3C/B3)

  • Logging correlation + auto-instrumentation

  • Transactions SDK (agents_txs)

  • Queue client to enqueue inserts/updates/deletes
  • REST client for rich queries and search
  • High-level manager that auto-scopes by subject/agent

These SDKs allow agents & services to self-instrument and ledger transactions with minimal effort.

System Services Layer

Inside system/ are long-running services and databases that persist and expose telemetry:

  • daemonset/ → Node-level collectors for hardware (CPU, GPU, memory, etc.)
  • global-metrics/ → Block, cluster, and vDAG level metrics services (with DB + APIs)
  • metrics/ → Core metrics DB + writers
  • transactions/ → TimescaleDB-backed transaction storage, tx-server API/worker, and queue consumer

Each service includes a Dockerfile, requirements, and entrypoint, making them Kubernetes-native.

🎯 Supported Components

Subsystem Brief
K8s Deployments Helm-based scripts for metrics, tracing, logging, dashboard.
Metrics SDK Prometheus + Redis metrics with rolling averages & JSON snapshots.
Tracing SDK OpenTelemetry wrapper with decorators, logging, and context propagation.
Global Metrics DBs Block, cluster, and vDAG metrics storage & query APIs.
Daemonset Collectors Node-level collectors for hardware/system metrics.
Logging Stack Loki + Promtail + Grafana, with persistence & S3 options.
Transactions Stack TimescaleDB + tx-server + Redis Streams queue + Python SDK.

📚 Contents

Metrics and Tracing

  1. Introduction
  2. Deploying Stacks
  3. Metrics Instrumentation SDK
  4. Tracing Instrumentation SDK

Transactions Ledger

  1. Deploying stack
  2. Transactions Queue Service
  3. Transactions instrumentation SDK
  4. Usage in Platform - Communications logging in AGIGr.id
  5. Usage in Platform - Inference server requests logging in AIGr.id

🚀 Features

  • 📊 Metrics SDK + Services (Prometheus + Redis + rolling summaries)
  • 🕵️ Tracing SDK + Tempo deployment for distributed tracing
  • 📜 Logging Stack with Loki, Promtail, Grafana, persistence, S3/MinIO
  • 🧾 Transactions & Ledgering with time-based batching, JSONB schema, and rich REST queries
  • 🌍 Global Metrics for block, cluster, and vDAG observability
  • ☁️ Kubernetes-first deployments via Helm shell scripts
  • 🛠 Extensible SDKs for easy instrumentation

🤝 Contributing

This project is community-driven. Contributions welcome!

Ways to Contribute

  • Add new exporters or storage backends
  • Extend Promtail pipelines (JSON parsing, multiline logs)
  • Add tracing propagators or custom samplers
  • Improve metrics ingestion and dashboards
  • Extend tx-server queries and SDK coverage
  • Write tutorials & examples

📢 Communications