beckn-onix

Beckn-ONIX

Latest Update

In August 2025, a completely new Beckn-ONIX adapter was made available. This version introduces a Plugin framework at it's core. The ONIX Adapter previous to this release is archived to a separate branch, main-pre-plugins for reference.

Overview

Beckn-ONIX is an enterprise-grade middleware adapter system designed to facilitate seamless communication in any Beckn-enabled network. It acts as a protocol adapter between Beckn Application Platforms (BAPs - buyer applications) and Beckn Provider Platforms (BPPs - seller platforms), ensuring secure, validated, and compliant message exchange across various commerce networks.

What is Beckn Protocol?

The Beckn Protocol is an open protocol that enables location-aware, local commerce across any platform and any domain. It allows creation of open, decentralized networks where:

• Platform Independence: Buyers and sellers can transact regardless of the platforms they use
• Interoperability: Seamless communication between different systems using standardized protocols
• Domain Agnostic: Works across retail, mobility, healthcare, logistics, and other domains
• Network Neutral: Can be deployed in any Beckn-compliant network globally

Key Concepts

• BAP (Beckn Application Platform): Buyer-side applications that help users search for and purchase products/services (e.g., consumer apps, aggregators)
• BPP (Beckn Provider Platform): Seller-side platforms that provide products/services (e.g., merchant platforms, service providers)
• Beckn Network: Any network implementing the Beckn Protocol for enabling open commerce

Features

🔌 Plugin-Based Architecture

• Dynamic Plugin Loading: Load and configure plugins at runtime without code changes
• Extensible Design: Easy to add new functionality through custom plugins
• Hot-Swappable Components: Update plugins without application restart (in development)

🔐 Enterprise Security

• Ed25519 Digital Signatures: Cryptographically secure message signing and validation
• HashiCorp Vault Integration: Centralized secrets and key management
• Request Authentication: Every message is authenticated and validated
• TLS/SSL Support: Encrypted communication channels

✅ Protocol Compliance

• JSON Schema Validation: Ensures all messages comply with Beckn protocol specifications
• Version Management: Support for multiple protocol versions simultaneously
• Domain-Specific Schemas: Tailored validation for different business domains

🚀 High Performance

• Redis Caching: Response caching for improved performance
• RabbitMQ Integration: Asynchronous message processing via message queues
• Connection Pooling: Efficient resource utilization
• Configurable Timeouts: Fine-tuned performance controls

📊 Observability

• Structured Logging: JSON-formatted logs with contextual information
• Transaction Tracking: End-to-end request tracing with unique IDs
• Metrics Support: Performance and business metrics collection
• Health Checks: Liveness and readiness probes for Kubernetes

🌐 Multi-Domain Support

• Retail & E-commerce: Product search, order management, fulfillment tracking
• Mobility Services: Ride-hailing, public transport, vehicle rentals
• Logistics: Shipping, last-mile delivery, returns management
• Healthcare: Appointments, telemedicine, pharmacy services
• Financial Services: Loans, insurance, payments

Architecture

┌─────────────────────────────────────────────────────────┐
│                    HTTP Request                          │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                   Module Handler                         │
│  (bapTxnReceiver/Caller or bppTxnReceiver/Caller)      │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                 Processing Pipeline                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ Middleware  │→ │   Steps     │→ │   Plugins   │    │
│  │(preprocess) │  │(validate,   │  │(cache,router│    │
│  └─────────────┘  │route, sign) │  │validator...)│    │
│                   └─────────────┘  └─────────────┘    │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│              External Services/Response                  │
└─────────────────────────────────────────────────────────┘

Core Components

1. Transaction Modules

• bapTxnReceiver: Receives callback responses at BAP
• bapTxnCaller: Sends requests from BAP to BPP
• bppTxnReceiver: Receives requests at BPP
• bppTxnCaller: Sends responses from BPP to BAP

2. Processing Steps

• validateSign: Validates digital signatures on incoming requests
• addRoute: Determines routing based on configuration
• validateSchema: Validates against JSON schemas
• sign: Signs outgoing requests
• cache: Caches requests/responses
• publish: Publishes messages to queue

3. Plugin Types

• Cache: Redis-based response caching
• Router: YAML-based routing rules engine
• Signer/SignValidator: Ed25519 signature handling
• SchemaValidator: JSON schema validation
• KeyManager: HashiCorp Vault integration
• Publisher: RabbitMQ message publishing
• Encrypter/Decrypter: AES encryption/decryption
• ReqPreprocessor: Request preprocessing (UUID generation, headers)

Quick Start

Prerequisites

• Go 1.23 or higher
• Redis (for caching)
• Docker (optional, for containerized deployment)
• HashiCorp Vault (optional, for production key management)
• RabbitMQ (optional, for async messaging)

Installation

1. Clone the repository

git clone https://github.com/beckn/beckn-onix.git
cd beckn-onix

1. Build the application

go build -o server cmd/adapter/main.go

1. Build plugins

./build-plugins.sh

1. Start Redis (if not running)

docker run -d -p 6379:6379 redis:alpine

1. Run the application

./server --config=config/local-dev.yaml

The server will start on http://localhost:8081

Docker Deployment

# Build the Docker image
docker build -f Dockerfile.adapter -t beckn-onix:latest .

# Run the container
docker run -p 8080:8080 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/schemas:/app/schemas \
  beckn-onix:latest

Basic Usage Example

1. Search for Products (BAP → BPP)

curl -X POST http://localhost:8081/bap/caller/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Signature keyId=\"bap.example.com|key1|ed25519\",algorithm=\"ed25519\",created=\"1234567890\",expires=\"1234567990\",headers=\"(created) (expires) digest\",signature=\"base64signature\"" \
  -d '{
    "context": {
      "domain": "nic2004:60221",
      "country": "IND",
      "city": "std:080",
      "action": "search",
      "core_version": "0.9.4",
      "bap_id": "bap.example.com",
      "bap_uri": "https://bap.example.com/beckn",
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "message_id": "550e8400-e29b-41d4-a716-446655440001",
      "timestamp": "2023-06-15T09:30:00.000Z",
      "ttl": "PT30S"
    },
    "message": {
      "intent": {
        "fulfillment": {
          "start": {
            "location": {
              "gps": "12.9715987,77.5945627"
            }
          },
          "end": {
            "location": {
              "gps": "12.9715987,77.5945627"
            }
          }
        }
      }
    }
  }'

Configuration

Configuration Structure

appName: "beckn-onix"
log:
  level: debug
  destinations:
    - type: stdout
http:
  port: 8080
  timeout:
    read: 30
    write: 30
    idle: 30
pluginManager:
  root: ./plugins
modules:
  - name: bapTxnReceiver
    path: /bap/receiver/
    handler:
      type: std
      role: bap
      plugins:
        cache:
          id: cache
          config:
            addr: localhost:6379
        router:
          id: router
          config:
            routingConfig: ./config/routing.yaml
        schemaValidator:
          id: schemavalidator
          config:
            schemaDir: ./schemas
      steps:
        - validateSign
        - addRoute
        - validateSchema

Deployment Modes

1. Combined Mode: Single instance handling both BAP and BPP (config/onix/)
2. BAP-Only Mode: Dedicated buyer-side deployment (config/onix-bap/)
3. BPP-Only Mode: Dedicated seller-side deployment (config/onix-bpp/)
4. Local Development: Simplified configuration (config/local-dev.yaml)

API Endpoints

BAP Endpoints

BPP Endpoints

Documentation

• Setup Guide: Complete installation, configuration, and deployment instructions
• Contributing: Guidelines for contributors
• Governance: Project governance model
• License: Apache 2.0 license details

GUI Component

The project includes a Next.js-based GUI component located in onix-gui/ that provides:

• Visual configuration management
• Request/response monitoring
• Plugin status dashboard
• Routing rules editor

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific test
go test ./pkg/plugin/implementation/cache -v

# Run tests with race detection
go test -race ./...

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Code of Conduct
• Development process
• Submitting pull requests
• Reporting issues

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Beckn Foundation for the protocol specifications