תיעוד חוזה חכם (NatSpec)

אנחנו יודעים איך נראה חוזה ללא תיעוד: אינטגרטורים מנחשים מה כל פונקציה עושה, מבקרים מבזבזים 30% יותר זמן, ומשתמשים ב-MetaMask רואים תיאור עסקה ריק. עם ניסיון של למעלה מ-5 שנים בעבודה עם Solidity, הקמנו תהליך ליצירת תיעוד NatSpec מלא עבור פרוטוקולים בכל גודל—מ-ERC-20 פשוט ועד מאגרי נזילות AMM מורכבים. נכון להיום, תיעדנו למעלה מ-50 חוזים, כולל פרוטוקולי DeFi עם לוגיקת תצורה מסיבית.

למה לתעד חוזים?

ללא NatSpec, כל שורת קוד היא חידה. מפתח שמבצע אינטגרציה עם הטוקן שלך שישה חודשים מאוחר יותר לא צריך לשחזר לוגיקה מ-bytecode ומבדיקות. NatSpec מובנה במהדר Solidity: הערות /// ו-/** */ נכנסות אוטומטית ל-ABI ומוצגות ב-MetaMask בעת חתימה על עסקה. זה לא רק פורמליות—זו הגנה מפני פונקציות הונאה ושגיאות משתמש. לפי הסטטיסטיקות שלנו, חוזים מתועדים כראוי מפחיתים קריאות פונקציה שגויות ב-80%.

איך אנחנו מתעדים חוזה

אנחנו עוברים על כל חוזה מתחילתו ועד סופו. עבור כל הפונקציות public ו-external, אירועים ושגיאות מותאמות אישית:

• @notice — תיאור ידידותי למשתמש (מה הפונקציה עושה, למה לקרוא לה, מה יקרה).
• @dev — ניואנסים טכניים: מגבלות גז, תנאי revert, הנחות מצב.
• @param / @return — תיאור מדויק של פרמטרים וערכי החזרה, כולל יחידות (wei, נקודות בסיס).

אנחנו מוסיפים @custom:security — סימון מקומות הדורשים אימות מבקר. עבור חוזים המשתמשים ב-OpenZeppelin Upgrades, אנו מוסיפים @custom:oz-upgrades-unsafe-allow; אחרת הפלאגין ידחה את ההגירה.

דוגמה לפונקציה מתועדת כראוי:

/// @notice Переводит токены на указанный адрес
/// @dev Не работает с ERC-777 токенами из-за hook'ов; используй safeTransfer для неизвестных получателей
/// @param to Адрес получателя, не может быть address(0)
/// @param amount Количество токенов в минимальных единицах (wei)
/// @return success True если перевод прошёл успешно
function transfer(address to, uint256 amount) external returns (bool success);

איך להגדיר יצירת תיעוד אוטומטית

לאחר כתיבת NatSpec, ניתן ליצור תיעוד אוטומטית. השתמש ב-/// @notice Переводит токены на указанный адрес /// @dev Не работает с ERC-777 токенами из-за hook'ов; используй safeTransfer для неизвестных получателей /// @param to Адрес получателя, не может быть address(0) /// @param amount Количество токенов в минимальных единицах (wei) /// @return success True если перевод прошёл успешно function transfer(address to, uint256 amount) external returns (bool success); מ-Foundry: פשוט הוסף סעיף forge doc ל-foundry.toml והרץ [doc]. עבור Hardhat, התקן את הפלאגין forge doc והגדר solidity-docgen. אנחנו מגדירים CI/CD כך שהתיעוד מתעדכן ומתפרסם ב-GitHub Pages או Vercel בכל deploy. כל התהליך אורך 2–4 שעות, ואתה מקבל תיעוד HTML עדכני ללא מאמץ נוסף.

למה NatSpec קריטי לאבטחה

רוב התקפות ה-reentrancy קורות כי האינטגרטור לא מבין את לוגיקת החוזה. כאשר פונקציה חסרה hardhat.config.ts, המפתח קורא לה עם פרמטרים שגויים או לא מצפה לתופעות לוואי. NatSpec מסיר את אי-הוודאות הזו. בנוסף, כלי ניתוח (Slither, Mythril) יכולים לקרוא @notice ולבדוק אוטומטית סעיפים מסומנים. תקן NatSpec מתואר בתיעוד Solidity.

מה כלול בתוצאה

• ביקורת מלאה על הערות קיימות (אם יש).
• כתיבת NatSpec עבור כל הפונקציות @custom:security/public, אירועים ושגיאות.
• יצירת תיעוד HTML באמצעות external או forge doc.
• אינטגרציה עם CI/CD (יצירה אוטומטית בעת deploy).
• ייעוץ לגבי שיטות עבודה מומלצות: אילו תגיות חובה ואילו אופציונליות.

אנחנו מבטיחים כיסוי של 100% של ה-API הציבורי ומעבר בדיקת המהדר—כל תגית נכונה תחבירית.

טעויות נפוצות ביצירת NatSpec

• בלבול בין solidity-docgen ו-@notice: הראשון מיועד למשתמש, השני למפתח.
• חוסר תיאור @dev—המשתמש לא יודע מה הפונקציה מחזירה.
• חוסר @return במקומות עם נקודות תורפה פוטנציאליות (flash loans, oracles).
• תיאורים ארוכים מדי—MetaMask חותך טקסט; שמור על קיצור.

לוחות זמנים ועלות

תיעוד חוזה אחד בגודל בינוני (500–1000 שורות) אורך יום עבודה אחד. הגדרת צינור יצירת התיעוד אורכת עוד 2–4 שעות. העלות מחושבת באופן אישי לפי נפח הקוד ומורכבות הלוגיקה. נספק הערכה לפרויקט שלך תוך 24 שעות—צור קשר.

במשך למעלה מ-5 שנים, תיעדנו יותר מ-50 חוזים: מ-ERC-721 פשוט ועד מאגרי נזילות AMM מורכבים וחוזי staking. הניסיון שלנו מבטיח שאחרי התיעוד, אינטגרטורים לא שואלים שאלות ב-Discord ומבקרים עובדים מהר יותר.

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