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

תיעוד חוזים חכמים: היכן הולך לאיבוד ההקשר

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

הקוד עונה על השאלה "איך", אך לא על "למה" — והידע הזה הולך לאיבוד ראשון כאשר האדם שכתב את החוזה עוזב את הפרויקט.

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

ניתוח חוזה זר ללא תיאור לוגיקה נמשך שבועות, וכל אותו זמן הפיתוח עומד מלכת: כל שינוי מחייב בדיקה מחדש של החוזה כולו.

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

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

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

מה משתנה לאחר התיעוד: תיקונים, ביקורת, הפצות

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

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

הדבר נשען על שלושה דברים. הערות-מפרט לפי תקן NatSpec לכל פונקציה ציבורית — ייעוד, ארגומנטים, ערכי החזרה, אירועים; מהן נבנה תיעוד קריא לאדם כחפץ אחד. השני — תפקידים ואינווריאנטים מתועדים: מי רשאי לקרוא למתודה ואילו מצבים אסורים. השלישי — בדיקה בבנייה: פונקציה ללא תיאור עוצרת את ההפצה, ולכן התיאור אינו מפגר אחרי הקוד.

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

פורמטים של תיאור: הערות, מרשמים, יצירה אוטומטית

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

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

שלבי תיעוד חוזים חכמים ובדיקות

פער בין התיאור לקוד הוא הפגם היקר ביותר בתיעוד: האינטגרטור קורא דבר אחד, החוזה עושה דבר אחר, וצריך לברר זאת כבר ברשת פעילה. לכן שלבי התיעוד של חוזים חכמים אצלנו בנויים כתהליך הנדסי עם בדיקה בכל שלב, ולא כתיקון חד־פעמי של הערות. להלן סדר העבודה שכל חוזה עובר לפני מסירה ללקוח.

1. מלאי פונקציות. אוספים את הממשק החיצוני המלא: מתודות ציבוריות וחיצוניות, קליטת כספים, אירועים, מודיפיקטורים, פניות לחוזים אחרים. בפלט — רשימה של כל מה שדורש תיאור, ללא השמטות.
2. סימון לפי התקן. לכל פונקציה ואירוע כותבים ייעוד למשתמש, הסבר למהנדס, פרמטרים, ערכי החזרה ותנאי כישלון. הניסוחים — על משמעות הפעולה, ולא שחזור של הקוד.
3. השוואת התיאור להתנהגות. מריצים תרחישים ברשת בדיקה, עוקבים אחר הקריאות ומשווים את ההשפעות בפועל למה שכתוב: שינוי מצב, העברת כספים, הגבלות לפי תפקידים, גבולות ערכים. פער — זו או שגיאה בטקסט, או פגם בלוגיקה.
4. תיעוד אינווריאנטים וסיכונים. בנפרד מסמנים פעולות בלתי הפיכות, נקודות עצירה, מגבלות ומה שאסור לעשות עם החוזה. דווקא החלק הזה הולך לאיבוד לרוב במסירה.
5. מסירת התיאורים. אוספים מסמך לצד הקוד, עוברים עליו עם צוות הלקוח ועונים על שאלות לגבי כל מתודה — כדי שיקראו את התיאור, ולא יניחו אותו בארכיון.
6. שמירה על עדכניות. מסכמים על כלל: שינוי לוגיקה ללא עדכון התיאור אינו עובר בדיקה לפני ההפצה.

תרשימי קריאות, נהלי עדכון, תבניות תיאור

חבילת התיעוד נאספת כך שמהנדס שלא השתתף בפיתוח יוכל להרים אותה ולפרוס את החוזה בלי התכתבות איתנו. להלן מה שנשאר אצלכם לאחר המסירה וחי יחד עם הקוד, ולא בנפרד ממנו.

• תרשים קריאות של החוזה — גרף של קריאות חיצוניות ופנימיות: מי קורא לכל פונקציה, אילו אירועים נרשמים, היכן נקודות ההסתעפות ולאן מובילות התלויות החיצוניות.
• מטריצת תפקידים — טבלת «תפקיד → פונקציה → הרשאות → השלכות שגיאה»: רואים למי ניתנה גישה להפצה, לעצירה ולשינוי פרמטרים, ומה בדיוק נשבר בשימוש שגוי.
• תבניות תיאור — הכנות של בלוקי NatSpec: ייעוד החוזה, פרמטרים וערכי החזרה, אינווריאנטים, מגבלות, דוגמאות לקריאה תקינה.
• נוהל עדכון תיאורים — כלל שלפיו תיקון הלוגיקה ותיקון התיאור נעשים כשינוי אחד; פער נחשב לפגם וחוסם מיזוג ענף.
• קישור לגרסה — התיאורים מפנים לכתובת החוזה הפרוס ולתגית ההפצה, ולכן מסמך מיושן אינו מוצג כמהימן.
• רשימת בדיקה לפני העלאה — האם הפונקציות הציבוריות מכוסות בתיאור, האם מטריצת התפקידים עודכנה, האם תרשים הקריאות תואם את התלויות בפועל.
• יומן פערים — היכן מתועדים אי־ההתאמות שנמצאו בין הקוד לתיאור ומי אחראי לסגירתם.

בעת החלפת קבלן החבילה עוברת לצוות החדש בשלמותה — הכניסה לקוד אורכת ימים, לא שבועות.

מקרה בוחן: תיאור לוגיקה לפני ביקורת והפצה

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

מה עשינו

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

לצד זה הנחנו תרשים מצבים וטבלה «דרישה עסקית — פונקציית החוזה», כדי שהבודק יראה את הקשר בין הקוד לכוונה, ולא ישחזר אותו לפי השערות.

מדדים לפני ואחרי

הביקורת התנהלה לפי השוואה למסמך, ולא לפי תשאול הצוות. מספר שאלות ההבהרה מהבודקים ירד מכ-ארבעים לשש — הן נגעו כבר לא לייעוד הקוד, אלא לנקודות שנויות במחלוקת בכלכלה.

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

במה NatSpec שונה מתיעוד חיצוני?

NatSpec — אלו הערות ישירות בקוד שקורא מהדר Solidity. הן משויכות לפונקציה, לאירוע או לחוזה מסוים: ייעוד, פרמטרים, ערכי החזרה, תופעות לוואי. אנוטציות כמו @notice ו-@param עוברות דרך הבנייה, ולכן אינן סוטות מהמימוש — בשינוי חתימה הפער צף בשלב ההידור, ולא אצל המשתמש.

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

מחבר בין השכבות הללו יצירת המדריך: מתוך NatSpec נאסף החלק הטכני — רשימת פונקציות, אירועים ושגיאות עם תיאורים — והמסמך החיצוני מפנה אליו. המפתח מקבל חתימה לצד המימוש, והלקוח — תיאור לוגיקה בלי לקרוא קוד מקור.

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

ספקות טכניים נפוצים לגבי תיאור לוגיקה

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

מה לעשות עם קוד מקור שאבד?

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

כיצד לתחזק את התיאורים בהמשך?

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

נדון במשימה: תיאור לוגיקה לפרויקט שלכם

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

• גבולות אמון: אילו כתובות ותפקידים מורשים לקרוא לפונקציות ומה קורה אם פונקציה נקראת על ידי גורם לא מתאים.
• תלויות חיצוניות: קריאות לחוזים אחרים, אורקלים, גשרים — וכיצד הלוגיקה מתנהגת כשהם לא זמינים או מחזירים נתונים בלתי צפויים.
• אירועים וערכי החזרה: האם הם מספיקים לצפייה במערכת ולניתוח תקלות, האם הם נקראים באופן חד־משמעי.
• אינווריאנטים: סכומים, מגבלות, סדר שינוי מצבים, הרשאות למשיכת כספים — מה שחייב להחזיק בכל תרחיש.
• מצב התיעוד הנוכחי: היכן ההערות סוטות מהקוד, אילו פונקציות ומודיפיקטורים אינם מתוארים כלל.
• נמען התיאור: ניתוח לביקורת, הוראות לאינטגרטורים או מסירת הפרויקט לתחזוקה.
• פורמט התוצאה: אנוטציות NatSpec בקוד, בניית תיעוד כללי, היסטוריית שינויים לפי גרסאות.

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