פריסת חוזה ניתן לתכנות

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

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

לפני שמתחילים

כדי להשלים את המדריך הזה, תצטרכו:

  • מפעילים את Cloud Shell במסוף Google Cloud .

    הפעלת Cloud Shell

  • חשבון משתמש ב-Universal Ledger עם ROLE_CONTRACT_CREATOR. החשבון הזה יהפוך לבעלי החוזה.

  • חשבון משתמש אחד או יותר ב-Universal Ledger עם התפקיד ROLE_CONTRACT_PARTICIPANT. הוא יכול להיות אותו חשבון כמו של בעלי החוזה.

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

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

מגדירים את הסביבה

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

הקומפיילר של gculpyc מקבל קוד מקור שכתוב בשפת GCULpy ומפיק קוד בייט ל-Universal Ledger.

מריצים כל אחת מהפקודות הבאות כדי לשלוף את קובץ האימג' של Docker ב-gculpyc, להגדיר שם סודי להרצת הקובץ הבינארי ולוודא שהקובץ הבינארי פועל.

docker pull us-docker.pkg.dev/gcul-artifacts/images/client/gculpyc:stable
alias gculpyc="docker run --rm -i --user $(id -u):$(id -g) \
    --volume .:/workspace --workdir /workspace \
    us-docker.pkg.dev/gcul-artifacts/images/client/gculpyc:stable"
gculpyc --help

כתיבת החוזה

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

מכיוון ש-GCULpy היא קבוצת משנה קפדנית של Python, אתם יכולים להמשיך להשתמש בסביבות הפיתוח המשולבות (IDE) המועדפות עליכם, יחד עם תהליכי העבודה ושיטות הפיתוח הקיימים שלכם.

לדוגמה, הקוד יכול להיראות כך:

import gcul

class Counter(gcul.Contract):
    """Example contract implementing a counter."""

    value: int

    def increment(self) -> None:
        """Increments the counter value by 1."""
        self.value += 1

מעתיקים את הקוד לדוגמה ושומרים אותו בקובץ בשם counter.py.

בדיקה מקומית

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

עריכת החוזה

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

gculpyc --source_file counter.py --output_file counter.bin

פריסת החוזה

פורסים את החוזה ברשת Universal Ledger על ידי שליחת עסקה מסוג CreateContract, שחתומה על ידי חשבון משתמש שמחזיק ב-ROLE_CONTRACT_CREATOR.

אם משתמשים ב-CLI של Universal Ledger, אפשר לעשות את זה באמצעות הפקודה:

ul-cli contracts create \
    --alias counter-contract \
    --sender OWNER_ALIAS \
    counter.bin

מחליפים את מה שכתוב בשדות הבאים:

  • ‫OWNER_ALIAS: השם החלופי של חשבון משתמש עם ROLE_CONTRACT_CREATOR.

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

Contract created: 1:CTR:005XvYfiSm3913Jwv4y8HVQucStJ2Ev15Sar6A1kNNX10

הפעלת שיטה של חוזה

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

אם משתמשים ב-CLI של Universal Ledger, אפשר לעשות את זה באמצעות הפקודה:

ul-cli contracts invoke \
    --alias counter-contract \
    --method-name increment \
    --sender PARTICIPANT_ALIAS

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PARTICIPANT_ALIAS: השם החלופי של חשבון משתמש עם ROLE_CONTRACT_PARTICIPANT.

קריאת מצב החוזה

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

באמצעות Universal Ledger CLI, אתם יכולים להריץ את הפקודות הבאות:

ul-cli accounts describe --alias counter-contract

כך אפשר לוודא שערך המונה מוגדר עכשיו כ-1, ומתקבל פלט כמו:

Account: 1:CTR:005XvYfiSm3913Jwv4y8HVQucStJ2Ev15Sar6A1kNNX10
Contract account details:
  Owner: 1:USR:XCL:022uF6cVkTJBaa6pViqTuYqP4455jnRbRc4bWannZGg0b
  Contract fields:
    value: int64_value:1

  Balances:
    None

המאמרים הבאים