Skip to main content

Secure Lock

Secure Lock is CheesePad’s on-chain locker for liquidity pools, token allocations, and vesting streams.
It combines a transparent public lock explorer with guided flows so teams can configure locks correctly while third‑party services can reliably index and display them.

This page focuses on the data model, behavior, and display conventions so that:

  • Explorers / 3rd‑party tools (e.g. DEX analytics, trackers) can ingest and show Secure Lock information consistently.
  • Developers can reason about how locks behave over time.
  • End users can quickly understand what is locked, for how long, and under which conditions it unlocks.

For contract source code, ABI, and deployment scripts, see the open‑source repository:
https://github.com/cheesepad-ai/cheese-lock.

Official CheesePad lock pages (BSC):

Deployed CheeseLock contracts​

CheeseLock is the on-chain smart contract used by CheesePad for secure token locking and vesting.

BNB Smart Chain​

CheeseLock contract address:

0x1E7826b7E3244aDB5e137A5F1CE49095f6857140

View on BscScan

BNB Smart Chain Testnet​

CheeseLock contract address:

0x1E7826b7E3244aDB5e137A5F1CE49095f6857140

View on BscScan (testnet)

On‑chain contracts & networks​

Secure Lock is implemented as an on‑chain locker contract (referred to in this document as the locker contract).

  • Contract name: typically SecureLock (see the cheese-lock repository for the exact name and ABI).
  • Networks: the component is chain agnostic, but current production deployments focus on EVM chains.
    From the product docs: “BSC is live today, but the component is chain agnostic. Use uppercase network tickers.”
  • Official addresses: locker contract addresses for each supported chain are maintained in the cheese-lock repository and CheesePad’s internal deployment configuration.

When integrating:

  • Always resolve the official locker address from:
    • The cheese-lock GitHub repository, or
    • Official CheesePad docs / announcements, or
    • Direct confirmation from the CheesePad core team.
  • Do not rely on third‑party copies of the contract address.
  • Verify that:
    • The bytecode matches the published source on the relevant block explorer.
    • The address is owned and announced by the official CheesePad team.

Third‑party explorers (e.g. DEX tools) typically:

  • Watch the locker contract events for lock creation and unlock activity.
  • Map each on‑chain record to the Secure Lock data model described below.
  • Render lock cards and details using the status, schedule, and amount fields.

Lock types we support​

At the Solidity level, the CheeseLock contract exposes one Lock struct.
Different “lock types” are represented by combinations of fields and creation functions, not by an on-chain enum.

  • Asset type (token vs LP):
    • Determined by the isLpToken flag passed to lock, vestingLock, or multipleVestingLock.
    • Internally, LP locks are registered via _lockLpToken and non-LP locks via _lockNormalToken.
    • For LP locks, cumulativeLockInfo[token].factory is set to the LP’s factory; for normal tokens it is address(0).
  • Schedule type (normal vs vesting):
    • Normal lock: created via lock(...), stored as a Lock where tgeBps == 0, cycle == 0, cycleBps == 0. It unlocks once at tgeDate.
    • Vesting lock: created via vestingLock(...) or multipleVestingLock(...), stored as a Lock where tgeBps > 0, cycle > 0, cycleBps > 0 and tgeBps + cycleBps <= 10_000. It unlocks gradually over time.

On top of this, product/UI layers are free to label locks as “LP Lock”, “Team allocation”, etc., but these labels are not encoded in the Solidity contract.

Core concepts​

At a high level, a Secure Lock instance has:

  • Lock identity: a globally unique identifier and on-chain transaction that created the lock.
  • Scope: which token or LP pair is locked and on which chain.
  • Amount: how many tokens (or LP tokens) are locked, and an optional USD reference amount.
  • Unlock schedule: when and how the locked position becomes claimable.
  • Status: whether the lock is active, partially unlocked, fully completed, or cancelled (if applicable).

The product documentation emphasizes:

  • Transparency: public lock explorer pages so anyone can verify a project’s locks.
  • Consistency: UI chips and badges that clearly communicate schedule and asset type. These are implemented at the product/indexer layer and are not part of the Solidity interface.

On-chain data model​

This section documents the actual Solidity structs and observable behavior of the CheeseLock contract.
Everything below is taken directly from the contract code in cheesepad-ai/cheese-lock.

1. Lock struct​

Each lock is stored in an array:

struct Lock {
    uint256 id;
    address token;
    address owner;
    uint256 amount;
    uint256 lockDate;
    uint256 tgeDate;      // TGE date for vesting locks, unlock date for normal locks
    uint256 tgeBps;       // In bips. Is 0 for normal locks
    uint256 cycle;        // Is 0 for normal locks
    uint256 cycleBps;     // In bips. Is 0 for normal locks
    uint256 unlockedAmount;
    string description;
}

Field semantics:

  • id: Lock identifier. In this implementation it is locks.length + ID_PADDING at creation time.
  • token: ERC‑20 token address being locked. For LP locks this is the LP token address.
  • owner: Current owner of the lock; has permission to unlock, edit, or transfer ownership.
  • amount: Total amount of tokens associated with this lock (in token smallest units).
  • lockDate: Block timestamp when the lock was created.
  • tgeDate:
    • For normal locks (tgeBps == 0 and cycle == 0 and cycleBps == 0): the unlock timestamp.
    • For vesting locks: the TGE (Token Generation Event) timestamp when the first portion becomes claimable.
  • tgeBps:
    • 0 for normal locks.
    • For vesting locks: basis points (out of 10_000) that unlock at tgeDate.
  • cycle:
    • 0 for normal locks.
    • For vesting locks: cycle duration in seconds.
  • cycleBps:
    • 0 for normal locks.
    • For vesting locks: basis points of amount that unlock on each cycle after TGE.
  • unlockedAmount: Total amount already withdrawn by the owner.
  • description: Free-form text; editable via editLockDescription.

Normal vs vesting locks:

  • lock(...) creates a normal lock:
    • tgeBps = 0, cycle = 0, cycleBps = 0.
    • tgeDate is the single unlock timestamp.
  • vestingLock(...) and multipleVestingLock(...) create vesting locks:
    • Require tgeDate > now, cycle > 0, 0 < tgeBps < 10_000, 0 < cycleBps < 10_000, and tgeBps + cycleBps <= 10_000.

2. CumulativeLockInfo struct​

The contract tracks cumulative locked amounts per token:

struct CumulativeLockInfo {
    address token;
    address factory;
    uint256 amount;
}
  • token: The ERC‑20 / LP token address.
  • factory:
    • For LP locks: the LP’s factory (e.g. UniswapV2‑compatible factory), inferred via _parseFactoryAddress.
    • For normal token locks: address(0).
  • amount: Sum of amount minus unlockedAmount over all active locks for this token.

Explorers can use factory != address(0) as a canonical way to detect LP tokens for this locker.

3. Internal sets and indexes​

Internally the contract organizes locks using EnumerableSet:

  • By user & asset type:
    • _userLpLockIds[owner] – set of LP lock IDs for a given owner.
    • _userNormalLockIds[owner] – set of non‑LP lock IDs for a given owner.
  • By token type:
    • _lpLockedTokens – set of LP token addresses with non‑zero cumulative locked amount.
    • _normalLockedTokens – set of non‑LP token addresses with non‑zero cumulative locked amount.
  • By token:
    • _tokenToLockIds[token] – set of lock IDs associated with a given token.

These sets are surfaced via various view functions documented below, and are crucial for indexers.

4. Events​

The main events emitted by CheeseLock are:

event LockAdded(
    uint256 indexed id,
    address token,
    address owner,
    uint256 amount,
    uint256 unlockDate
);

event LockUpdated(
    uint256 indexed id,
    address token,
    address owner,
    uint256 newAmount,
    uint256 newUnlockDate
);

event LockRemoved(
    uint256 indexed id,
    address token,
    address owner,
    uint256 amount,
    uint256 unlockedAt
);

event LockVested(
    uint256 indexed id,
    address token,
    address owner,
    uint256 amount,
    uint256 remaining,
    uint256 timestamp
);

event LockDescriptionChanged(uint256 lockId);

event LockOwnerChanged(uint256 lockId, address owner, address newOwner);

Indexers SHOULD:

  • Subscribe to LockAdded to detect new locks (both normal and vesting).
  • Listen to LockRemoved and LockVested to track unlocks and remaining balances.
  • Use LockUpdated to pick up changes to amount or tgeDate.
  • Use LockDescriptionChanged to refresh any cached human‑readable description.
  • Use LockOwnerChanged to track ownership transfers, including renounces (newOwner = address(0)).

5. Unlock behavior​

Unlocking logic is split between normal and vesting flows:

  • Normal unlock (_normalUnlock):
    • Requires block.timestamp >= userLock.tgeDate.
    • Requires userLock.unlockedAmount == 0 (one‑time full unlock).
    • Transfers amount to msg.sender, sets unlockedAmount = amount, updates cumulative totals, and emits LockRemoved.
  • Vesting unlock (_vestingUnlock):
    • Uses _withdrawableTokens(userLock) to compute how many tokens are currently claimable.
    • If newTotalUnlockAmount == amount, it removes the lock ID from the relevant sets and emits both LockRemoved and LockVested.
    • Always emits LockVested with amount unlocked in this call, remaining amount, and timestamp.

The helper used for vesting calculations:

function _withdrawableTokens(Lock memory userLock) internal view returns (uint256) {
    if (userLock.amount == 0) return 0;
    if (userLock.unlockedAmount >= userLock.amount) return 0;
    if (block.timestamp < userLock.tgeDate) return 0;
    if (userLock.cycle == 0) return 0;

    uint256 tgeReleaseAmount = FullMath.mulDiv(userLock.amount, userLock.tgeBps, 10_000);
    uint256 cycleReleaseAmount = FullMath.mulDiv(userLock.amount, userLock.cycleBps, 10_000);

    uint256 currentTotal = 0;
    if (block.timestamp >= userLock.tgeDate) {
        currentTotal =
            (((block.timestamp - userLock.tgeDate) / userLock.cycle) * cycleReleaseAmount) +
            tgeReleaseAmount;
    }

    if (currentTotal > userLock.amount) {
        return userLock.amount - userLock.unlockedAmount;
    } else {
        return currentTotal - userLock.unlockedAmount;
    }
}

Informally:

  • Before tgeDate: nothing is withdrawable.
  • At tgeDate: tgeBps of amount becomes available.
  • After each multiple of cycle seconds since tgeDate: an additional cycleBps of amount is released.
  • Total unlocked is capped at amount.

6. Public/external functions relevant for integrators​

From the CheeseLock implementation (and its ICheeseLock interface), key functions are:

  • Lock creation
    • lock(owner, token, isLpToken, amount, unlockDate, description) returns (uint256 id)
      • Creates a normal lock that unlocks fully at unlockDate.
    • vestingLock(owner, token, isLpToken, amount, tgeDate, tgeBps, cycle, cycleBps, description) returns (uint256 id)
      • Creates a vesting lock with TGE and cycle‑based vesting.
    • multipleVestingLock(owners[], amounts[], token, isLpToken, tgeDate, tgeBps, cycle, cycleBps, description) returns (uint256[] ids)
      • Batch version of vestingLock for multiple owners.
  • Unlocking
    • unlock(lockId)
      • If lock is vesting (tgeBps > 0), calls _vestingUnlock.
      • Otherwise, calls _normalUnlock.
    • withdrawableTokens(lockId) view returns (uint256)
      • Convenience view returning _withdrawableTokens(getLockById(lockId)).
  • Editing metadata
    • editLock(lockId, newAmount, newUnlockDate)
      • Owner‑only. Can increase amount (not decrease) and/or push tgeDate forward.
    • editLockDescription(lockId, description)
      • Owner‑only. Updates description.
  • Ownership
    • transferLockOwnership(lockId, newOwner)
    • renounceLockOwnership(lockId) (sets owner to address(0)).

Indexing & querying:

  • getTotalLockCount() view returns (uint256)
  • getLockAt(index) view returns (Lock memory)
  • getLockById(lockId) view returns (Lock memory)
  • allLpTokenLockedCount(), allNormalTokenLockedCount()
  • getCumulativeLpTokenLockInfoAt(index), getCumulativeNormalTokenLockInfoAt(index)
  • getCumulativeLpTokenLockInfo(start, end), getCumulativeNormalTokenLockInfo(start, end)
  • totalTokenLockedCount()
  • Per‑user:
    • lpLockCountForUser(user), lpLocksForUser(user), lpLockForUserAtIndex(user, index)
    • normalLockCountForUser(user), normalLocksForUser(user), normalLockForUserAtIndex(user, index)
  • Per‑token:
    • totalLockCountForToken(token)
    • getLocksForToken(token, start, end)

These views give everything a third‑party explorer needs to reconstruct all locks and balances from on-chain state.

Example data model for indexers (TypeScript)​

Below is an example off-chain schema mirroring the Solidity structs and adding a few derived helpers.
Fields marked as “derived” are computed off-chain and are not stored in the contract.

export interface LockRecord {
  id: number;
  token: string;
  owner: string;
  amount: string;          // raw token units
  lockDate: number;        // unix seconds
  tgeDate: number;         // unix seconds
  tgeBps: number;
  cycle: number;           // seconds
  cycleBps: number;
  unlockedAmount: string;  // raw token units
  description: string;

  // Derived helpers (off-chain only)
  isVesting: boolean;      // tgeBps > 0 && cycle > 0 && cycleBps > 0
  isLpToken: boolean;      // cumulativeLockInfo[token].factory != address(0)
}

export interface CumulativeLockInfoRecord {
  token: string;
  factory: string;         // 0x0 for normal tokens
  amount: string;          // total locked (minus unlocked)
}

Usage examples​

This section shows how to read lock data from the CheeseLock contract using common Ethereum libraries.

Reading lock data by ID with ethers.js​

import { ethers } from "ethers";
import CheeseLockABI from "./abi/CheeseLock.json";

const provider = new ethers.JsonRpcProvider("https://bsc-dataseed1.binance.org/");

// CheeseLock contract address on BNB Smart Chain
const contractAddress = "0x1E7826b7E3244aDB5e137A5F1CE49095f6857140";
const contract = new ethers.Contract(contractAddress, CheeseLockABI, provider);

async function getLockData(lockId: number) {
  try {
    const lockData = await contract.getLockById(lockId);
    console.log("Lock Data:", {
      id: lockData.id.toString(),                     // Unique lock identifier
      token: lockData.token,                          // Token contract address
      owner: lockData.owner,                          // Lock owner address
      amount: lockData.amount.toString(),             // Total locked amount
      lockDate: new Date(Number(lockData.lockDate) * 1000).toISOString(), // Lock creation timestamp
      tgeDate: new Date(Number(lockData.tgeDate) * 1000).toISOString(),   // TGE / unlock date
      tgeBps: lockData.tgeBps.toString(),             // TGE unlock percentage in basis points
      cycle: lockData.cycle.toString(),               // Vesting cycle duration in seconds
      cycleBps: lockData.cycleBps.toString(),         // Cycle unlock percentage in basis points
      unlockedAmount: lockData.unlockedAmount.toString(), // Amount already unlocked
      description: lockData.description,              // Lock description
    });
    return lockData;
  } catch (error) {
    console.error("Error fetching lock data:", error);
  }
}

// Example usage
getLockData(1);

Reading lock data by ID with viem​

import { createPublicClient, http, getContract } from "viem";
import { bsc } from "viem/chains";
import CheeseLockABI from "./abi/CheeseLock.json";

const publicClient = createPublicClient({
  chain: bsc,
  transport: http(),
});

const contractAddress = "0x1E7826b7E3244aDB5e137A5F1CE49095f6857140" as const;

const contract = getContract({
  address: contractAddress,
  abi: CheeseLockABI,
  publicClient,
});

async function getLockData(lockId: bigint) {
  try {
    const lockData = await contract.read.getLockById([lockId]);
    console.log("Lock Data:", {
      id: lockData.id.toString(),                     // Unique lock identifier
      token: lockData.token,                          // Token contract address
      owner: lockData.owner,                          // Lock owner address
      amount: lockData.amount.toString(),             // Total locked amount
      lockDate: new Date(Number(lockData.lockDate) * 1000).toISOString(), // Lock creation timestamp
      tgeDate: new Date(Number(lockData.tgeDate) * 1000).toISOString(),   // TGE / unlock date
      tgeBps: lockData.tgeBps.toString(),             // TGE unlock percentage in basis points
      cycle: lockData.cycle.toString(),               // Vesting cycle duration in seconds
      cycleBps: lockData.cycleBps.toString(),         // Cycle unlock percentage in basis points
      unlockedAmount: lockData.unlockedAmount.toString(), // Amount already unlocked
      description: lockData.description,              // Lock description
    });
    return lockData;
  } catch (error) {
    console.error("Error fetching lock data:", error);
  }
}

// Example usage
getLockData(1n);

Example: normal lock (non-vesting)​

{
  "id": 1,
  "token": "0xTOKEN_ADDRESS",
  "owner": "0xOWNER",
  "amount": "1000000000000000000000",
  "lockDate": 1704067200,
  "tgeDate": 1706745600,
  "tgeBps": 0,
  "cycle": 0,
  "cycleBps": 0,
  "unlockedAmount": "0",
  "description": "Team lock for 30 days",
  "isVesting": false,
  "isLpToken": false
}

Example: vesting lock with TGE and cycles​

{
  "id": 2,
  "token": "0xTOKEN_ADDRESS",
  "owner": "0xTEAM_MULTISIG",
  "amount": "5000000000000000000000000",
  "lockDate": 1704067200,
  "tgeDate": 1706745600,
  "tgeBps": 1000,
  "cycle": 2592000,
  "cycleBps": 375,
  "unlockedAmount": "0",
  "description": "Team vesting: 10% at TGE, 3.75% per month",
  "isVesting": true,
  "isLpToken": false
}

Reviewing a lock request (for ops / reviewers)​

The Secure Lock product documentation suggests the following checklist for manual review:

  1. Confirm the token address matches the Launchpad listing (if applicable).
  2. Ensure liquidity is routed to the locker before the public pool goes live.
  3. Store transaction hashes in the CMS so the leaderboard or analytics teams can surface them later.
  4. Reply via Telegram or official channels if any field is unclear, keeping the same support channels as cheesepad.ai’s footer links.

Third‑party services do not need to perform all of these steps, but they SHOULD at least:

  • Verify that the token address is correct and not a honeypot/impersonator.
  • Verify that the locker contract is the official CheesePad Secure Lock deployment for that chain.
  • Display a clear warning if any inconsistencies are detected.

Public transparency & display checklist (for explorers / analytics)​

To keep the Secure Lock experience trustworthy and visually consistent across the ecosystem, we recommend:

  • Lock cards / detail pages
    • Display lock cards on routes like /lock/<chain>/<type> using a metric grid similar to CheesePad’s homepage.
    • Show at least: token/LP name, amount, USD reference, lock type, schedule badge, and countdown timer.
  • Links and sharing
    • Include a View on explorer link (e.g. BscScan) for the lock creation transaction and token contract.
    • Include a Share button so teams can promote their proof of lock on social platforms.
  • Countdown timers
    • Show live countdown timers for active locks (time until cliff or full unlock).
    • Use brown or highlight color for active timers and slate / muted text for completed locks, matching the guidance from the official docs.
  • Badges and chips
    • Use clear chips like LP Lock, Team Allocation, Cliff, Daily, Instant, etc.
    • Match the playful chip style used on CheesePad’s own UI so users immediately recognize Secure Lock semantics.

Keeping these standards tight ensures that every Secure Lock integration feels trustworthy, predictable, and on brand, whether users are viewing it on CheesePad directly or through third‑party tools and explorers.