הגדרת Truffle לחוזים חכמים: תצורה, מיגרציות ובדיקות

למה Truffle Suite נשבר במיגרציות ובבדיקות

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

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

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

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

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

מה נותנת תצורת בנייה ומיגרציות מסודרת

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

צ'קליסט שלפיו רואים שתצורה מסודרת:

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

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

Truffle Suite וחלופות: השוואת מצבי עבודה

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

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

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

סדר ההגדרה: מאודיט מבנה ועד מסירה לצוות

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

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

תצורות, סכמות מיגרציות ותיעוד בפלט

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

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

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

מקרה בוחן: צמצום פעולות ידניות בפריסת חוזים

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

לפני: פריסה ידנית

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

אחרי: הרצה אחת

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

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

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

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

מה לעשות אם התצורה כבר נפרסה ודורשת השלמה

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

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

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

שאלות טכניות נפוצות על הגדרה ותמיכה

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

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

איך מגדירים כמה רשתות בפרויקט אחד?

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

למה מקומית הכול עובר, וברשת הציבורית זה נופל?

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

איך מבצעים רולבק למיגרציה שלא הצליחה?

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

נדון במשימה שלכם: תצורה, מיגרציות ובדיקות

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

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

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