bor-sdk 1.0.0

BoR-Proof SDK — Deterministic, Replay-Verifiable Proof of Reasoning

BoR-Proof SDK — Deterministic, Replay-Verifiable Proof of Reasoning

The BoR-Proof SDK extends the Blockchain of Reasoning (BoR) framework into a system that turns every computation into a verifiable proof.
Each reasoning step, configuration, and output is encoded deterministically so that the entire process can be replayed and verified by anyone.
The SDK provides a command-line interface (CLI) and Python API for generating and checking these proofs.

---

1. Overview: The Proof Chain

Every reasoning run is represented as a 5-layer proof stack:

Layer	Purpose	Conceptual Guarantee
P₀ — Initialization	Hashes the environment and inputs	Same inputs → same start hash
P₁ — Step Proofs	Hashes each reasoning step (f, S, C, V)	Each step leaves a traceable fingerprint
P₂ — Master Proof	Aggregates all step hashes	Defines the identity of the reasoning chain (HMASTER)
P₃ — Verification	Replays and compares results	Proves reproducibility across time and machines
P₄ — Persistence	Hashes stored proof files	Detects any tampering in saved data (H_store)

Together they form a cryptographically closed reasoning ledger.

---

2. Sub-Proofs (System-Level Validations)

Eight higher-order sub-proofs check that the system behaves as it should:

ID	Proof Name	Validates
DIP	Deterministic Identity	identical runs → identical HMASTER
DP	Divergence	perturbations → different HMASTER
PEP	Purity Enforcement	impure functions rejected by @step
PoPI	Proof-of-Proof Integrity	SHA-256 hash of primary proof JSON
CCP	Canonicalization Consistency	dict/key order does not change hashes
CMIP	Cross-Module Integrity	core, verify, and store agree on results
PP	Persistence	JSON and SQLite stores produce identical HMASTER
TRP	Temporal Reproducibility	proofs stable across time delays

The hashes of these eight sub-proofs are concatenated and re-hashed to produce H_RICH, the single commitment for the entire run.

---

3. Installation

Quick Install (Recommended)

pip install bor-sdk
borp --help

Developer Install (for Contributors)

git clone https://github.com/kushagrab21/BoR-proof-SDK.git
cd BoR-proof-SDK
python -m venv .venv
source .venv/bin/activate      # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
borp --help

---

4. Generating and Verifying Proofs (from First Principles)

4.1 Generate a Proof (P₀–P₄ + Sub-Proofs)

Each command below corresponds directly to one logical assertion:

borp prove --all \
  --initial '7' \                   # S₀ (initial state)
  --config '{"offset": 4}' \         # C (configuration)
  --version 'v1.0' \                 # V (version string)
  --stages examples.demo:add examples.demo:square \
  --outdir out

This command:

1. Canonicalizes inputs (P₀)
2. Runs each step deterministically (P₁)
3. Aggregates fingerprints into HMASTER (P₂)
4. Executes all sub-proofs (DIP→TRP)
5. Produces the Rich Proof Bundle (out/rich_proof_bundle.json)

---

4.2 Verify a Proof (Fast Structural Check)

Checks the cryptographic integrity of the bundle without replaying computations:

borp verify-bundle --bundle out/rich_proof_bundle.json

This recomputes sub-proof hashes and verifies that the stored H_RICH matches the recomputed value.

---

4.3 Verify with Replay (Strong Check)

Fully re-executes the reasoning steps and recomputes HMASTER:

borp verify-bundle --bundle out/rich_proof_bundle.json \
  --initial '7' --config '{"offset":4}' --version 'v1.0' \
  --stages examples.demo:add examples.demo:square

If the recomputed HMASTER equals the stored value, the reasoning process is proven identical.

---

4.4 Show the Proof Trace

Displays the reasoning sequence in plain text:

borp show --trace out/rich_proof_bundle.json --from bundle

Each line shows function, input, output, and hash — allowing step-by-step auditability.

---

4.5 Persist Proofs (P₄ Storage Integrity)

Stores and audits proofs across JSON and SQLite backends:

borp persist --label demo --primary out/primary.json --backend both

This ensures that saved proofs can later be checked for tampering using their H_store hashes.

---

5. Example Output

[BoR P₀] Initialization Proof Hash = ...
[BoR P₁] Step #1 'add' → hᵢ = ...
[BoR P₂] HMASTER = ...
[BoR RICH] Bundle created
{
  "H_RICH": "e9ac1524f4a318a3..."
}
[BoR RICH] VERIFIED
{
  "ok": true,
  "checks": {"H_RICH_match": true, "subproof_hashes_match": true}
}

---

6. Proof Validation Matrix

Command	Proof Layer	Guarantee
borp prove --all	P₀–P₄ + sub-proofs	Generates deterministic, verifiable reasoning chain
borp verify-bundle	P₃	Validates proof structure and digest integrity
borp verify-bundle ... --stages	P₃ (Replay)	Confirms computational equivalence of reasoning
borp persist	P₄	Confirms stored proof authenticity
borp show --trace	—	Renders human-readable logical sequence

---

7. Troubleshooting

Error: ModuleNotFoundError: No module named 'bor'
→ The global Python PATH is being used. Run CLI via the virtual environment:

.venv/bin/borp --help

CLI command not found
→ Ensure you installed the SDK in editable mode within an activated environment:

pip install -e .

Note on Anaconda/venv conflicts
If you see ModuleNotFoundError: No module named 'bor', your shell is using Anaconda's global Python.

Fix:

conda deactivate
source .venv/bin/activate
pip install -e .
which borp  # should point inside .venv/bin/

Always run borp from the virtual environment, or call

python -m bor.cli --help

to guarantee correct imports.

---

8. Independent Verification Checklist

1. Clone the repository and install dependencies.
2. Run pytest -q → expect all 88 tests to pass.
3. Execute the Quickstart commands.
4. Observe [BoR RICH] VERIFIED.
5. Optionally, recompute SHA-256 of the proof JSON to confirm immutability.

---

9. Citation

@software{kushagra_bor_proof_sdk,
  author = {Kushagra Bhatnagar},
  title  = {BoR-Proof SDK: Deterministic, Replay-Verifiable Proof System},
  year   = {2025},
  url    = {https://github.com/kushagrab21/BoR-proof-SDK}
}

---

10. Architecture

bor/
├── core.py          # Proof engine (P₀–P₂)
├── decorators.py    # @step purity contract (P₁)
├── hash_utils.py    # Canonical encoding + environment hash (P₀)
├── store.py         # Persistence proofs (P₄)
├── verify.py        # Replay + bundle verification (P₃)
├── subproofs.py     # DIP→TRP system checks
├── bundle.py        # Bundle builder and index generator
└── cli.py           # Unified CLI interface

examples/
└── demo.py          # Demonstration stages

---

11. License

MIT License
© 2025 Kushagra Bhatnagar. All rights reserved.

---

12. Understanding the Results: A First-Principled Explanation

12.1 How to Read the Verification Output

When you run any BoR-Proof command, every line corresponds to a layer in the logical proof ledger:

In BoR-Proof, a reasoning chain is a closed deterministic system whose behavior is fully captured by its cryptographic invariants.

Output Prefix	Proof Layer	Interpretation
[BoR P₀]	Initialization	System has canonicalized and hashed (S₀, C, V, env) → establishes the starting fingerprint
[BoR P₁]	Step Proofs	Each reasoning function fᵢ(Sᵢ₋₁, C, V) executed deterministically; its input and output were hashed → produces hᵢ
[BoR P₂]	Master Proof	All step fingerprints concatenated and hashed → defines the unique chain identity HMASTER
[BoR P₃]	Verification	System recomputed HMASTER' and compared to stored value → confirms reproducibility
[BoR P₄]	Persistence	Proof stored in canonical JSON and SQLite forms; file integrity hashes H_store computed
[BoR RICH]	Sub-Proof Integrity	Eight higher-order sub-proofs re-hashed to form HRICH, the single immutable commitment for the entire reasoning run

If you see [BoR RICH] VERIFIED, it means every hash, sub-proof, and master digest matched.

This is equivalent to a mathematical proof of identity:

HMASTER' = HMASTER  and  HRICH' = HRICH

---

12.2 Why These Results Hold Mathematically

BoR-Proof relies on three foundational axioms of deterministic computation:

1. Referential Transparency

Each function f(S, C, V) always produces the same output given the same input—no randomness, no hidden state.

f(S, C, V) = S'  ⇒  H(f, S, C, V) is constant

2. Cryptographic Hash Collision Resistance

The probability that two different inputs produce the same hash is negligible (≈ 2⁻²⁵⁶ for SHA-256).
Thus if two proofs have identical hashes, they are indistinguishable at the bit level.

H(x) = H(y)  ⇒  x = y  (with overwhelming probability)

3. Deterministic Composition

The master proof is built by hashing hashes in sequence:

HMASTER = H(h₁ || h₂ || ... || hₙ)

Any change in any step (even one bit) alters the aggregate hash entirely.
Hence reproducibility is equivalent to equality of master hashes.

Result: When the replayed chain recomputes the same HMASTER and all sub-proofs match their stored values, the reasoning process is mathematically guaranteed to be identical to the original.

---

12.3 Conceptual Model: Proof as a Chain of Invariants

                    Inputs (S₀, C, V)
                           │
                           ▼
                ┌──────────────────────┐
                │  Canonical Encoder   │ ──→ H₀
                │        (P₀)          │
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │  Deterministic Steps │ ──→ h₁, h₂, ..., hₙ
                │        (P₁)          │
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │     Aggregator       │ ──→ HMASTER
                │        (P₂)          │
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │ Verification Replay  │ ──→ HMASTER'
                │        (P₃)          │
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │ Persistence / Audit  │ ──→ H_store
                │        (P₄)          │
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │     Sub-Proofs       │ ──→ HRICH
                │      DIP→TRP         │
                └──────────────────────┘

Figure 1: Logical flow from inputs to HRICH.

Every arrow represents a deterministic and hash-preserving transformation.
Therefore, identical arrows (executions) always produce identical end-states.

---

12.4 Mathematical Summary

Property	Formal Statement	Consequence
Determinism	f(S, C, V) = S' is pure	Repeatable computation
Canonicalization	JSON sorted, fixed precision	Platform-independent results
Hash Integrity	H(x) = SHA256(x)	Bit-level tamper detection
Chain Aggregation	HMASTER = H(h₁ ‖ ... ‖ hₙ)	Global reasoning identity
Rich Proof Integrity	HRICH = H(H(DIP), ..., H(TRP))	Compound integrity across all meta-proofs

Conclusion: Proof validity is grounded in mathematics, not authority.
Verification is a direct comparison between observed and expected invariants — a proof of equality rather than an assertion of trust.

---

12.5 Interpreting a Verified Proof (Example)

[BoR P₂] HMASTER = dde71a3e4391...
[BoR RICH] VERIFIED
{
  "checks": {
    "H_RICH_match": true,
    "primary_master_replay_match": true,
    "subproof_hashes_match": true
  },
  "ok": true
}

Interpretation:

• HMASTER identifies the reasoning chain uniquely
• Matching primary_master_replay_match proves that the reasoning logic can be replayed exactly
• HRICH_match ensures every sub-proof (DIP→TRP) agrees with stored commitments
• Together, they constitute a cryptographic certificate of logical identity

---

12.6 Why Integrity Matters Beyond Code

1. Scientific Reproducibility

Any researcher can rerun the reasoning and obtain identical hashes, establishing proof of scientific consistency.

2. Auditable AI and Computation

Decisions and outputs become verifiable artifacts, preventing silent alteration or drift.

3. Legal and Regulatory Trust

A signed proof ledger acts as immutable evidence of computation, admissible without third-party validation.

4. Philosophical Shift

Trust migrates from who computed to what was computed — a move from belief to verifiable knowledge.

---

12.7 In Essence

BoR-Proof SDK establishes a new baseline for reasoning integrity:

Correctness = Equality of Hashes
Trust = Deterministic Reproducibility

Every [VERIFIED] message you see is not a subjective approval — it is a mathematical identity proof between two complete reasoning universes.

---

12.8 Where Function Details Live

Each reasoning function used in a BoR-Proof run (for example examples.demo:add and examples.demo:square) is automatically embedded inside the proof artifact itself.

During execution, each step records:

{
  "fn": "add",
  "input": 7,
  "output": 11,
  "config": {"offset": 4},
  "version": "v1.0",
  "fingerprint": "ac971c1ddacb80d4c117bc4..."
}

When verification occurs, these same functions are re-imported and re-executed to recompute identical fingerprints.
If HMASTER remains unchanged, that means — by mathematical necessity — the same functions produced the same outputs.

Therefore:

• The README defines the logical framework
• The proof bundle contains the function-level evidence

---

12.9 Quickstart for New Nodes

If you only want to reproduce the official proof and register your node, you can do it in two commands.

Option A: Using pip (fastest)

pip install bor-sdk

# Clone repo for examples
git clone https://github.com/kushagrab21/BoR-proof-SDK.git
cd BoR-proof-SDK

borp prove --all \
  --initial '7' \
  --config '{"offset":4}' \
  --version 'v1.0' \
  --stages examples.demo:add examples.demo:square \
  --outdir out

borp register-hash --user "<your-github-handle>" --label "demo-node"

Option B: From source (for contributors)

git clone https://github.com/kushagrab21/BoR-proof-SDK.git
cd BoR-proof-SDK
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

borp prove --all \
  --initial '7' \
  --config '{"offset":4}' \
  --version 'v1.0' \
  --stages examples.demo:add examples.demo:square \
  --outdir out

borp register-hash --user "<your-github-handle>" --label "demo-node"

Check the file proof_registry.json; it now contains your node entry. Then submit it via pull request or GitHub issue (see Step 2 submission details). Average time ≈ 60 seconds.

---

Note: Future versions of BoR-Proof will extend this into a full deterministic reasoning compiler, where each reasoning step is not only hashed but also represented as a canonical intermediate form, allowing reasoning graphs to be recompiled, diffed, and verified like code.

---

13. Consensus Verification Protocol (v1.0)

Establishing Public Consensus on Deterministic Reasoning Proofs

Step 0 — Purpose of Consensus

The BoR-Proof SDK already guarantees local determinism: identical inputs always yield identical proofs.
This section extends that guarantee to public consensus — multiple independent verifiers reproducing the same proof hash (HRICH) and confirming it publicly.
In short:

If multiple users obtain the same HRICH, the reasoning process itself has reached consensus.

Consensus here is epistemic, not social — a collective proof that logic, not opinion, determines correctness.

---

Step 1 — Overview (1-Minute Summary)

Adding your proof to the public consensus ledger takes less than one minute.

Step	Action	Time
1	Run borp prove --all to generate proof	10 s
2	Run borp register-hash to record metadata	1 s
3	Verify your proof_registry.json entry	1 s
4	Submit via GitHub PR or issue	30 s
5	Wait for 2+ identical hashes → consensus reached	passive

That's all — two commands, one file, under a minute.

No networking protocols, blockchain mining, or complex configuration required.

---

Step 2 — Run Your Node

Prerequisites

Ensure you have installed the SDK in a virtual environment:

git clone https://github.com/kushagrab21/BoR-proof-SDK.git
cd BoR-proof-SDK
python -m venv .venv
source .venv/bin/activate      # or .venv\Scripts\activate on Windows
pip install -e .

---

Step 1 — Generate a Deterministic Proof

Run the proof generation command with your chosen inputs:

borp prove --all \
  --initial '7' \
  --config '{"offset":4}' \
  --version 'v1.0' \
  --stages examples.demo:add examples.demo:square \
  --outdir out

What this does:

• Creates a complete proof bundle with HMASTER and HRICH
• Executes all 8 sub-proofs (DIP, DP, PEP, PoPI, CCP, CMIP, PP, TRP)
• Saves out/rich_proof_bundle.json and out/rich_proof_index.json

Expected output (final lines):

[BoR RICH] Bundle created
{
  "HRICH": "78ead3960f3d4fdfc9bd8acac7dd01b2a5b16c589f8bcdcacfc56a2fb0e985c7"
}

Time: ~10 seconds

---

Step 2 — Register Your Consensus Node

Automatically record your proof metadata:

borp register-hash \
  --user "your-github-handle" \
  --label "demo-quickstart"

What this does:

• Extracts HRICH from out/rich_proof_bundle.json automatically
• Detects your OS, Python version, timestamp
• Creates proof_registry.json with your entry

Expected output:

[BoR Consensus] Registered proof hash: 78ead3960f3d4fdf...
[BoR Consensus] Metadata written to proof_registry.json
[BoR Consensus] User: your-github-handle  |  OS: macOS-14.0-...  |  Python: 3.12.2

Time: ~1 second

---

Step 3 — Verify Your Registry Entry

Check the generated file:

cat proof_registry.json

You should see:

[
  {
    "user": "your-github-handle",
    "timestamp": "2025-11-06T14:22:47.940056Z",
    "os": "macOS-14.0-x86_64-i386-64bit",
    "python": "3.12.2",
    "sdk_version": "v1.0",
    "label": "demo-quickstart",
    "hash": "78ead3960f3d4fdfc9bd8acac7dd01b2a5b16c589f8bcdcacfc56a2fb0e985c7"
  }
]

Time: ~1 second

---

Step 4 — Submit to Public Registry

You can contribute your consensus entry in two ways:

Option A: Pull Request (Recommended)

1. Fork the repository: https://github.com/kushagrab21/BoR-proof-SDK
2. Add your proof_registry.json entry to the repo's proof_registry.json
3. Create a pull request titled: Consensus Submission – <your-handle>

Option B: GitHub Issue

1. Create a new issue: https://github.com/kushagrab21/BoR-proof-SDK/issues
2. Title: Consensus Submission – <your-handle>
3. Paste the contents of your proof_registry.json file

Time: ~30 seconds

---

Step 5 — Consensus Confirmation (Passive)

Once 3 or more independent verifiers produce the same HRICH, the consensus epoch is confirmed.

You're done! Your entry now acts as one verifier node in the reasoning consensus network.

Total Active Time: < 1 minute

---

Step 3 — Understand the Genesis Block

The first verifier creates the genesis entry:

[
  {
    "epoch": "2025-11-06",
    "hash": "e9ac1524f4a318a3...",
    "verifiers": ["kushagrab21"],
    "status": "GENESIS_PROOF"
  }
]

When two or more additional verifiers independently reproduce the same hash, the entry updates to:

{
  "epoch": "2025-11-06",
  "hash": "e9ac1524f4a318a3...",
  "verifiers": ["kushagrab21", "alice-node", "bob-node"],
  "status": "CONSENSUS_CONFIRMED"
}

This marks the first consensus epoch — proof that reasoning reproducibility holds across machines and observers.

---

Step 4 — Optional CLI Parameters

The register-hash command supports additional configuration:

borp register-hash \
  --bundle out/rich_proof_bundle.json \
  --registry custom_registry.json \
  --user "custom-username" \
  --label "my-experiment-v2"

Options:

• --bundle: Path to proof bundle (default: out/rich_proof_bundle.json)
• --registry: Registry file to create/append (default: proof_registry.json)
• --user: Override auto-detected username
• --label: Custom label for this proof (default: unlabeled)

Multiple Entries:

Run register-hash multiple times to append additional proof entries to the same registry. Each run adds one verifier node entry.

---

Step 5 — What Your Proof Means

A verified consensus run means:

• Every participant's environment produced the same HRICH
• No hidden or nondeterministic variance exists
• Logical replayability has been independently validated

Mathematically:

HRICH(v₁) = HRICH(v₂) = ... = HRICH(vₙ)
  ⇒  Collective Proof of Reasoning Identity

Consensus, therefore, is equality of invariants across observers — extending blockchain's data immutability into reasoning immutability.

---

13.7 Summary Table

Artifact	Role	Guarantee
rich_proof_bundle.json	Local deterministic proof	Cryptographic identity
proof_manifest.json	Verifier metadata	Environment transparency
proof_registry.json	Public ledger of submissions	Cross-verifier equality
Consensus Epoch	≥ 3 identical HRICH	Public reasoning consensus

---

13.8 Closing Principle

BoR-Proof consensus transforms determinism into trust:

Correctness = Equality of Hashes
Trust = Equality across Observers

When these equalities hold, reasoning itself has reached consensus — the first reproducible proof of logic as a shared invariant.

---

13.9 Common Pitfalls

Issue	Symptom	Fix
Wrong Python interpreter	ModuleNotFoundError: No module named 'bor'	Run inside .venv
Old borp on PATH	which borp → /opt/anaconda3/bin/borp	Reactivate venv or run .venv/bin/borp
No proof_registry.json created	Forgot register-hash step	Run borp register-hash --label my-node
Different H_RICH from others	Changed inputs/config	Use exact demo parameters