# Provenance Blockchain Modules Presentation
## x/asset, x/ledger, and x/registry

---

## Overview

The Provenance blockchain provides three core modules that work together to create a comprehensive digital asset management and financial tracking system:

1. **x/asset** - Digital asset creation and management
2. **x/ledger** - Financial tracking and accounting for assets
3. **x/registry** - Role-based access control and permissions

These modules form the foundation for creating, managing, and tracking digital assets with full financial transparency and controlled access.

---

## Module 1: x/asset

### Purpose
The Asset module provides functionality for creating and managing digital assets on the Provenance blockchain. It leverages the Cosmos SDK's NFT module to represent assets as non-fungible tokens while adding additional features like asset classes, pools, tokenizations, and securitizations.

### How It Works
- **Asset Classes**: Define schemas and classifications for digital assets with JSON schema validation
- **Assets**: Create individual digital assets within asset classes with data validation
- **Pools**: Bundle multiple NFTs into tradeable marker tokens
- **Tokenizations**: Fractionalize individual NFTs into tradeable tokens
- **Securitizations**: Create structured financial products with multiple tranches

### Key Messages/Actions

#### MsgCreateAssetClass
Creates a new asset class that defines the classification and schema for digital assets.

message MsgCreateAssetClass {
    AssetClass asset_class = 1;
    string ledger_class = 2;
    string from_address = 3;
}

#### MsgCreateAsset
Creates a new digital asset within an existing asset class.

message MsgCreateAsset {
    Asset asset = 1;
    string from_address = 2;
}

#### MsgCreatePool
Creates a pool of NFTs represented by a marker token.

message MsgCreatePool {
    Coin pool = 1;
    repeated Nft nfts = 2;
    string from_address = 3;
}

#### MsgCreateTokenization
Creates a tokenization marker representing fractional ownership of an individual NFT.

message MsgCreateTokenization {
    Coin denom = 1;
    Nft nft = 2;
    string from_address = 3;
}

#### MsgCreateSecuritization
Creates a securitization with multiple pools and tranches.

message MsgCreateSecuritization {
    string id = 1;
    repeated string pools = 2;
    repeated Coin tranches = 3;
    string from_address = 4;
}

---

## Module 2: x/ledger

### Purpose
The Ledger module provides a comprehensive financial tracking system for NFTs, allowing for detailed accounting of transactions, disbursements, payments, and fees associated with NFT ownership. It maintains a chronological record of all financial activities and their impact on principal, interest, and other balances.

### How It Works
- **Ledger Classes**: Define configuration for specific classes of assets
- **Ledgers**: Track financial activities for specific NFTs or scopes
- **Ledger Entries**: Represent individual financial transactions or activities
- **Balance Buckets**: Maintain balances in different categories (Principal, Interest, Other)
- **Entry Types**: Support various transaction types (Disbursements, Payments, Fees, etc.)

### Key Messages/Actions

#### MsgCreateLedgerClass
Creates a new ledger class configuration.

message MsgCreateLedgerClass {
    LedgerClass ledger_class = 1;
    string authority = 2;
}

#### MsgCreateLedger
Creates a new ledger for an asset.

message MsgCreateLedger {
    Ledger ledger = 1;
    string authority = 2;
}

#### MsgAppendLedgerEntry
Adds one or more new entries to an existing ledger.

message MsgAppendLedgerEntry {
    string nft_id = 1;
    string asset_class_id = 2;
    repeated LedgerEntry entries = 3;
    string authority = 4;
}

#### MsgDestroyLedger
Removes a ledger and all associated data.

message MsgDestroyLedger {
    string nft_id = 1;
    string asset_class_id = 2;
    string authority = 3;
}

---

## Module 3: x/registry

### Purpose
The Registry module provides role-based access control and permissions management for digital assets. It defines who can perform specific actions on assets through a system of roles and addresses.

### How It Works
- **Registry Keys**: Unique identifiers linking registry entries to specific NFT assets
- **Registry Entries**: Contain roles and addresses that can perform those roles
- **Roles**: Define different types of permissions (Servicer, Controller, Custodian, etc.)
- **Addresses**: Blockchain addresses assigned to specific roles

### Key Messages/Actions

#### MsgRegisterNFT
Registers a new NFT in the registry with specified roles and addresses.

message MsgRegisterNFT {
    string authority = 1;
    RegistryKey key = 2;
    repeated RolesEntry roles = 3;
}

#### MsgGrantRole
Grants a role to one or more addresses.

message MsgGrantRole {
    string authority = 1;
    RegistryKey key = 2;
    RegistryRole role = 3;
    repeated string addresses = 4;
}

#### MsgRevokeRole
Revokes a role from one or more addresses.

message MsgRevokeRole {
    string authority = 1;
    RegistryKey key = 2;
    RegistryRole role = 3;
    repeated string addresses = 4;
}

#### MsgUnregisterNFT
Unregisters an NFT from the registry.

message MsgUnregisterNFT {
    string authority = 1;
    RegistryKey key = 2;
}

### Registry Roles
- **REGISTRY_ROLE_SERVICER**: Maintains and services underlying assets
- **REGISTRY_ROLE_SUBSERVICER**: Assists servicers with limited administrative capabilities
- **REGISTRY_ROLE_CONTROLLER**: Has administrative control over registry entries
- **REGISTRY_ROLE_CUSTODIAN**: Holds and safeguards underlying assets
- **REGISTRY_ROLE_BORROWER**: Can borrow against underlying assets
- **REGISTRY_ROLE_ORIGINATOR**: Creates and originates underlying assets

---

## Use Case: Loan and Payments

### Scenario
A borrower wants to take out a loan using their commercial real estate as collateral. The loan will be tracked on the blockchain with full transparency and automated payment processing.

### Step-by-Step Process

The complete loan workflow involves the following steps:

1. **Asset Creation (x/asset)** - Create asset class and property asset
2. **Registry Setup (x/registry)** - Register property with appropriate roles
3. **Ledger Creation (x/ledger)** - Create ledger for loan tracking
4. **Loan Disbursement** - Record initial loan amount
5. **Monthly Payment Processing** - Record regular payments
6. **Interest Accrual** - Track interest charges

A complete demo script with all CLI commands is available in `demo_loan_workflow.sh`. This script demonstrates the entire workflow with proper error handling, colored output, and configuration options.

To run the demo:

# Make the script executable
chmod +x demo_loan_workflow.sh

# Run the demo (commands are commented out by default)
./demo_loan_workflow.sh

# To run actual commands, uncomment the 'eval' line in the script
# and replace demo addresses with real addresses

### Benefits of This System

1. **Transparency**: All loan activities are recorded on-chain and publicly verifiable
2. **Automation**: Payments and accruals can be automated through smart contracts
3. **Auditability**: Complete audit trail of all financial transactions
4. **Access Control**: Role-based permissions ensure only authorized parties can perform actions
5. **Compliance**: Regulatory requirements can be built into the asset classes and ledger configurations
6. **Liquidity**: Assets can be tokenized or securitized for secondary market trading

### Integration Benefits

- **Asset Module**: Provides the underlying asset representation and management
- **Ledger Module**: Tracks all financial activities and maintains balances
- **Registry Module**: Controls who can perform specific actions on the assets
- **Marker Module**: Enables creation of fungible tokens for asset-backed securities
- **Exchange Module**: Allows trading of asset-backed tokens

This integrated system provides a complete solution for digital asset management, financial tracking, and regulatory compliance in the blockchain ecosystem.