BSV-HiLog

BSV-powered tamper-proof log attestation — Merkle aggregation, OP_RETURN anchoring, SPV verification

Overview

BSV-HiLog provides cryptographically secure, blockchain-anchored log attestation for OpenHarmony HiLog and any other logging system. Each batch of logs is hashed into a Merkle tree, and the Merkle root is permanently recorded on the BSV blockchain via OP_RETURN — making log tampering detectable and verifiable at any time.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         BSV-HiLog System Architecture                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                       OpenHarmony Device Layer                          │ │
│  │  ┌──────────────────────────────────────────────────────────────────┐ │ │
│  │  │                      HiLog SDK                                    │ │ │
│  │  │  • Log interception (Hook)  • Hash computation (SHA-256)         │ │ │
│  │  │  • Protocol encapsulation (HTTP/MQTT)                          │ │ │
│  │  └──────────────────────────────────────────────────────────────────┘ │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                         │
│                                    ▼ HTTP/gRPC/MQTT                         │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                      LogCollector (Log Collection)                     │ │
│  │  • Multi-protocol gateway  • Log normalization  • Device DID tracking │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                         │
│                                    ▼                                         │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                    MerkleAggregator (Merkle Aggregation)               │ │
│  │  • Batch queue  • Merkle tree construction  • Timeout auto-submit      │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                         │
│                                    ▼                                         │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                       BSVAnchor (BSV Anchoring)                        │ │
│  │  • OP_RETURN data  • HD wallet management  • Offline queue             │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                         │
│                                    ▼ OP_RETURN Attestation Transaction       │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                          BSV Blockchain                                 │ │
│  │  • Merkle root hash  • Batch ID  • Device DID anchoring               │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                    │                                         │
│                                    ▼                                         │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                    VerifyService (Verification)                        │ │
│  │  • SPV verification  • Merkle path verification  • Attestation receipt │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Features

• Merkle Aggregation: Batch 100+ logs into a single Merkle tree, reducing cost to <$0.000002 per log
• OP_RETURN Anchoring: Compact 80-byte format stores Merkle root + batch metadata on BSV
• SPV Verification: Verify log integrity without running a full node
• Offline Queue: SQLite-backed persistence ensures no logs are lost during network outages
• Multi-Protocol Gateway: HTTP, gRPC, and MQTT support for flexible integration
• Prometheus Metrics: Built-in metrics for monitoring log throughput and anchor status

Installation

npm install @mingchain/bsv-hilog

Quick Start

JavaScript/ES Module

import { HiLog, createHiLog } from '@mingchain/bsv-hilog';

// Create HiLog instance
const hilog = createHiLog({
  deviceId: 'device-001',
  deviceDid: 'did:bsva:abc123',
  batchSize: 100,
  walletAddress: '1HQTm7L2KXTmNTecedhFRnQqP98yU1GAD7'
});

// Log entries
hilog.log({ content: 'User login', level: 1 });
hilog.log({ content: 'Request processed', level: 1 });
hilog.log({ content: 'Error: timeout', level: 3 });

// Flush and get anchor transaction (unsigned)
const batches = hilog.flush();
console.log('Pending anchor:', batches[0]?.anchor);

// Verify a log
const result = hilog.verify({
  logHash: 'abc123...',
  batchId: 1
});
console.log('Verified:', result.isVerified());

Using the Gateway (HTTP API)

import { AttestationGateway } from '@mingchain/bsv-hilog';

const gateway = new AttestationGateway();

// Register tenant and get API key
const apiKey = gateway.registerTenant('tenant-001');

// Submit logs via HTTP
const response = await gateway.handleRequest({
  method: 'POST',
  path: '/api/v1/logs',
  headers: { 'x-api-key': apiKey },
  body: {
    deviceId: 'device-001',
    entries: [
      { content: 'Log message 1', level: 1 },
      { content: 'Log message 2', level: 3 }
    ]
  }
});

API Reference

HiLog Class

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | batchSize | number | 100 | Max logs per batch | | batchTimeoutMs | number | 60000 | Max ms before auto-flush | | walletAddress | string | 1HQTm... | BSV wallet address | | deviceId | string | auto | Unique device identifier | | deviceDid | string | auto | Device DID |

Methods

• log(entry) - Log a single entry
• logBatch(entries) - Log multiple entries
• submitLogs(entries) - Submit raw log entries
• flush() - Flush pending batches
• getAnchor(batchId) - Get anchor transaction for batch
• verify({ logHash, batchId }) - Verify log integrity
• getBatch(batchId) - Get batch information
• status() - Get system status
• destroy() - Clean up resources

Log Entry Format

{
  sequenceId: 12345,      // Optional: sequence number
  timestampNs: 1712000000000000,  // Optional: nanosecond timestamp
  level: 1,              // 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL
  logType: 0,            // 0=APP, 1=CORE, 2=INIT, 3=KMSG
  domain: 0x0001,         // Domain identifier
  tag: 'MyApp',          // Log tag
  pid: 1234,            // Process ID
  tid: 5678,            // Thread ID
  content: 'Message'     // Log message content
}

OP_RETURN Data Format (80 bytes)

┌────────────────────────────────────────────────────────────┐
│ Field              │ Length   │ Description                │
├────────────────────────────────────────────────────────────┤
│ PROTOCOL_PREFIX    │ 4 bytes  │ "BSHL" (0x4253484C)       │
│ PROTOCOL_VERSION   │ 1 byte   │ 0x01                       │
│ OPERATION          │ 1 byte   │ 0x01 = batch_attest        │
│ BATCH_ID           │ 8 bytes  │ Batch ID (big-endian)      │
│ MERKLE_ROOT        │ 32 bytes │ Merkle root hash           │
│ LOG_COUNT          │ 4 bytes  │ Log count (big-endian)     │
│ START_TIME         │ 8 bytes  │ Start timestamp (big)     │
│ END_TIME           │ 8 bytes  │ End timestamp (big)       │
│ DEVICE_DID_HASH    │ 20 bytes │ Device DID Hash160         │
│ LEVEL_MASK         │ 2 bytes  │ Log level mask             │
│ CHECKSUM           │ 2 bytes  │ CRC16 checksum            │
└────────────────────────────────────────────────────────────┘

Cost Comparison

| Solution | Cost per Log | Immutability | Verification | |----------|--------------|--------------|--------------| | BSV-HiLog | <$0.000002 | ✅ Blockchain | ✅ SPV | | Traditional PKI | $0.001-0.01 | ❌ Centralized | ❌ CA-dependent | | Other Blockchains | $0.01-1.00 | ✅ Blockchain | ✅ SPV |

At 100 logs per batch and $0.00005/BSV transaction fee, each log costs less than $0.000002.

Business Model

• Tool is Free: SDK, Merkle aggregation, and verification are fully open source
• BSV Fees Paid by User: Each batch requires a BSV transaction (~$0.00005 at current prices)
• Enterprise Support: Commercial support and managed services available from Minglian Tech

License

MIT License - see LICENSE

Related Projects

• agent-audit-trail - Agent action audit trail
• bsv-geo-shield - GEO poisoning defense for AI