פיתוח SDK לחוזים חכמים: מה נשבר בקנה מידה
הקריאה הראשונה לחוזה מתוך השירות נכתבת מהר: תיאור המתודות בהישג יד, הארגומנטים נאספים כמחרוזות, והתשובה מפורקת ידנית. פיתוח SDK לחוזים חכמים מתחיל בדיוק במקום שבו הקריאות הופכות לעשרות, החוזה מתעדכן, וכל עדכון הופך להשוואה בין מה שהשירות שולח לבין מה שהרשת מצפה לו.
מעטפות קריאה ידניות לכל רשת נפרדות זו מזו: במקום אחד סדר הארגומנטים שונה, במקום אחר הערך המוחזר אינו מטופל, ובמקום שלישי ההמתנה לאישור מחושבת אחרת. כל רשת חדשה היא העתקה של הקוד עם תיקונים מקומיים, ואת כולם לאחד להתנהגות אחת כבר אין מי שיעשה.
מיד לאחר מכן מורגשת אי-התאמה של טיפוסי נתונים. מספרים גדולים מגיעים מהצומת כמחרוזת ומאבדים דיוק בעת הפירוק, הכתובת נכנסת לקוד ללא סכום ביקורת, ומבנה ההחזרה מפורק לפי אינדקסים במקום לפי שדות. פגמים כאלה לא נתפסים בסקירת קוד: הם צפים בהעברה שגויה או בקריאה למתודה הלא נכונה.
קטגוריה נפרדת היא אי-התאמה בין סביבות: בסביבת הבדיקה פרוסה גרסת בנייה אחת של החוזה, ברשת הייצור אחרת, והאירועים שהשירות רשום אליהם נבדלים בקבוצת השדות. שגיאות אינטגרציה של חוזים מתגלות כבר אצל משתמשים חיים, ואיתור הסיבה אורך ימים. להלן כיצד סוגרים זאת.
מה נותנת טיפוסיזציה קפדנית של קריאות לחוזים
שכבת טיפוסים אחודה נבנית מתיאור החוזה: גנרטור כמו TypeChain הופך את הסכימה לקבוצת הצהרות — כתובת, הרכב הארגומנטים, מבנה התשובה, אירועים. לאחר מכן הקריאה אינה עוברת דרך מחרוזת עם שם המתודה, אלא דרך מעטפת מטופסת, והעורך מציע את הערכים המותרים עוד לפני ההרצה.
כך נעלם סוג שלם של פגמים — אי-התאמה של פורמטים: כתובת במקום האש, סדר ארגומנטים מבולבל, מחרוזת במקום שבו מצופה מספר, מימד שגוי של מערך. בעבר דברים כאלה צפו ברשת הבדיקה או, גרוע מכך, ברשת הייצור כבר בקריאה הראשונה; כעת הבנייה פשוט אינה עוברת.
התיקונים מואצים מאותה סיבה: בעת שינוי החוזה הפערים נראים כשגיאות טיפוסים במקומות מוגדרים, ולא כקבוצת נתונים אחרת בזמן הריצה. בדיקת הארגומנטים לפני הפריסה הופכת לחלק מהבנייה — החוזה אינו מקבל קריאה שגויה מלכתחילה, והצוות אינו מבזבז זמן על ניתוח תקלה.
תמיכה במספר רשתות נפתרת באותה שכבה: כתובות החוזים, המרשמים והעקיפות מוצאים לקונפיגורציה נפרדת, והלוגיקה של היישום נשארת משותפת. חיבור רשת חדשה הוא רשומה בקונפיג והרצה של אותן בדיקות מטופסות, ולא העתקה של קוד עם תיקונים מקומיים.
התוצאה מדידה: שיעור הקריאות היוצאות לרשת עם שגיאה בארגומנטים יורד לאפס — אותם חוסמת הבנייה, ולא המשתמש.
דרכי אספקה: ספרייה, יצירת קוד, מעטפות
שכבת הגישה לחוזים מסופקת בשלוש דרכים, והבחירה ביניהן נקבעת לפי התדירות שבה משתנה סכימת החוזים וכמה צוותים משתמשים בהם. ספריית חבילה מקבעת את המתודות והטיפוסים ברגע המסירה: נוח לקרוא אותה ולכסות אותה בבדיקות, אך כל שינוי בחוזה הוא תיקון ידני.
יצירת קוד של מעטפות יוצאת מתיאור החוזה: הסכימה משתנה — הטיפוסים ופירוק התשובות נבנים מחדש יחד איתה. המגבלה היא שיש לתעד גרסאות של הסכימה ולשמור על סנכרון עם הקוד הפרוס, אחרת השכבה הנוצרת מתרחקת מהמציאות. להלן השוואה לפי התאמה ומגבלות של המצבים.
| אפשרות אספקה | מתי מתאימה | מגבלות |
|---|---|---|
| ספריית חבילה | החוזים קפואים, המתודות מעטות, צרכן אחד | תיקונים ידניים בכל עדכון סכימה, הטיפוסים מתיישנים |
| יצירת קוד של מעטפות | חוזים רבים, שחרורים תכופים, מספר צרכנים | יש לתעד גרסאות של הסכימה ולבנות מחדש את החבילה בצינור |
| מעטפת בזמן ריצה | חלק מהחוזים אינם ידועים בשלב הבנייה | אין בדיקת טיפוסים בעת הבנייה — שגיאות קריאה נראות כבר בעבודה |
| ממשק אחוד מעל הרשתות | החוזה פרוס ברשתות שונות, קוד הצרכן משותף | פער בגרסאות ובכתובות, סמנטיקה שונה של ביטולים |
המצבים משולבים: חבילה — עבור הליבה הקפואה, יצירת קוד — עבור החלק הגדל, ממשק אחוד — עבור מספר רשתות. לפני האספקה אנו מסמנים את החוזים לפי תדירות השינויים ומפצלים אותם לפי מצבים, כדי ששכבה אוניברסלית אחת לא תתכסה בפתרונות עוקפים.
שלבי ההטמעה: מניתוח החוזים ועד המסירה
אנו מפצלים את העבודה לשלבים כך שבכל אחד נשאר תוצר ניתן לבדיקה: תיאור הממשקים, סכימת המודולים, הטיפוסים שנוצרו, דוח ההרצות. אז פערים בפרשנות החוזה צפים בביקורת, ולא בעת ההעלאה לרשת הראשית Ethereum. להלן הסדר שבו מתבצעת ההטמעה.
- ביקורת חוזים. אוספים את ה-ABI, מנתחים את הממשקים, האירועים, משני הגישה ומגבלות גרסת המהדר. מתעדים מקומות שבהם התיאור סוטה מהקוד.
- סכימת שכבת הגישה. מתכננים את המודולים: תובלה, חתימת טרנזקציות, סריאליזציה של ארגומנטים, טיפול בכשלי רשת. מתאמים מה הספרייה כופה ומה נשאיר כנקודת הרחבה.
- יצירת טיפוסים. מתוך ה-ABI והסכימות אוספים את הטיפוסים, ומשבצים את הגנרטור בבנייה — אי-התאמה של חתימות תופס המהדר, ולא סביבת הריצה.
- בדיקות ואימות ברשת הבדיקה. הרצות מודולריות על מוקים, אינטגרטיביות — על עותק של מצב הרשת, ובנפרד תרחישים עם ביטול ושליחה חוזרת.
- מתאמים רב-רשתיים. ממשק אחוד מעל רשתות שונות: ההבדלים בגימור ובחישוב הגז נשארים בתוך המתאמים ואינם דולפים לקוד היישום.
- קבלה ומסירת תחזוקה. צינור בנייה ופרסום החבילה, תיעוד ההגירה בין גרסאות, סקירה עם צוות הלקוח ותקופה של תיקונים משותפים.
תוצרי המסירה: סכימות, טיפוסים, נהלים
לאחר המסירה נשאר במאגר של הלקוח לא רק קוד החוזים, אלא גם כל מה שמאפשר לצוות שלכם לפתח אותו בלעדינו. כל סעיף להלן הוא תוצר מסירה מחייב: אנו בודקים אותו בקבלה יחד עם המהנדס שלכם.
- תיאורי חוזים — ממשקים וסכימות קריאים למכונה: מתודות, אירועים, שדות חובה. מהם נוצרים הטיפוסים, ולכן פער בין הקוד לתיאור צף בבנייה, ולא ברשת הראשית.
- טיפוסים שנוצרו — טיפוסיזציה של קריאות ותשובות עבור קוד היישום: כתובת, ארגומנטים וערכים מוחזרים נבדקים על ידי המהדר.
- קונפיגורציות רשתות — כתובות החוזים הפרוסים ופרמטרי החיבור לפי פרופילים של רשת הבדיקה והרשת הראשית: החלפת סביבה אינה דורשת תיקונים בקוד.
- מערך בדיקות — בדיקות מודולריות ואינטגרטיביות, תרחישים עם הרשאות גישה וערכי גבול, הרצה על רשת מקומית. דוח הכיסוי מראה אילו מסלולים נבדקו בפועל.
- נוהל עדכון — סדר שחרור גרסה: הכנת השינוי, אישור, הגירת מצב, ביטול שחרור כושל.
- תיעוד עבור הצוות — מפת החוזים, נקודות האינטגרציה, הערות ארכיטקטוניות והוראות להרצה מקומית של הסביבה.
- הרשאות ומפתחות — רשימת המהנדסים שלכם עם הרשאות למאגר ולפריסה, סדר רוטציה של מפתחות והנפקת חדשים.
מערך כזה מסיר את הסיכון העיקרי בפיתוח בקבלנות — התלות באנשים מסוימים.
מקרה בוחן: איחוד חמש רשתות לשכבת לקוח אחת
מה היה לפני
הפרויקט פעל בחמש רשתות במקביל, וכל רשת חדשה חוברה בהעתקה של הלקוח הקודם: טיפוסים לקריאות לחוזים נכתבו ביד, והמתאמים שכפלו זה את זה. אינטגרציה אחת ארכה כשלושה שבועות, יותר ממחציתם — ניפוי פערים בקידוד הנתונים. הדבקה ידנית הצטברה עד 900 שורות לרשת, ותיקון בחוזה שבר מקום אחר מזה שציפו לו.
מה שינינו
אספנו SDK לקוח אחד, שבו תיאורי החוזים הפכו למקור האמת היחיד: מתוכם נוצרים הטיפוסים והקריאות הניתנות לבדיקה. כל רשת מממשת ממשק משותף, וההבדלים עוברים למתאם — את Ethereum עשינו לעוגן, ואת האחרות התאמנו אליו.
את הבדיקות חילקנו למודולריות מהירות ולאינטגרטיביות בסביבת הבדיקה של הרשת, ובנפרד כיסינו תרחישים של כשלים, ניסיונות חוזרים וערכי גבול של סכומים.
מה יצא
חיבור חוזה חדש הצטמצם משלושה שבועות ליומיים, יחד עם הבדיקות והסקירה. שיעור הכשלים בגלל נתונים שנאספו שגוי ירד מ-11% ל-0.4%: פערים בדיוק המספרים ובפורמט הכתובות אינם מגיעים יותר לרשת. הקוד הידני באינטגרציה קטן פי עשרה בערך — נשארו רק תרחישי העסק. שוק או חוזה חדשים מחוברים כעת בימים, לא בחודשים, ואת הזמן שהתפנה הצוות מקדיש למוצר.
מה לעשות אם ה-SDK כבר הוטמע ודורש השלמה
שכבת הגישה לחוזים חכמים נכתבה כמעט תמיד עבור רשת אחת, וכשמחברים שנייה, ההפשטות מתחילות לדלוף. אין צורך לכתוב מחדש את ה-SDK לחוזים חכמים מאפס: לרוב די להוציא למתאם את מה שמוטבע היטב בלוגיקה העסקית.
החוב הטכני של האינטגרציה נראה צפוי: כתובות וטיפוסים מונחים בקבועים לצד הקוד העסקי, הבדיקות רצות על תשובות מוקלטות ולא על צומת חי, ופירוק האירועים בכל שירות הוא אחר. אנו מתארים תחילה את החוב הזה במרשם ומשאירים רק את הנקודות שמפריעות לרשת הבאה — היקף העבודה נראה לפני תחילת ההשלמה.
השלמת שכבה קיימת היא הרחבה, לא החלפה: מקבעים ממשק, שעבורו נכתבת מימוש לכל רשת, וההבדלים — קבלת החתימה, האישור, הניסיונות החוזרים — עוברים למתאם.
תאימות לאחור נשמרת בשכבת תאימות נפרדת: המתודות הישנות ממשיכות לעבוד, מסומנות כמיושנות ומוסרות רק לאחר מעבר כל הצרכנים. כך הוספת רשת חדשה אינה הופכת לשחרור חובה בו-זמני של כל השירותים.
ההחלפה ההדרגתית מתבצעת במקביל: המסלול החדש מופעל בדגל קונפיגורציה, שניהם רצים על אותם נתוני קלט, התוצאות מושוות אוטומטית, ופער חוסם את ההחלפה. רשתות מתחברות בימים, והחזרה למימוש הקודם נשארת זמינה בכל שלב.
שאלות נפוצות על אינטגרציה של שכבת החוזים
אינטגרציה של שכבת החוזים מתחילה לא בקוד, אלא בבדיקת השערות: כיצד תתנהג המעטפת בעת עדכון ממשק החוזה, מה יקרה לטרנזקציה בעת ניתוק התקשורת, והאם אותה קריאה מתנהגת באותו אופן ברשתות שונות.
ספקות אלה זולים יותר להסיר לפני השחרור — בייצור הם הופכים לטרנזקציות תלויות ולפערים בנתונים בין הרשתות.
האם ניתן לפנות לחוזים ישירות, בלי המעטפת?
כן. המעטפת מוסיפה טיפוסים, בדיקת ארגומנטים ופירוק שגיאות, אך אינה נועלת את הגישה: תיאורי הממשקים וכתובות החוזים נשארים אצלכם, וניתן לבצע קריאות ישירות. היא נחוצה במקומות שבהם חשובה הצפיות בצד היישום, ולא כדרך היחידה לרשת.
מה קורה כשהחוזה עודכן, והיישום עדיין בגרסה הישנה?
תיאורי הממשקים מנוהלים בגרסאות, והתאימות נבדקת בבדיקות חוזה על עותק של נתוני הייצור. אם חתימת הקריאה השתנתה, הבדיקה נופלת בבנייה, ולא בייצור; המעבר לגרסה החדשה מתבצע בשלב נפרד עם אפשרות לחזרה.
כיצד בודקים עבודה ברשת לא יציבה ובמספר רשתות?
האמולטור מדמה ניתוקים, השהיות ושליחה חוזרת, כדי לבדוק אידמפוטנטיות של הקריאות והתנהגות בתוצאה לא מוגדרת. מערך בדיקות אחד רץ על כל רשת נתמכת — פערים בהתנהגות המעטפות נראים לפני השחרור.
נדון במשימה: אילו נתונים נדרשים להערכה
בדיקות, טיפוסיזציה ותמיכה במספר רשתות — אלה חלקי ה-SDK שבהם ההערכה תלויה ביותר בנתוני הפתיחה. כדי לחזור עם תוכנית עבודה, ולא עם מילים כלליות, אנו זקוקים למערכת קצרה של עובדות על הפרויקט שלכם.
- הרכב החוזים: כמה יש, אילו כבר פרוסים, האם קיים פרוקסי ומנגנון עדכון לוגיקה — מכך תלוי היקף יצירת הטיפוסים והתשתית.
- רשתות היעד וסדר החיבור: רשת אחת או כמה בבת אחת, האם נדרשות כתובות ומערכי פרמטרים נפרדים לכל סביבה.
- הלקוח הנוכחי: במה כתוב הקשר כעת — המעטפות מוטמעות מעליו או מחליפות אותו לחלוטין.
- דרישות לבדיקות: אילו תרחישים חייבים להיות מכוסים — שחרור, הרשאות גישה, מגבלות קריאה, התנהגות בעת כשל.
- מה כואב היום: קריאות ידניות, פערי טיפוסים לאחר עדכון החוזה, היעדר בדיקות בסביבה מקומית.
- אספקה ותוצרים: האם נדרשת חבילה במרשם פנימי, יצירת טיפוסים בשלב הבנייה, תיעוד נפרד עבור הצוות.
תארו את המשימה בצורה חופשית — לפי סעיפים אלה נחזור עם הערכה, גבולות השלבים ותוכנית עבודה.