אינטגרציית פרונטאנד של TON: SDK, TonConnect ומודל Cell

אינטגרציה של TON SDK: היכן הפרונטנד נשבר ומה עושים עם זה

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

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

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

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

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

מה נותנת בנייה צפויה: מהירות, כשלים, תמיכה

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

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

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

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

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

פורמטים של אינטגרציה: מודול צדדי, הטמעה, היברידי

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

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

שלבי עבודה: מביקורת ועד מסירה לצוות

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

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

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

סכמות, קונפיגורציה ונהלי עדכון

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

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

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

מקרה בוחן: איך הסרנו אישורים תקועים אצל משתמשים

מה היה

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

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

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

מה השתנה

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

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

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

במה מודל Cell שונה מבקשות רגילות לשרת

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

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

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

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

מגבלות וחששות טכניים לפני התחלה

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

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

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

מה אם המשתמש דחה את החתימה או סגר את הארנק?

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

אילו סיכוני תאימות ונדידה?

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

נדבר על המשימה: מה נדרש מכם ומה אנחנו עושים

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

מה נדרש מצדכם:

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

מה אנחנו לוקחים על עצמנו:

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

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