إنتقل إلى المحتوى الرئيسي

Events and data reference

كل ما تحتاجه أداة فهرسة أو لوحة معلومات: الأحداث التي يجب الاستماع إليها، وكيفية البحث العكسي عن بيع، وكل بنية وenum وثابت تذكره هذه الوثائق.

المحتويات​

نموذج الفهرسة​

كل نمط إطلاق يربط هويته بعنوان fundManager، وهو معامل مفهرس (indexed) على كل حدث في دورة الحياة، فيمكنك تصفية كامل تاريخ بيع واحد بموضوع (topic) واحد. أحداث الإنشاء (PoolCreated، MicroSaleCreated، BondingCurvePoolCreated) تحمل أيضًا token، فيمكنك بناء خريطة البيع-إلى-التوكن من حدث الإنشاء وحده.

تُطبَّق indexed على fundManager وuser في أحداث دورة الحياة؛ أما index الرقمي فليس مفهرسًا على أحداث الصفقة/الإنهاء، لذا صفِّ وادمج على fundManager.

الأحداث الأهمّ لخلاصة الإدراجات:

  • PoolCreated / MicroSaleCreated / BondingCurvePoolCreated: أُنشئ بيع (وبالنسبة لـ microsale أو Melt Pool، سُكّ توكن).
  • Finalized / MicroSaleFinalized / BondingCurveFinalized: أُدرِج التوكن على DEX وبدأ التداول.

أحداث الـ Pool​

تصدرها مسارات presale وfair launch وsubscription.

event PoolCreated(uint256 index, address indexed fundManager, address owner, address token, uint256 timestamp);

event Contributed(uint256 index, address indexed fundManager, address indexed user, uint256 amount, uint256 timestamp);

event Claimed(
    uint256 index,
    address indexed fundManager,
    address indexed user,
    uint256 claimed,
    uint256 totalPurchased,
    uint256 timestamp
);

event ExcessiveRefunded(
    uint256 index,
    address indexed fundManager,
    address indexed user,
    uint256 amount,
    uint256 total,
    uint256 timestamp
);

event WithdrawContribution(uint256 index, address indexed fundManager, address indexed user, uint256 amount, uint256 timestamp);

event EmergencyWithdrawContribution(uint256 index, address indexed fundManager, address indexed user, uint256 amount, uint256 timestamp);

event Finalized(uint256 index, address indexed fundManager, uint256 timestamp);
event Cancelled(uint256 index, address indexed fundManager, uint256 timestamp);
event PoolUpdated(uint256 index, address indexed fundManager, uint256 timestamp);

// whitelist
event WhitelistRootUpdated(address indexed fundManager, bytes32 root, uint256 timestamp);
event WhitelistTierAdded(address indexed fundManager, uint256 tier, uint256 startTime, uint256 duration, uint256 timestamp);
event WhitelistTierUpdated(address indexed fundManager, uint256 tier, uint256 startTime, uint256 duration, uint256 timestamp);

// subscription allocation
event AllocationSubmitted(uint256 indexed poolIndex, address indexed fundManager, bytes32 allocationRoot, uint256 totalVolumePurchased);
event AllocationApproved(uint256 indexed poolIndex, address indexed fundManager);
event AllocationRevoked(uint256 indexed index, address indexed fundManager);

ملاحظة: Finalized وCancelled تخصّان الـ pools. أما الـ microsales فتُصدر MicroSaleFinalized و MicroSaleCancelled بدلًا منهما. في أحداث مخصصات subscription، يكون poolIndex مفهرسًا (على عكس index الرقمي في أحداث دورة الحياة).

أحداث الـ Microsale​

كل أحداث دورة الحياة مُعلَنة بهذه التواقيع. المعاملات indexed هي مواضيع (topics) قابلة للتصفية.

event MicroSaleCreated(
    uint256 indexed index,
    address indexed fundManager,
    address indexed owner,
    address token,
    uint256 configId,
    uint256 timestamp
);

event MicroSaleContributed(
    uint256 index,
    address indexed fundManager,
    address indexed user,
    uint256 amount,
    uint256 timestamp
);

event MicroSaleFinalized(uint256 index, address indexed fundManager, uint256 timestamp);

event MicroSaleClaimed(
    uint256 index,
    address indexed fundManager,
    address indexed user,
    uint256 claimed,
    uint256 timestamp
);

event MicroSaleWithdraw(
    uint256 index,
    address indexed fundManager,
    address indexed user,
    uint256 amount,
    uint256 timestamp
);

event MicroSaleEmergencyWithdraw(
    uint256 index,
    address indexed fundManager,
    address indexed user,
    uint256 amount,
    uint256 timestamp
);

event MicroSaleCancelled(uint256 index, address indexed fundManager, uint256 timestamp);

event MicroSaleUpdated(uint256 indexed index, address indexed fundManager, uint256 timestamp);

ملاحظة: الـ microsales تُصدر MicroSaleFinalized. أما حدث Finalized العام فيخصّ مسار الـ pool الأقدم لـ presale وfair launch، وليس الـ microsales.

أحداث الـ Melt Pool​

يصدرها مسار الـ Melt Pool. يهجّي العقد هذه بـ BondingCurve* — وهو الاسم التقني لمنحنى التسعير الذي يعمل عليه Melt Pool. راجع melt-pool.md.

event BondingCurvePoolCreated(
    uint256 indexed index,
    address indexed fundManager,
    address owner,
    address token,
    address quoteToken,
    uint256 timestamp
);

// one per buy and per sell
event BondingCurveTraded(
    uint256 index,
    address indexed fundManager,
    address indexed user,
    bool    isBuy,
    uint256 quoteAmount,   // BNB in (buy) or out (sell)
    uint256 baseAmount,    // tokens out (buy) or in (sell)
    uint256 reserveBase,   // reserves after the trade
    uint256 reserveQuote,
    uint256 timestamp
);

// the buy that takes the last curve token
event BondingCurveSoldOut(uint256 index, address indexed fundManager, uint256 timestamp);

event BondingCurveFinalized(uint256 index, address indexed fundManager, address pair, uint256 timestamp);

event BondingCurvePoolUpdated(uint256 indexed index, address indexed fundManager, uint256 timestamp);

يحمل BondingCurveTraded الاحتياطيات بعد الصفقة، فيمكنك تتبّع السعر (reserveQuote / reserveBase) والحجم دون قراءة لاحقة. يُطلَق BondingCurveSoldOut على عملية الشراء التي تستنزف المنحنى، وهي إشارتك إلى أن الـ pool جاهز للتخرج. وهذه لحظة منفصلة عن BondingCurveFinalized، الذي يُطلَق عندما يستدعي شخص ما الإنهاء فعليًا ويُدرَج التوكن، ويحمل pair الخاص بـ DEX. يُطلَق BondingCurvePoolUpdated عندما يعدّل مالك الـ pool البيانات الوصفية.

أحداث الـ Vault​

تصدرها عقود الـ vault، لا الـ launchpad. صفِّها على عنوان الـ vault الذي تحصل عليه من getMicroSaleByFundManager(fundManager).vault.

مشترك بين كل vault مبني على VaultBase:

event Bound(address indexed token);      // fee-receiver wired to its token, once
event RevenueReceived(uint256 amount);   // best-effort signal when the token settles tax

SplitterVault:

event Distributed(uint256 amount);
event Paid(address indexed payee, uint256 amount);
event PayFailed(address indexed payee, uint256 amount); // payee could not receive; kept as owed
event Claimed(address indexed payee, uint256 amount);

GiftVault:

event BeneficiaryBound(address indexed beneficiary, uint256 nonce, bool viaRelayer);
event Distributed(uint256 amount);
event Paid(address indexed to, uint256 amount);
event PayFailed(address indexed to, uint256 amount);
event Claimed(address indexed to, uint256 amount);
event Locked();
event DividendDistributed(uint256 amount); // timeout fallback fired; vault is now dividend-only

عمليات البحث العكسي​

كل خريطة تحتاجها هي استدعاء عرض (view). الـ pools والـ microsales لها دوال حصول متوازية.

// microsales
await launchpad.getMicroSaleByFundManager(fundManager);
await launchpad.getMicroSaleByToken(token);   // 1:1
await launchpad.getMicroSaleByVault(vault);   // vault launches
await launchpad.getMicroSale(index);
await launchpad.getMicroSalesCount();

// pools
await launchpad.getPoolByFundManager(fundManager); // confirm result.fundManager === fundManager
await launchpad.getPoolByIndex(index);
await launchpad.getPoolCount();

// melt pools
await launchpad.getBondingCurvePoolByFundManager(fundManager); // confirm result.fundManager === fundManager
await launchpad.getBondingCurvePool(index);
await launchpad.getBondingCurvePoolsCount();

استدعاء getPoolByFundManager (ونظيره في Melt Pool) لعنوان غير معروف يُرجع الـ pool 0 بدلًا من فشل التنفيذ، لذا تحقق من result.fundManager === fundManager قبل الوثوق به. من MicroSale أو Pool أو BondingCurvePool تملك بالفعل token وfundManager وowner، لذا فإن معظم عمليات الدمج لا تحتاج استدعاءً ثانيًا. الـ Melt Pools ليس لها دالة حصول بالتوكن، لكن عنوان التوكن حقل في البنية.

بنى البيانات​

Pool​

تُعيدها دوال العرض getPool*. أي الحقول ذات معنى يعتمد على نوع الـ pool (fair launch يترك rate و hardCap عند صفر؛ وsubscription يستخدم softCapTokens بدلًا من softCap).

struct Pool {
    uint256 index;
    PoolTypeIndex poolType;
    address owner;
    address token;
    address currency;              // address(0) = native (BNB)
    address fundManager;           // the sale handle
    address router;                // address(0) for a manual-listing pool
    uint256 startTime;
    uint256 endTime;
    uint256 publicSaleStartTime;   // whitelist window ends here
    uint256 whitelistTierCount;
    uint256 minContribution;
    uint256 maxContribution;
    uint256 softCap;               // currency; presale + fair launch
    uint256 hardCap;               // currency; presale
    uint256 softCapTokens;         // tokens; subscription
    uint256 totalSellingTokens;    // fair launch + subscription
    uint256 hardCapTokensPerUser;  // subscription
    uint256 rate;                  // tokens per currency unit; presale + subscription
    uint256 listingRate;
    uint256 lockDuration;          // LP lock seconds; 0 = burn
    uint256 listingPercent;        // percent of the raise into liquidity
    uint256 buybackPercent;
    uint256 affiliateBps;
    RefundType refundType;         // Refund | Burn (unsold tokens)
    State state;                   // Active | Finalized | Cancelled
    uint256 listedAt;
    uint256 claimTime;
    uint256 totalRaised;
    uint256 totalCommitted;        // subscription commitments before allocation
    uint256 totalVolumePurchased;  // tokens sold / allocated
    int256  lockId;                // locker id when locked, else -1
    string  poolDetails;
    string  kycDetails;
    bytes32 whitelistRoot;         // 0 = no whitelist
    bytes32 allocationRoot;        // subscription / overflow allocation
    bytes32 noAllocationRoot;      // overflow non-allocated refunds
    uint256 tgePercent;            // vesting: released at claim start
    uint256 cyclePercent;          // vesting: released per cycle
    uint256 cycle;                 // vesting: cycle length in seconds
    bool    requireContributorValidation; // contributions need a platform signature
}

دالة getContributionInfosByFundManager المُقسَّمة إلى صفحات تُرجع ContributionInfoResponse، وهي ContributionInfo مع إضافة عنوان user في المقدمة:

struct ContributionInfoResponse {
    address user;
    uint256 contribution;
    uint256 purchased;
    uint256 claimed;
    uint256 excessiveRefunded;
}

MicroSale​

تُعيدها كل دالة عرض getMicroSale*.

struct MicroSale {
    uint256 index;                 // creation index
    MicroSaleTypeIndex microSaleType;
    address owner;                 // creator
    address token;                 // minted token
    address currency;              // raise currency; address(0) = native (BNB)
    address fundManager;           // the sale handle
    address router;                // DEX router used at finalize
    uint256 startTime;
    uint256 endTime;
    uint256 hardCap;               // in the raise currency
    uint256 totalSellingTokens;    // presale allocation
    uint256 rate;                  // presale rate; purchased = amount * rate / 1e18
    uint256 listingRate;           // opening DEX price basis
    State state;                   // Active | Finalized | Cancelled
    uint256 filledAt;              // when the hard cap filled (0 if not)
    uint256 listedAt;              // when finalized (0 if not)
    uint256 totalRaised;
    uint256 totalVolumePurchased;  // total tokens sold
    uint256 configId;              // template it launched from
    string  poolDetails;           // free-form metadata
    string  kycDetails;            // platform-set KYC metadata
    uint256 maxContribution;       // per-wallet cap; 0 = unlimited
    uint256 lockDuration;          // LP lock seconds; 0 = LP burned
    int256  lockId;                // locker id when locked, else -1
    address vault;                 // attached vault, or address(0)
    address vaultFactory;          // factory that made the vault, or address(0)
}

MicroSaleConfig​

تُعيدها getMicroSaleConfig ودوال الإعدادات النشطة.

struct MicroSaleConfig {
    uint256 configId;
    uint256 presaleTokens;   // tokens sold in the presale
    uint256 lpTokens;        // tokens paired into liquidity
    uint256 hardCap;         // in the template's raise currency
    uint256 duration;        // sale length in seconds
    uint256 buyTaxBps;       // template buy tax (used by templated tax tokens)
    uint256 sellTaxBps;      // template sell tax
    uint256 taxDuration;     // template tax lifetime
    bool    active;
}

presaleTokens + lpTokens تساوي دائمًا إجمالي العرض الثابت البالغ 1,000,000,000 توكن.

ContributionInfo​

سجلّ كل مستخدم، مشترك بين الـ pools والـ microsales. تُعيده getContributionInfo (للـ pools) و getMicroSaleContribution (للـ microsales) كاملًا؛ أما استجابة الـ microsale المُقسَّمة إلى صفحات فتُسقِط excessiveRefunded.

struct ContributionInfo {
    uint256 contribution;      // amount put in, in the raise currency
    uint256 purchased;         // tokens allocated
    uint256 claimed;           // tokens claimed so far
    uint256 excessiveRefunded; // subscription / overflow refund; unused by microsales
}

// paginated microsale response shape
struct MicroSaleContributionInfoResponse {
    address user;
    uint256 contribution;
    uint256 purchased;
    uint256 claimed;
}

WhitelistTier​

تُعيدها getWhitelistTiers(fundManager) لـ pool.

struct WhitelistTier {
    uint256 tier;        // 1-indexed
    uint256 startTime;   // when the tier opens
    uint256 duration;    // seconds the tier stays open; 0 = single open-ended tier
    string  description;
}

BondingCurvePool​

تُعيدها getBondingCurvePool(index) وgetBondingCurvePoolByFundManager(fundManager).

struct BondingCurvePool {
    uint256 index;
    address owner;
    address token;
    address quoteToken;       // address(0) = native (BNB); otherwise an allowed ERC20 quote token
    address fundManager;      // the pool handle
    address router;
    uint256 initialBase;      // virtual base reserve seed
    uint256 initialQuote;     // virtual quote reserve seed
    uint256 totalSellingBase; // tokens sellable before graduation
    uint256 reserveBase;      // current base reserve
    uint256 reserveQuote;     // current quote reserve
    CurveState state;         // Active | Finalized
    uint256 listedAt;         // graduation timestamp, 0 until finalized
    uint8   tokenType;        // 0 = no-tax (CheeseToken), 4 = tax (CheeseTaxTokenV2)
    address vault;            // attached vault, or address(0)
    address vaultFactory;     // factory that made the vault, or address(0)
    string  poolDetails;      // free-form metadata
}

السعر هو reserveQuote / reserveBase. "نافد" (متخرج) يعني reserveBase == initialBase - totalSellingBase؛ وهو مشتق من الاحتياطيات، وليس مخزَّنًا كحالة.

BondingCurveConfig​

قالب منحنى المنصة لعملة تسعير معيّنة، تُعيده getBondingCurveConfig(quoteToken).

struct BondingCurveConfig {
    bool    active;           // curves cannot be created against an inactive config
    uint256 initialBase;      // virtual base reserve seed
    uint256 initialQuote;     // virtual quote reserve seed
    uint256 totalSellingBase; // tokens sellable before graduation
}

TaxConfig​

تُمرَّر داخل بنية CreateParamsV2 لإطلاقات التوكن الضريبي CheeseTaxTokenV2. تحكم ضريبة التوكن والمكان الذي تذهب إليه الضريبة. تأخذ استدعاءات إنشاء التوكن الضريبي أيضًا dexKey أخيرًا (الـ DEX المُراد الإدراج عليه) إلى جانب المعاملات.

struct TaxAllocation {   // BPS; the four must sum to 10000
    uint16 feeReceiver;  // to the fee receiver (wallet or vault)
    uint16 holders;      // to holders as dividends
    uint16 burn;         // to the dead address
    uint16 liquidity;    // added back as LP
}

struct TaxConfig {
    uint256 buyTaxBps;          // <= 1000 (10%)
    uint256 sellTaxBps;         // <= 1000 (10%); buyTaxBps + sellTaxBps must be > 0
    uint256 taxDuration;        // seconds after listing that tax applies; must be > 0
    uint256 antiFarmerDuration; // seconds of the anti-farmer window; <= taxDuration
    TaxAllocation allocation;   // must sum to 10000
    address feeReceiver;        // wallet path only; vault path binds the vault instead
    address quoteToken;         // 0 fills from the template binding (WETH or an allowed ERC20 quote token)
    uint256 minHolderShare;     // required > 0 only if allocation.holders > 0
    // Anti-farmer venue prediction — filled by the launchpad from the chosen DEX, not
    // by the caller. Leave at zero defaults.
    address  v3Factory;
    bytes32  v2PairInitCodeHash;
    bytes32  v3PoolInitCodeHash;
    uint24[] v3FeeTiers;
}

فوق ضريبة المُنشئ هذه، تأخذ CheesePad رسوم منصة إضافية بنسبة 10% على الضريبة (مرحلة المنحنى وبعد الإدراج)؛ راجع tokens.md#the-fee-model.

Platform config​

تُعيد getMasterConfig() الإعدادات على مستوى المنصة.

struct LaunchpadMasterConfig {
    address feeTo;                  // platform fee + creation fee sink
    address locker;                 // LP locker for locked-liquidity sales
    address affiliateProgram;
    address buybackManager;
    address verificationWallet;
    uint256 creationFee;            // pool creation fee (not microsale)
    uint128 nativeFeePercent;
    uint256 maxAffiliateBps;
    uint256 fairLaunchMaxDuration;
    uint256 totalParticipants;
    address cheeseTokenHelper;      // shared swap/liquidity helper for tax tokens
    address platformRole;           // vault emergency-rescue backstop
    address giftRelayerSigner;      // EIP-712 attestor for GiftVault identity binds
    uint256 microSaleCreationFee;   // flat native fee to create a microsale
    address swapRouter;             // shared upgradeable router for CheeseTaxTokenV2 processors
    uint16  platformCutPreBps;      // platform fee on curve-phase creator tax (BPS)
    uint16  platformCutPostBps;     // platform fee on post-listing creator tax (BPS)
}

platformCutPreBps / platformCutPostBps هما رسوم المنصة على ضريبة مُنشئ التوكن الضريبي أثناء مرحلة المنحنى وبعد الإدراج؛ اقرأهما مباشرةً بـ getPlatformCutBps(). راجع tokens.md#the-fee-model.

LaunchDataV1​

ما تستلمه دالة _reviewV1 الخاصة بمصنع الـ vault عند فحص إطلاق. إنها معاملات الإطلاق، دون vaultData الخاصة بكل vault.

struct LaunchDataV1 {
    uint256 configId;
    address quoteToken;
    uint256 buyTaxBps;
    uint256 sellTaxBps;
    uint256 taxDuration;
    uint16  feeReceiverBps;
    uint16  holdersBps;
    uint16  burnBps;
    uint16  liquidityBps;
    uint256 minDispatch;
    uint256 minHolderShare;
    address creator;
}

Vault schema types​

تستخدمها vaultDataSchema() (نموذج الإنشاء) وvaultUISchema() (الإجراءات والحالة القابلة للقراءة). تعرض واجهة المستخدم أي vault من هذه دون كود خاص بالـ vault.

enum FieldType {
    String, Address, Uint16, Uint256, Uint128, Bool, Bytes, Bytes32, Time, MsgValue
}

struct Field {
    string    name;
    FieldType fieldType;
    bool      isArray;
    uint8     decimals;  // UI multiplies inputs / divides outputs by 10^decimals
    string    hint;
}

struct VaultDataSchema {  // how to encode vaultData for createVault
    string  description;
    bool    isArray;      // true => vaultData is a tuple[]; false => a single tuple
    Field[] fields;
}

struct ApprovalHint {     // an ERC20 approval a UI must prompt before a write
    string tokenRef;      // "token", "quoteToken", or a 0x address literal
    string amountField;   // input field holding the amount; "*" = max approval
}

struct Method {
    string         name;
    bytes4         selector;
    bool           isWrite;    // true = tx button; false = read field
    Field[]        inputs;
    Field[]        outputs;
    ApprovalHint[] approvals;
    string         hint;
}

struct VaultUISchema {
    string   vaultType;
    string   description;
    Method[] methods;
}

ملاحظات على الأنواع: Time هو طابع وقت Unix مطلق (والمدة هي مجرد Uint256 من الثواني). MsgValue هو BNB أصلي يُرسَل كـ msg.value مع كتابة، وليس معامل ABI. decimals لا تنطبق على Time أو MsgValue. المُنفِق (spender) لأي ApprovalHint هو دائمًا الـ vault.

الـ Enums​

enum State { Active, Finalized, Cancelled }   // 0, 1, 2; used by pools and microsales

enum PoolTypeIndex {                          // Pool.poolType
    Presale,            // 0
    FairLaunch,         // 1
    Subscription,       // 2
    OverflowPresale,    // 3, not currently creatable
    OverflowFairLaunch  // 4, not currently creatable
}

enum RefundType { Refund, Burn }              // 0, 1; handling of unsold pool tokens

enum SubscriptionCalculationStage {           // getSubscriptionCalculationStage
    notCalculated,      // 0
    needConfirm,        // 1
    calculated          // 2, claiming can open
}

enum MicroSaleTypeIndex { Presale }           // only one type today

enum CurveState { Active, Finalized }         // 0, 1; BondingCurvePool.state (sold-out is derived)

الثوابت والحدود​

ConstantValueWhere
عرض التوكن المسكوك1,000,000,000 (18 decimals)كل توكن microsale وMelt Pool (الـ pools تجلب توكنها الخاص)
سقف الضريبة لكل جانب10% (1000 BPS)التوكن الضريبي عند الإطلاق
سقف ضريبة القالب لكل جانب5% (500 BPS)قالب إعدادات microsale
أساس التوزيع10000 BPSيجب أن يساوي مجموع توزيع الضريبة هذا
رسوم المنصة عند الإنهاء5% (microsale) / nativeFeePercent (pool)finalize
رسم صفقة Melt Pool1% (100 BPS) لكل صفقةكل شراء وبيع على المنحنى
رسم السحب الطارئ10% من المساهمةالسحب الطارئ
حدّ السحب الطارئآخر 15 دقيقة قبل النهايةالسحب الطارئ
نسبة إدراج الـ pool20 إلى 100إنشاء pool
قاعدة السقف الأدنى لـ presalesoftCap * 4 >= hardCap وsoftCap < hardCapإنشاء presale
الحد الأدنى لقفل السيولة30 يومًا (pool) / 365 يومًا (microsale)؛ 5 دقائق على BNB testnet فقطالإنهاء مع قفل
الحد الأقصى لقفل السيولة10 سنواتإنشاء microsale
سيولة Melt Poolتُحرق السيولة عند التخرج (دائم)إنهاء Melt Pool
الحد الأقصى لمستفيدي SplitterVault50SplitterVault
نافذة ربط GiftVault1 إلى 365 يومًاإطلاق GiftVault