Untitled

# Smart Contract Specifications: Inputs & Outputs

This document outlines the expected input parameters and output data for the core functions of each proposed Smart Contract in the Bitzaro Kub Chain architecture.

---

## 1. Reserve Controller Contract (The Guard)
This contract ensures that internal token supply never exceeds external physical reserves.

### `updateExternalReserve`
Updates the known external reserve balance for a specific asset.
*   **Caller:** Multi-sig Admin or Authorized Backend Role.
*   **Inputs:**
    *   `assetId` (String/Bytes32): e.g., "BTC", "USDT"
    *   `newReserveAmount` (Uint256): The updated total amount held in external wallets.
*   **Outputs:**
    *   `success` (Boolean): True if successfully updated.
    *   *Event Emitted:* `ReserveUpdated(assetId, oldAmount, newAmount, timestamp)`

### `validateAndMint`
Checks if there are enough reserves before calling the Token Contract to mint.
*   **Caller:** Authorized Backend Minter Role.
*   **Inputs:**
    *   `kubAddress` (Address): The user's internal Kub Chain wallet.
    *   `assetId` (String/Bytes32): The asset to mint (e.g., "BTC").
    *   `amount` (Uint256): The amount to mint.
    *   `externalDepositTxHash` (String): The native chain transaction hash (for audit tracing).
*   **Outputs:**
    *   `success` (Boolean): True if condition `(Total Supply + Amount <= External Reserve)` is met and minting succeeds.
    *   *Event Emitted:* `MintValidated(kubAddress, assetId, amount)`

---

## 2. User Registry Contract (Account Binding)
Maps internal Kub Chain addresses to external deposit profiles.

### `bindUserProfile`
Binds a Kub address to a hashed profile of external addresses.
*   **Caller:** Authorized Backend Role (after user verification).
*   **Inputs:**
    *   `kubAddress` (Address): The user's Kub Chain wallet.
    *   `hashedProfileData` (Bytes32): A Keccak256 hash containing the user's BTC, TRON, and EVM deposit addresses.
*   **Outputs:**
    *   `success` (Boolean): True if successfully bound.
    *   *Event Emitted:* `UserBound(kubAddress, timestamp)`

### `verifyUserBinding`
Checks if a given external address hash belongs to the specific Kub Address.
*   **Caller:** Reserve Controller (during minting) or Backend.
*   **Inputs:**
    *   `kubAddress` (Address): The user's Kub Chain wallet.
    *   `hashedProfileData` (Bytes32): The hash to verify against.
*   **Outputs:**
    *   `isBound` (Boolean): True if the hashes match.

---

## 3. Bitzaro Token Contracts (KAP-20 / ERC-20)
The actual token contracts (e.g., Bitzaro-BTC, Bitzaro-USDT).

### `mint`
Creates new tokens.
*   **Caller:** Strictly restricted to the **Reserve Controller Contract**.
*   **Inputs:**
    *   `to` (Address): The user's Kub Chain wallet.
    *   `amount` (Uint256): Amount of tokens to create.
*   **Outputs:**
    *   `success` (Boolean)
    *   *Event Emitted:* `Transfer(address(0), to, amount)`

### `burn`
Destroys tokens when a user initiates a withdrawal to the external native chain.
*   **Caller:** Authorized Backend Role (or User if self-withdrawing).
*   **Inputs:**
    *   `from` (Address): The user's Kub Chain wallet.
    *   `amount` (Uint256): Amount to destroy.
*   **Outputs:**
    *   `success` (Boolean)
    *   *Event Emitted:* `Transfer(from, address(0), amount)`

---

## 4. Token Factory Contract
Automates the creation of new Bitzaro tokens to ensure standardized security.

### `createNewToken`
Deploys a new KAP-20 token contract based on the audited template.
*   **Caller:** Multi-sig Admin.
*   **Inputs:**
    *   `name` (String): e.g., "Bitzaro Bitcoin"
    *   `symbol` (String): e.g., "BBTC"
    *   `decimals` (Uint8): e.g., 8 for BTC, 18 for ETH
*   **Outputs:**
    *   `newTokenAddress` (Address): The deployed contract address on Kub Chain.
    *   *Event Emitted:* `TokenCreated(name, symbol, newTokenAddress)`

---

## 5. Paymaster Contract (Gas Sponsor)
Handles gas sponsorship so users don't need to pay KUB for internal transfers.

### `sponsorTransaction`
Validates and pays for a user's transaction.
*   **Caller:** Kub Chain EntryPoint (ERC-4337 mechanism) or Bitzaro Relayer.
*   **Inputs:**
    *   `userOperation` (Struct): Contains sender, recipient, amount, and signature.
*   **Outputs:**
    *   `validationResult` (Uint256): 0 if the Paymaster agrees to pay the gas fee, otherwise reverts.

### `depositFunds`
Adds native KUB to the Paymaster to fund future user transactions.
*   **Caller:** Multi-sig Admin or Financial Ops.
*   **Inputs:**
    *   `amount` (Value/Payable): Amount of native KUB sent with the transaction.
*   **Outputs:**
    *   None (Updates contract balance).