Metadata-Version: 2.4
Name: lumen-sdk
Version: 0.5.0
Summary: Lumen SDK: cryptographic ledger verification and Merkle integrity engine
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: aiosqlite>=0.19.0
Dynamic: license-file

# Lumen SDK

## Verifiable Event Ledger and Integrity Framework

Lumen SDK is a cryptographic integrity toolkit for building auditable data systems. It provides immutable event journaling, Merkle verification, forensic auditing, and validation workflows for applications that require trustworthy data history.

---

## Overview

Lumen SDK provides a foundation for systems that need to prove data integrity, detect unauthorized changes, and maintain verifiable records.

The framework combines:

- Cryptographic event journaling
- Transaction manifests
- Merkle tree verification
- HMAC authentication
- Forensic ledger auditing
- Telemetry integrity validation

---

## Features

### Cryptographic Ledger

- Immutable event records
- SHA-256 integrity hashing
- HMAC-based authentication
- Transaction manifest validation
- Event lineage tracking
- Historical state preservation

### Verification Engine

- Merkle root calculation
- Merkle integrity validation
- Corruption detection
- Chain fracture detection
- Manifest authentication checks
- Event seal verification

### Testing Framework

Lumen SDK includes validation tooling for:

- Sequential scale testing
- Blind corruption testing
- Adversarial modification testing
- Chaos testing
- Resiliency testing
- Multi-node replication experiments

---

## Installation

Clone the repository:

git clone https://github.com/jasonharoldchavez/lumen-sdk.git

cd lumen-sdk

Install:

python3 -m pip install -e .

---

## Quick Example

from lumen import MerkleTreeEngine

events = [
    "a"*64,
    "b"*64,
    "c"*64
]

root = MerkleTreeEngine.compute_root(events)

print(root)

---

## Package Validation

The installable SDK package has been verified:

Lumen SDK import OK

Merkle root generation successful

Installed package validation OK

---

## Project Structure

lumen-sdk/

├── lumen/
│   ├── __init__.py
│   ├── sqlite_engine.py
│   ├── merkle.py
│   └── verifier.py

├── core/
│   ├── sqlite_engine.py
│   ├── merkle.py
│   ├── verifier.py
│   └── network components

├── examples/
│   └── nasa_telemetry_test.py

├── tests/
│   ├── scale_test.py
│   ├── blind_test.py
│   ├── chaos_test.py
│   ├── resiliency_test.py
│   └── final_blind_test.py

├── pyproject.toml

└── README.md

---

## Validation Results

Lumen SDK has been tested with:

- Ledger creation tests
- 100+ block integrity validation
- Blind forensic audits
- Artificial corruption injection
- Chain integrity verification
- External telemetry validation

---

## Telemetry Integrity Validation

Lumen SDK was validated using NASA Telemanom telemetry data as an external telemetry source.

The validation demonstrated:

- Telemetry event ingestion
- Cryptographic event recording
- Merkle integrity generation
- Ledger chain verification
- Forensic audit validation

Result:

Status: VERIFIED

Manifests processed: 1

Errors: []

## Security Model

Lumen SDK uses:

- Cryptographic hashing
- HMAC verification
- Merkle integrity proofs
- Immutable event ordering
- Manifest authentication
- Forensic auditing

Designed to detect:

- Modified records
- Invalid event seals
- Broken transaction chains
- Unauthorized data changes
- Ledger corruption

---

## Release History

### v0.1.0

Initial release:

- Ledger engine
- Merkle verification
- Validation suite
- Network layer

### v0.2.0-nasa-validation

Added:

- NASA Telemanom validation benchmark
- External telemetry testing

### v0.3.0-sdk-structure

Added:

- Organized SDK structure
- Examples directory
- Validation test organization

### v0.4.0-package-ready

Added:

- Installable Python package
- Package exports
- Editable installation support

---


### v0.4.1-package-fix
Added:
- Fixed package discovery configuration
- Improved package distribution compatibility

### v0.5.0
Added:
- Corrected SDK usage examples
- Verified package installation workflow
- Prepared release package artifacts

### v0.6.0
Added:
- Dual licensing documentation
- Apache 2.0 open source license
- Commercial licensing option
- Contributor and usage terms documentation

## Limitations

Lumen SDK is an integrity verification toolkit.

It provides:

- Data integrity validation
- Audit verification
- Tamper detection mechanisms

It does not provide:

- Guaranteed prevention of all attacks
- Automatic compliance certification
- Managed hosting
- Included support services unless separately provided

## Licensing

Lumen SDK uses a dual license model.

Open source use:
- Apache License 2.0

Commercial use:
- Commercial licensing is available for organizations requiring additional rights or commercial deployment terms.

See:
- LICENSE
- COMMERCIAL_LICENSE.md
- NOTICE


## Commercial Use

Lumen SDK is available under a dual license model.

The Apache License 2.0 license supports open source usage.

Commercial licensing is available for organizations requiring:
- proprietary deployment rights
- commercial integration terms
- additional licensing permissions

Contact the project owner for commercial licensing inquiries.

## Development Status

Active development.

Lumen SDK is being developed as a foundation for verifiable, auditable, integrity-focused data systems.

---

## Author

Jason Chavez
