# Library Reference: CoReason URN Authority API
This section documents the public module boundaries and APIs provided by the native Rust library crate `coreason_urn_authority` (available under the `coreason-urn-authority` crate name on crates.io).
---
## 📦 Module Index
| [`ledger`](#ledger) | OCI registry ledger structures and file locking | `LedgerEntry`, `load_ledger`, `promote_capability` |
| [`crypto`](#crypto) | Zero-trust attestation and zk-SNARK model proof checks | `verify_code_attestation`, `verify_ezkl_proof` |
| [`cost_tracker`](#cost_tracker) | Thermodynamic cost tracking and verification | `ThermodynamicCostRecord`, `verify_cost_and_update` |
| [`nats_registry`](#nats_registry) | Async Model Context Protocol JetStream registry | `register_capability`, `resolve_urn` |
| [`epistemic`](#epistemic) | Merkle Root dependency validation | `calculate_epistemic_root` |
| [`init`](#init) | Host system profiling and KYC-to-CID calculations | `get_ram_gb`, `detect_gpu`, `calculate_tenant_cid` |
| [`routing`](#routing) | Decoupled verification routing receipt generation | `resolve_capability`, `CapabilityReceipt` |
---
## 📑 Module References
<a name="ledger"></a>
### 1. `ledger`
Provides capabilities load, parse, and atomic Promotion logic for the YAML ledger index file.
#### Structs
* **`LedgerEntry`**: Core entity representing a registered tool/capability.
```rust
pub struct LedgerEntry {
pub urn: String,
pub oci_uri: String,
pub authorized_signer_did: String,
pub tenant_cid: String,
pub mcp_registry: Option<MCPRegistryRef>,
pub license_tier: String,
pub minimum_tier: String,
pub cost_per_invocation: f64,
pub dependencies: Vec<String>,
pub royalty_shares: HashMap<String, u32>,
pub payment_splitter_address: Option<String>,
}
```
#### Functions
* `load_ledger(ledger_path: Option<PathBuf>) -> Result<Vec<LedgerEntry>, String>`
* `promote_capability(urn: &str, oci_uri: &str, did: &str, tenant_cid: &str, mcp_namespace: Option<&str>, dependencies: Vec<String>, royalty_shares: HashMap<String, u32>, payment_splitter_address: Option<&str>, ledger_path: Option<PathBuf>, skip_git: bool) -> Result<(), String>`
---
<a name="crypto"></a>
### 2. `crypto`
Provides zero-trust signature checks and ZK proof verifications.
#### Functions
* `verify_code_attestation(code_file: &Path, expected_hash: Option<&str>) -> Result<(), String>`
Calculates the SHA256 of the target code file and validates it against the co-signing signature anchor.
* `verify_ezkl_proof(proof: &Path, vk: &Path, settings: &Path) -> Result<bool, String>`
Invokes the EZKL proof engine to verify the validity of zk-SNARK inference receipts.
---
<a name="cost_tracker"></a>
### 3. `cost_tracker`
Enforces invocation budgets for tool execution via gas-like thermodynamic credits.
#### Structs
* **`ThermodynamicCostRecord`**:
```rust
pub struct ThermodynamicCostRecord {
pub capability_urn: String,
pub compute_cost_credits: f64,
pub timestamp: i64,
pub authorization_signature: String,
}
```
#### Functions
* `verify_cost_and_update(budget: f64, records: Vec<ThermodynamicCostRecord>, new_record: ThermodynamicCostRecord) -> Result<Vec<ThermodynamicCostRecord>, String>`
Verifies that the new cost record does not breach the total budget, cryptographically signs the cost updates, and appends it to the historic vector list.
* `get_postgres_schema() -> &'static str`
Outputs the native SQL schema for thermodynamic ledger tables.
---
<a name="nats_registry"></a>
### 4. `nats_registry`
Integrates capability management directly with high-performance async NATS brokers.
#### Functions
* `async fn register_capability(nats_url: &str, bucket: &str, urn: &str, clearance: &str, epistemic_status: &str, metadata: serde_json::Value, content_hash: &str) -> Result<(), String>`
* `async fn resolve_urn(nats_url: &str, bucket: &str, urn: &str) -> Result<NatsRegistryEntry, String>`
---
<a name="epistemic"></a>
### 5. `epistemic`
Encapsulates epistemic boundary analysis.
#### Functions
* `calculate_epistemic_root(project_path: &Path, manifest_version: Option<&str>) -> Result<String, String>`
Builds a Merkle Tree representing files inside the target directory and calculates the root hash for dependency boundary validation.
---
<a name="init"></a>
### 6. `init`
Enables sandboxing setups and dynamic KYC canonicalization.
#### Functions
* `calculate_tenant_cid(kyc_json: &str) -> Result<(String, String), String>`
Accepts raw KYC JSON, produces its canonical representation, and hashes it into an IPFS-style tenant Content Identifier (CID).
* `generate_egress_rules(target_path: &Path, categories: &[String]) -> Result<(), String>`
Writes secure egress firewall configs matching the specified runtime tool capabilities.