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.