# Usage

This section guides you through the **TokenTable TVM smart contract** for efficient token distribution based on merkle proof verification. Whether you're a developer deploying the contract or a user claiming tokens, this section provides key instructions for each role.

### **Smart Contract Interaction Overview**

#### **Contract Structure**

The **TokenTable TVM** consists of two primary contracts:

* **Main Distributor Contract**: Handles token distribution logic and stores the merkle root for verification.
* **Leaf Contracts**: Verifies individual merkle proofs and triggers token distribution to valid users.

#### **Deployment and Setup**

Before you begin interacting with the contract, ensure you’ve deployed the **Main Distributor Contract** and associated **Leaf Contracts**. Here’s a step-by-step process:

1. **Deploy the Main Distributor Contract**:
   * The merkle root (generated off-chain) must be provided during deployment.
   * Ensure the correct merkle tree configuration to verify users' eligibility for token claims.
2. **Deploy the Leaf Contracts**:
   * Each Leaf Contract corresponds to a specific set of users (or leaf nodes) in the merkle tree.
   * These contracts will interact with the Main Distributor Contract to validate user claims and distribute tokens.
3. **Initialize Token Distribution**:
   * Ensure the contracts are funded with sufficient tokens to execute the distribution.

#### **Claiming Tokens**

Users will interact with the contract to claim tokens. Below is a guide on how to submit a claim using a merkle proof:

1. **Generating Merkle Proof**:
   * Off-chain, generate a merkle proof for the user’s wallet address.
   * Ensure the proof corresponds to the merkle root stored in the Main Distributor Contract.
2. **Submitting Proof**:
   * The user submits their merkle proof and index directly through a smart contract interaction to their corresponding leaf.
   * The proof is validated by the contract, ensuring the user is eligible for token distribution.
3. **Token Distribution**:
   * Upon successful verification, the contract transfers the appropriate number of tokens to the user’s wallet.
   * If the proof is invalid, the contract will reject the claim and unlock the leaf ready for reclaiming.

### **Contract Roles and Permissions**

The **TokenTable TVM** smart contract enforces certain roles and permissions to maintain secure and efficient operations:

* **Admin**: The administrator has the authority to deploy the contracts, set up merkle roots, and manage the token distribution process.
* **User**: Users submit their merkle proofs to claim tokens. They can only interact with their corresponding **Leaf Contracts** and cannot alter contract configurations.
* **Fee Admin**: This administrator has the authority to collect accumulated claim fees to their wallets.

### **Common Use Cases**

Here are some scenarios illustrating how different participants may interact with the TokenTable TVM smart contract:

#### **Use Case 1: Token Distribution for an Airdrop**

A project running an airdrop campaign can use **TokenTable TVM** to distribute tokens securely to a large user base by:

* Deploying the **Main Distributor Contract** with a predefined merkle root.
* Users can claim tokens by submitting their merkle proof, ensuring only eligible wallets receive tokens.

#### **Use Case 2: Verifying Wallet Ownership**

A company can utilize the **Leaf Contracts** to verify wallet ownership through cryptographic proofs without needing to store or expose sensitive data. Users can simply submit their proof to prove ownership and receive rewards.

#### **Use Case 3: Decentralized Token Rewards**

For decentralized platforms, **TokenTable TVM** enables efficient token reward distribution to users without requiring an extensive on-chain user list. By leveraging merkle proofs, the system remains scalable and cost-efficient.

#### **Use Case 4: Batch Token Distribution**

Organizations distributing tokens to many users can use batch processing by splitting the distribution into multiple **Leaf Contracts**. This approach helps optimize gas costs and ensures the system can handle a large number of transactions.

***

In the following sections, we'll delve into more technical aspects, such as TLB structure and relationships.