تحریریں
ERC-20 vesting contracts کے لیے سیکیورٹی چیک لسٹ
محفوظ ERC-20 vesting contracts کے لیے vesting کا حساب، revocation، admin keys، token transfers، Foundry invariant tests اور deployment چیکس۔
sigmacode.io انجینئرنگ ٹیم9 منٹ کی قراءت
اس صفحے پر (14)
- 1. Vesting کا حساب
- 2. Beneficiaries اور revocation
- 3. Access control اور admin keys
- 4. Token transfer کی handling
- 5. Reentrancy اور call کی ترتیب
- 6. Timestamps
- 7. Events اور شفافیت
- 8. Upgradeability کے فائدے اور نقصانات
- 9. Emergency controls
- 10. Testing
- 11. Static analysis
- 12. Deployment اور verification
- 13. Operational چیکس
- آخری بات
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:
// 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 کرنے کے بجائےfalsereturn کرتے ہیں۔ - 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
recoverERC20function کے ذریعے 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 کرنے کی کوئی وجہ نہیں۔
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 contract | beneficiaries کے لیے مضبوط ترین ضمانت، آسان audit | Bugs fix نہیں ہو سکتیں؛ migration کو نیا contract اور فنڈز درکار |
| Upgradeable proxy | Bugs 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 کریں کہvestedAmountmonotonic ہے اور کبھی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 کبھی نہیں بڑھتا۔
// 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 پر توجہ دیں۔
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 کرتے ہوئے خوشی ہوگی: بس رابطہ کریں۔