مواد پر جائیں

تحریریں

ERC-20 vesting contracts کے لیے سیکیورٹی چیک لسٹ

محفوظ ERC-20 vesting contracts کے لیے vesting کا حساب، revocation، admin keys، token transfers، Foundry invariant tests اور deployment چیکس۔

sigmacode.io انجینئرنگ ٹیم9 منٹ کی قراءت

اس صفحے پر (14)
  1. 1. Vesting کا حساب
  2. 2. Beneficiaries اور revocation
  3. 3. Access control اور admin keys
  4. 4. Token transfer کی handling
  5. 5. Reentrancy اور call کی ترتیب
  6. 6. Timestamps
  7. 7. Events اور شفافیت
  8. 8. Upgradeability کے فائدے اور نقصانات
  9. 9. Emergency controls
  10. 10. Testing
  11. 11. Static analysis
  12. 12. Deployment اور verification
  13. 13. Operational چیکس
  14. آخری بات

Vesting contracts بظاہر سادہ لگتے ہیں: tokens کو lock کریں، وقت کے ساتھ release کریں، اور کام ختم۔ عملاً یہ برسوں تک کسی پروجیکٹ کی supply کا بڑا حصہ اپنے اندر رکھتے ہیں، ان کو founders، investors، employees اور multisigs ہاتھ لگاتے ہیں، اور deploy ہونے کے بعد انہیں شاذ و نادر ہی دوبارہ دیکھا جاتا ہے۔ حساب یا permission model میں ایک چھوٹی سی غلطی پورے vesting period کے لیے زندہ رہتی ہے۔ یہ چیک لسٹ وہ سوالات جمع کرتی ہے جو ہم ERC-20 vesting contract کو design یا review کرتے وقت پوچھتے ہیں، حساب سے لے کر deployment اور روزمرہ operations تک۔

1. Vesting کا حساب#

ہر vesting contract کا مرکز ایک function ہے جو اس سوال کا جواب دیتا ہے کہ "وقت t پر کتنے tokens vested ہیں؟"۔ تقریباً ہر سنجیدہ vesting bug یہیں رہتا ہے۔

Linear schedule اور cliff#

  • Schedule کو واضح parameters کے ساتھ define کریں: start، cliff، duration، totalAllocation۔ deployment کے وقت block.timestamp سے اخذ ہونے والی implicit values سے گریز کریں۔
  • طے کریں کہ cliff کا مطلب کیا ہے۔ عام models یہ ہیں: "cliff سے پہلے کچھ نہیں، پھر start سے linear انداز میں catch up" اور "cliff سے پہلے کچھ نہیں، پھر یکمشت رقم، پھر linear"۔ منتخب کردہ model کو NatSpec اور tests میں لکھ لیں۔
  • Creation کے وقت validate کریں: duration صفر سے زیادہ ہو، cliff، start + duration کے بعد نہ ہو، totalAllocation صفر سے زیادہ ہو، اور beneficiary zero address نہ ہو۔
  • start + duration کے بعد vested رقم بالکل totalAllocation کے برابر ہونی چاہیے، "تقریباً" نہیں۔

Rounding#

  • تقسیم سے پہلے ضرب دیں۔ total * elapsed / duration درست ہے؛ total / duration * elapsed ہر release پر خاموشی سے tokens کھو دیتا ہے۔
  • Rounding ہمیشہ contract کے حق میں ہونی چاہیے: beneficiary جو کچھ claim کر سکتا ہے اسے نیچے round کریں، کبھی اوپر نہیں۔ schedule کے آخر میں آخری release باقی بچی ہوئی dust نکال لیتی ہے۔
  • 18-decimal tokens کے ساتھ بڑی allocations پر overflow چیک کریں۔ Solidity 0.8.x overflow پر revert کرتی ہے، لیکن vestedAmount کے اندر ایک revert ہر claim کو lock کر سکتا ہے۔ اگر حاصلِ ضرب بڑا ہو سکتا ہے تو OpenZeppelin کا Math.mulDiv استعمال کریں۔

ماضی یا مستقبل میں start#

  • ماضی میں start جائز ہے (backdated employee grants) لیکن اس کا مطلب ہے کہ بڑی رقم فوراً claim کی جا سکتی ہے۔ اسے ایک واضح، reviewed فیصلہ بنائیں، نہ کہ کسی غلط parameter کا اتفاقی نتیجہ۔
  • دور مستقبل میں start کسی typo کا نتیجہ ہو سکتا ہے (seconds کے بجائے milliseconds ایک کلاسیکی مثال ہے)۔ constructor یا factory اور deployment script میں sanity bounds لگائیں۔

Schedule کا ایک مختصر reference implementation:

solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";

function vestedAmount(
    uint256 total,
    uint64 start,
    uint64 cliff,
    uint64 duration,
    uint64 timestamp
) pure returns (uint256) {
    if (timestamp < cliff) return 0;
    if (timestamp >= start + duration) return total;
    // Multiply before divide; mulDiv avoids intermediate overflow.
    return Math.mulDiv(total, timestamp - start, duration);
}

2. Beneficiaries اور revocation#

  • کون claim کر سکتا ہے؟ صرف beneficiary، یا beneficiary کی طرف سے کوئی بھی؟ جب تک tokens ہمیشہ beneficiary کو ہی جائیں، کسی کو بھی release() trigger کرنے دینا ٹھیک ہے؛ یہ lost-key recovery اور automation میں مدد دیتا ہے۔
  • کیا beneficiary بدل سکتا ہے؟ اگر ہاں، تو اس کا آغاز موجودہ beneficiary سے کروائیں (مثالی طور پر acceptance کے ساتھ two-step transfer)، اور ایک event emit کریں۔ ایسا beneficiary جو خود contract ہو، tokens وصول اور استعمال کر سکتا ہو۔
  • Revocation model. فی schedule طے کریں کہ وہ revocable ہے یا نہیں۔ Revocation پر، پہلے سے vested مگر اب تک unreleased رقم beneficiary کے لیے claimable رہنی چاہیے؛ صرف unvested باقی رقم treasury کو واپس جائے۔ vested tokens کو revoke کرنا صرف code کا نہیں بلکہ اعتماد کا مسئلہ ہے۔
  • Revocation حتمی ہونی چاہیے۔ revoked schedule کو دوبارہ revoke نہیں ہونا چاہیے، vesting جاری نہیں رکھنی چاہیے، اور admin کو unvested باقی رقم سے زیادہ withdraw کرنے کی اجازت نہیں ہونی چاہیے۔
  • فی beneficiary متعدد schedules. schedules کو صرف address کے بجائے کسی id سے key کریں، تاکہ دوسری grant پہلی کو overwrite نہ کرے۔

3. Access control اور admin keys#

  • ہر privileged function کی فہرست بنائیں: schedules بنانا، revoke کرنا، pause کرنا، surplus نکالنا، upgrade کرنا۔ اگر key compromise ہو جائے تو ہر ایک ایک attack surface ہے۔
  • ایک سب کچھ کرنے والے واحد owner کے بجائے Ownable2Step یا AccessControl کو الگ الگ roles کے ساتھ استعمال کریں۔ schedules بنانے والے role کو فنڈز نکالنے والا role ہونا ضروری نہیں۔
  • admin roles کو multisig میں رکھیں، اور ایسی ہر چیز کے لیے timelock پر غور کریں جو tokens کو contract سے باہر منتقل کرے۔
  • admin کو کبھی بھی ایسے tokens نکالنے کی اجازت نہیں ہونی چاہیے جو schedules کے لیے committed ہیں۔ totalCommitted کو track کریں اور surplus کے لیے صرف balance - totalCommitted کی withdrawal کی اجازت دیں۔
  • آخری حالت کی منصوبہ بندی کریں: کیا تمام schedules بننے کے بعد admin rights renounce کیے جا سکتے ہیں؟ زندہ keys کم ہونے کا مطلب کم failure modes ہیں۔

4. Token transfer کی handling#

  • ہر transfer کے لیے OpenZeppelin SafeERC20 استعمال کریں۔ کچھ tokens boolean return نہیں کرتے، دوسرے revert کرنے کے بجائے false return کرتے ہیں۔
  • Fee-on-transfer tokens. اگر contract کو ایسے token سے fund کیا جائے جو fee لیتا ہے، تو اسے nominal رقم سے کم ملتا ہے۔ funding سے پہلے اور بعد میں balance ناپیں اور دراصل آئی ہوئی رقم ریکارڈ کریں، یا ایسے tokens کو واضح طور پر مسترد کر دیں۔
  • Rebasing tokens. جو balances خود سے بدلتے ہیں وہ balance == committed + surplus کے مفروضے کو توڑ دیتے ہیں۔ یا تو document کریں کہ rebasing tokens supported نہیں ہیں، یا accounting کو shares میں design کریں۔
  • اگر contract ایک ہی token کے لیے ہے تو token address کو immutable کے طور پر pin کریں۔ فی schedule arbitrary token addresses قبول کرنا attack surface کو نمایاں طور پر بڑھا دیتا ہے۔
  • کسی generic recoverERC20 function کے ذریعے vested token کو committed رقمیں منہا کیے بغیر "rescue" ہونے کی اجازت کبھی نہ دیں۔

5. Reentrancy اور call کی ترتیب#

  • checks-effects-interactions کی پیروی کریں: safeTransfer کو call کرنے سے پہلے released کو update کریں۔
  • release، revoke اور ہر withdrawal function پر nonReentrant لگائیں۔ ERC-777 طرز کے hooks یا کوئی malicious token contract کو دوبارہ call کر سکتے ہیں۔
  • external calls کو کم از کم رکھیں۔ کسی vesting contract کو arbitrary addresses کو call کرنے کی کوئی وجہ نہیں۔
solidity
function release(uint256 scheduleId) external nonReentrant {
    Schedule storage s = schedules[scheduleId];
    uint256 amount = _releasable(s);
    require(amount > 0, "Vesting: nothing to release");

    s.released += amount;          // effects first
    totalCommitted -= amount;

    token.safeTransfer(s.beneficiary, amount); // interaction last
    emit TokensReleased(scheduleId, s.beneficiary, amount);
}

6. Timestamps#

  • block.timestamp استعمال کریں، block numbers نہیں۔ Block times مختلف chains میں مختلف ہوتے ہیں اور وقت کے ساتھ بدلتے ہیں؛ وہی contract بعد میں کسی L2 پر بھی deploy ہو سکتا ہے۔
  • timestamps پر validators کا اثر چند seconds تک محدود ہے۔ مہینوں میں ناپے جانے والے schedules کے لیے یہ بے معنی ہے، لیکن ایسا logic نہ بنائیں جو second-level precision پر منحصر ہو۔
  • timestamps کو uint64 میں store کریں۔ یہ کسی بھی حقیقی schedule کے لیے کافی ہے اور storage میں اچھی طرح pack ہوتا ہے۔
  • حدود کو واضح طور پر test کریں: cliff سے ایک second پہلے، بالکل cliff پر، بالکل آخر میں، اور آخر کے کافی بعد۔

7. Events اور شفافیت#

ہر state change پر ایک event emit ہونا چاہیے: ScheduleCreated، TokensReleased، ScheduleRevoked، BeneficiaryChanged، role کی تبدیلیاں اور pauses۔ indexers، dashboards اور آپ کی اپنی support team انہی events پر انحصار کرتی ہے۔ صرف addresses نہیں بلکہ schedule id اور رقمیں بھی شامل کریں۔ investors اور employees پوچھیں گے کہ کتنا vested ہے، اور on-chain events اس کا سب سے قابلِ اعتماد جواب ہیں۔

8. Upgradeability کے فائدے اور نقصانات#

آپشنفائدہخطرہ
Immutable contractbeneficiaries کے لیے مضبوط ترین ضمانت، آسان auditBugs fix نہیں ہو سکتیں؛ migration کو نیا contract اور فنڈز درکار
Upgradeable proxyBugs patch ہو سکتے ہیںUpgrade key کوئی بھی rule بدل سکتی ہے، storage layout کی غلطیاں، audit کا بڑا scope
Immutable کے علاوہ factoryہر schedule set الگ تھلگ رہتا ہے، نئی grants کے لیے نئے versionsپرانے instances پرانے bugs برقرار رکھتے ہیں

vesting کے لیے immutability اکثر بہتر default ہے: contract کی پوری وجہ ہی یہ ہے کہ بعد میں کوئی معاہدہ نہ بدل سکے۔ اگر آپ proxy منتخب کریں تو upgrade role کو multisig اور timelock کے پیچھے رکھیں، storage gaps یا namespaced storage استعمال کریں، اور CI میں OpenZeppelin کی upgrade safety checks چلائیں۔

9. Emergency controls#

  • pause کسی نامعلوم bug کے خلاف حفاظت کر سکتا ہے، لیکن ایسا pause جو release کو ہمیشہ کے لیے روک دے، beneficiaries کو freeze کرنے کا ایک طریقہ بھی ہے۔ اس پر غور کریں کہ pause کی مدت محدود ہو، یا نئے schedules کی creation paused ہوتے ہوئے بھی releases کی اجازت ہو۔
  • document کریں کہ کون pause کر سکتا ہے، کن حالات میں، اور community کو کس طرح آگاہ کیا جائے گا۔
  • "emergency میں سب کچھ withdraw کرو" جیسے functions سے گریز کریں۔ اگر کوئی ناگزیر ہو تو وہ timelock کے پیچھے ہونا چاہیے اور اس documentation میں واضح ہونا چاہیے جو investors پڑھتے ہیں۔

10. Testing#

Unit tests کم از کم شرط ہیں۔ vesting contracts کے لیے property-based tests بہت قیمت بڑھاتے ہیں، کیونکہ حساب ہر وقت اور ہر رقم کے لیے قائم رہنا چاہیے۔

  • Unit tests: ہر revert path، ہر boundary timestamp، cliff سے پہلے revocation، مکمل vesting کے بعد revocation، ایک ہی beneficiary کے لیے متعدد schedules۔
  • Fuzz tests: random total، duration اور timestamp؛ یہ assert کریں کہ vestedAmount monotonic ہے اور کبھی total سے زیادہ نہیں ہوتا۔
  • Invariant tests: Foundry کو release، revoke، createSchedule اور vm.warp کو random ترتیب میں call کرنے دیں، پھر global properties چیک کریں۔

مفید invariants:

  • فی schedule released رقموں کا مجموعہ اس کی allocation سے کبھی زیادہ نہیں ہوتا۔
  • contract کا token balance ہمیشہ کم از کم totalCommitted کے برابر ہوتا ہے۔
  • revoked schedule کے بعد اس کا vested amount کبھی نہیں بڑھتا۔
solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {Test} from "forge-std/Test.sol";

contract VestingInvariants is Test {
    VestingHandler handler;

    function setUp() public {
        handler = new VestingHandler(); // deploys token + vesting, exposes bounded actions
        targetContract(address(handler));
    }

    function invariant_releasedNeverExceedsAllocation() public view {
        uint256 n = handler.vesting().scheduleCount();
        for (uint256 i; i < n; i++) {
            (, uint256 total, uint256 released) = handler.vesting().scheduleInfo(i);
            assertLe(released, total);
        }
    }

    function invariant_balanceCoversCommitments() public view {
        assertGe(
            handler.token().balanceOf(address(handler.vesting())),
            handler.vesting().totalCommitted()
        );
    }
}

11. Static analysis#

ہر change پر Slither چلائیں اور اس کے output کو pass/fail signal کے بجائے review queue کے طور پر لیں۔ vesting contracts میں reentrancy findings، unchecked transfers، balances پر خطرناک strict equalities اور missing events پر توجہ دیں۔

bash
slither . --filter-paths "lib|test" --exclude-dependencies
forge test --fuzz-runs 10000
forge coverage --report summary

ایک AI-assisted pre-review، جیسے ہمارا Smart Contract AI Reviewer، ایک اور تیز پہلا مرحلہ ہے جو کسی انسان کے code دیکھنے سے پہلے مشکوک patterns اجاگر کر دیتا ہے۔

12. Deployment اور verification#

  • deployment کو Foundry scripts سے script کریں، manual transactions سے نہیں۔ parameters version-controlled config files میں رہتے ہیں اور code کی طرح review ہوتے ہیں۔
  • پہلے بالکل اسی script اور parameters کے ساتھ testnet پر deploy کریں، پھر mainnet fork پر dry run چلائیں۔
  • deployment کے فوراً بعد block explorer پر source code verify کریں، اسی compiler version اور optimizer settings کے ساتھ۔
  • decimals کی دوبارہ تصدیق کریں: 18 decimals والے 1,000,000 tokens کی allocation 1_000_000e18 ہے، 1_000_000 نہیں۔
  • اسی script میں ownership multisig کو transfer کریں، اور تصدیق کریں کہ deployer key کے پاس کوئی باقی roles نہیں رہتے۔

13. Operational چیکس#

  • باقاعدگی سے reconcile کریں: schedule allocations کا مجموعہ منہا releases، committed رقم اور contract balance سے ملنا چاہیے۔
  • events کی نگرانی کریں اور غیر متوقع revocations، role کی تبدیلیوں یا pauses پر alert کریں۔
  • schedules کا ایک public یا investor-facing جائزہ رکھیں، تاکہ سوالات کا جواب on-chain data سے دیا جا سکے۔
  • اہم procedures کی مشق کریں: multisig signer rotation، اگر کوئی beneficiary اپنے wallet تک رسائی کھو دے تو کیا ہوگا، اور pause کس طرح convey کیا جائے گا۔

آخری بات#

ایک چیک لسٹ اور automated review بہت سے مسائل جلد پکڑ لیتی ہیں، لیکن یہ independent security audit کا بدل نہیں ہیں۔ اس سے پہلے کہ کوئی vesting contract حقیقی مالیت سنبھالے، اسے ایسے لوگوں سے review کرائیں جنہوں نے اسے نہیں لکھا۔

اگر آپ دیکھنا چاہتے ہیں کہ ہم عملاً اسے کیسے کرتے ہیں، تو ہمارا token suite showcase دیکھیں، جس میں tests کے ساتھ ایک vesting contract شامل ہے، یا ہماری blockchain services کے بارے میں مزید پڑھیں۔ ہماری ٹیم کی قیادت 20+ سال کے تجربے رکھنے والا ایک tech lead کر رہا ہے، اور ہمیں آپ کے tokenomics یا vesting design کا review کرتے ہوئے خوشی ہوگی: بس رابطہ کریں۔

کوئی پروجیکٹ ذہن میں ہے؟

ہمیں بتائیں کہ آپ کیا بنا رہے ہیں۔ کام کے دنوں میں ایک سینئر انجینئر ایک گھنٹے کے اندر جواب دیتا ہے — پھر آپ کو دیانتدارانہ جائزہ، واضح دائرۂ کار اور مقررہ قیمت یا سنگ میل پر مبنی تجویز ملتی ہے، عام طور پر چند کام کے دنوں میں۔

پہلے لکھنا پسند کریں گے؟ ہمیں لکھیں

آپ براہِ راست Ing. Ismet Mesic، ٹیک لیڈ سے بات کریں گے۔