מפרט טכני לפרויקטים של בלוקצ'יין: מדריך מלא

כאשר משיקים פרוטוקול DeFi, ביקורת חושפת לעיתים קרובות בעיות ריאנטרנסי (reentrancy), מה שמאלץ שכתוב דחוף של הלוגיקה. ללא מפרט טכני ברור, כל ספרינט הופך לכאוס: מפתחים משנים פונקציות, ובודקים לא יכולים לכסות תרחישים חדשים. לפי סטטיסטיקות, 60% מפרויקטי הבלוקצ'יין מתמודדים עם ריאנטרנסי בגלל היעדר מפרט. מפרט עוזר לצפות התקפות כאלה בשלב התכנון. עברנו על 50+ פרויקטי בלוקצ'יין ואנחנו יודעים: מפרט טכני איכותי הוא הבסיס לאמינות המוצר.

למה מפרט רגיל לא עובד עבור בלוקצ'יין?

מפרטים מסורתיים מיועדים למערכות מרכזיות שבהן ניתן לתקן באגים באמצעות תיקון שרת. בבלוקצ'יין, לאחר פריסת חוזה, ניתן לשנות לוגיקה רק באמצעות אסטרטגיית שדרוג — הדורשת ארכיטקטורת פרוקסי מתוכננת בקפידה. לדוגמה, UUPS proxy, המתואר בתיעוד חוזה חכם של OpenZeppelin, מאפשר שדרוגי חוזים באמצעות timelock. בנוסף, כל פעולה עולה גז: קריאה לא אופטימלית יכולה לעלות $50 בשעות שיא. שגיאה בחישובי עמלות הופכת את המוצר ללא רווחי. ראינו פרויקטים שבהם חוזים חכמים נאלצו להיכתב מחדש מאפס כי המפרט לא כלל מפרטי תפקידי גישה או לא התחשב בהתקפות flash loan.

אילו סעיפים צריך מפרט טכני של פרויקט בלוקצ'יין להכיל?

סקירת מערכת

• מטרת הפרויקט ובעלי העניין המרכזיים.
• הבלוקצ'יין הנבחר (L1/L2) וההצדקה: Ethereum, Polygon, Arbitrum או Solana.
• ארכיטקטורה ברמה גבוהה עם דיאגרמה — אינטראקציה של חוזים, רכיבי off-chain.
• אינטגרציות: אורקלים (Chainlink), גשר, פרוטוקולים חיצוניים.

איך לתאר חוזים חכמים במפרט?

כל חוזה צריך תיאור מפורט: חתימות פונקציות עם פרמטרים, אירועים שנפלטים, תפקידי גישה (AccessControl), פרמטרים הניתנים להגדרה. חשוב לציין תקנים (ERC-20, ERC-721, ERC-1155, ERC-4626) וסוג פרוקסי. הנה דוגמה לחוזה מאגר נזילות:

Contract: LiquidityPool
Сеть: Arbitrum One
Стандарты: ERC-20 compatible
Апгрейдаемость: UUPS proxy
Функции:
  - deposit(uint256 amount) — депозит токенов, mint LP shares
  - withdraw(uint256 shares) — burn LP shares, получить токены + accumulated fees
  - swap(address tokenIn, uint256 amountIn, uint256 minAmountOut) — обмен
События (Events):
  - Deposit(address indexed user, uint256 amount, uint256 shares)
  - Withdraw(address indexed user, uint256 shares, uint256 amount)
  - Swap(address indexed user, address tokenIn, uint256 amountIn, uint256 amountOut)
Роли (Access Control):
  - DEFAULT_ADMIN_ROLE: Gnosis Safe 3/5
  - PAUSE_ROLE: Protocol Defender (multisig или automated)
  - FEE_MANAGER_ROLE: DAO timelock
Параметры (configurable):
  - swapFee: 0.3% (range: 0.01%-1%)
  - protocolFeeShare: 20% от swap fee

דוגמה למפרט חוזה מאגר נזילות: למעלה תבנית מלאה — מלאו אותה עבור כל חוזה. ציינו תקציב גז: לדוגמה, מקסימום גז להפקדה = 200k גז. זה מונע עלויות בלתי צפויות לאחר הפריסה.

מפרט טוקן (אם קיים)

Token: PROTO
Standard: ERC-20 + ERC-2612 (Permit)
Supply: 100,000,000 (fixed)
Decimals: 18
Mintable: нет (fixed supply)
Burnable: да (holder может сжечь)
Pausable: да (PAUSE_ROLE)
Distributor: специальный Vesting контракт

רכיבי Off-Chain

• אינדקסר (The Graph subgraph) — אילו אירועים מתועדים, סכמת GraphQL.
• API backend (אם נדרש) — נקודות קצה, אימות.
• Frontend — מחסן טכנולוגי, אינטגרציית ארנק (wagmi, RainbowKit).

תשתית

Деплой:
- Foundry Deploy Scripts + Hardhat для верификации
- Multisig owner: Gnosis Safe 3/5
- Timelock: 48 часов для admin функций
- Proxy: UUPS (implementation upgrade через timelock)
Мониторинг:
- OpenZeppelin Defender для alerts
- Tenderly для транзакций simulation
- The Graph для исторических данных
Сети для деплоя:
- Testnet: Arbitrum Sepolia
- Mainnet: Arbitrum One

אבטחה

• רשימת תבניות חוזים חכמים: Reentrancy guard, CEI, בדיקות למניפולציית אורקל.
• הגנה מפני התקפות flash loan: בדיקת יתרת המאגר לפני ואחרי החלפה.
• תוכנית בקרת גישה: כל תפקיד מקושר לכתובת ספציפית (EOA, multisig, DAO).
• אסטרטגיית שדרוג עם timelock: תהליך ייזום וחזרה לאחור.

בדיקות

בדיקות יחידה (Foundry):

• כל הפונקציות הציבוריות.
• מקרי קצה ותנאי גבול.
• תרחישי revert.

בדיקות Fuzz:

• אינווריאנטים: "totalShares * pricePerShare = totalAssets".
• רצפי הפקדה/משיכה אקראיים.

בדיקות Fork:

• אינטגרציה עם פרוטוקולים אמיתיים על mainnet משוכפל.

יעד כיסוי: 95%+.

תוכנית ביקורת

• היקף הביקורת: אילו חוזים נבדקים.
• ציר זמן: ביקורת לאחר הקפאת קוד, לפני mainnet.
• קריטריונים למוכנות: כל הממצאים ברמת בינוני ומעלה תוקנו.

איך לחסוך בגז עם המפרט?

תקציב גז מוגדר בבירור במפרט מאלץ מפתחים לייעל קוד מההתחלה. לדוגמה, מגבלה של 200k גז להפקדה דורשת תבניות חסכוניות באחסון. לפי הנתונים שלנו, גישה זו חוסכת עד $20,000 בשנה בעלויות עסקאות. בנוסף, אסטרטגיית שדרוג נכונה מפחיתה עלויות עדכון: פרויקט עם UUPS ו-timelock מתעדכן תוך 48 שעות עם סיכונים מינימליים — פי 7 מהר יותר מאשר פריסה מחדש של כל החוזה.

טעויות נפוצות במפרטים טכניים ואיך להימנע מהן

חוסר במפרט תפקידים. "רק הבעלים יכול לקרוא לפונקציה זו" — אבל האם הבעלים הוא EOA, multisig או DAO? במפרט, ציינו כתובות או תפקידים ספציפיים. הניסיון שלנו מראה שעד 90% מהתקפות הריאנטרנסי מתרחשות עקב חלוקת הרשאות שגויה.

אין אסטרטגיית שדרוג. מפתחים מחליטים תוך כדי תנועה — סיכון לפתרונות לא תואמים. השוואה: פרויקט ללא אסטרטגיית שדרוג, כאשר מתרחשת שגיאה, דורש פריסה מלאה מחדש, מה שמוביל לאובדן נזילות ואמון. פרויקט עם UUPS ו-timelock מתעדכן תוך 48 שעות עם סיכונים מינימליים.

אין תקציב גז יעד. החוזה נכתב, ואז מתברר שכל קריאה עולה $50 בגז. ציינו תקציב במפרט: לדוגמה, מקסימום גז להפקדה = 200k גז (עבור Solidity 0.8.20). זה יכול לחסוך עד $20,000 בשנה בעסקאות. היעדר מפרט מוביל גם לעלויות ביקורת נוספות של $5,000–$10,000.

תרחישי כישלון לא מתוארים. מה קורה אם האורקל לא זמין, אם הצד השני לא מיישם את הממשק? כתבו את כל הנתיבים החלופיים ומנגנוני ההשהיה.

מה כלול בכתיבת מפרט סוהר?

התהליך כולו אורך 1 עד 4 שבועות תלוי במורכבות. לאחר מסירת המפרט, אתם מקבלים מסמך שניתן להעביר לכל צוות פיתוח — הוא מפחית את זמן בדיקת הקוד והביקורת ב-30%. אם אתם זקוקים לעזרה בכתיבת מפרט, צרו קשר.

איך לבנות אסטרטגיית שדרוג: הוראות שלב-אחר-שלב

1. בחרו את סוג הפרוקסי: UUPS, Beacon או Transparent. עבור רוב מוצרי DeFi, UUPS מתאים — הוא זול וגמיש יותר.
2. הגדירו ממשל: multisig Gnosis Safe 3/5 + timelock של 48 שעות.
3. תעדו את נוהל החזרה לאחור: איך לחזור לגרסה הישנה אם החדשה מכילה באג קריטי.

השוואת אסטרטגיות שדרוג:

אנחנו ממליצים על UUPS לחוזים עם עדכונים נדירים. קבלו ייעוץ לפרויקט שלכם — נעזור לכם לבחור את האסטרטגיה האופטימלית.