تكوين العقد الذكي ونشره

لإنشاء العقد الذكي، نحتاج إلى تحديد الكيانات المطلوب تخزينها وإدارتها في البلوك تشين كما هو موضح في نموذج كيان الصورة التالية.

وصف الشكل التوضيحي oracle-blockchain-cms-entity.png
يتم تحديد كل هذه الكيانات وعلاقاتها، وكل المنطق المطلوب لإدارة الكيانات والتفاعل معها، وكذلك الاحتفاظ بها في دفتر أستاذ قواعد البيانات المتسلسلة في العقد الذكي.

يتم تمثيل المجلد كرمز NFT مميز، لذلك سيتم تطويره وتهيئته كـ NFT. الكيانات التابعة الأخرى (المستندات والخصائص) هي كيانات قياسية وهي كيانات تابعة للمجلد، لذا سيتم تطويرها ككيانات قياسية دون الحاجة إلى التهيئة.

بمجرد إنشاء العقد الذكي، سنقوم بتثبيته ونشره في شبكة Blockchain التي أنشأناها.

تكوين العقد الذكي

بمجرد تكوين Oracle Blockchain App Builder، يمكنك تكوين ملف المواصفات. يمكن إنشاء ملف المواصفات كملف YAML بسيط معروض في التعليمة البرمجية التالية.

ملاحظة:

يمكنك أيضًا تنزيل هذا الملف من GitHub: تنزيل ملف YAML.

#
# Token asset to manage the complete lifecycle of a non-fungible token representing a folder to hold docuements. 
# This specification file will generate an Smartcontract project with a non-fungible token for the folders to be maintained by the users.
#
assets:
    - name: folderNFT
      type: token
      symbol: eDocs
      standard: erc721+
      anatomy: 
        type: nonfungible
        unit: whole
      behavior:
        - indivisible
        - singleton
        - mintable:
        - transferable
        - burnable
        - roles:
            minter_role_name: minter
      properties:
          - name: folderHASH
            type: string
          - name: documents
            type: document[]
      metadata:
          - name: folderID
            type: string
            mandatory: true
            id: true
          - name: folderType
            type: string
            mandatory: true
      methods:
        crud: [create, getById, update, delete]
        others: [getHistoryById, getByRange]
    - name: document
      properties:
        - name: docName
          type: string
          mandatory: true
          id: true
        - name: docURL
          type: string
          mandatory: true
        - name: docHASH
          type: string
          mandatory: true
        - name: docType
          type: string
          mandatory: true
        - name: docProperties
          type: docProperty[]
      methods:
        crud: [create, getById, update, delete]
        others: [getHistoryById, getByRange]
    - name: docProperty
      type: embedded
      properties:
          - name: propName
            type: string
            mandatory: true
          - name: propValue
            type: string
            mandatory: true
      methods:
        crud: [create, getById, update, delete]
        others: [getHistoryById, getByRange]
customMethods:
    - executeQuery
    - "attachDocument(tokenId: string, docName: string, docURL: string, docHASH: string, docType: string, docProps: string[], docVals: string[])" # Attach a document to an existing folder. 
    - "retrieveDocuments(tokenId: string)" # Retrieve Documents of an folder. 
    - "transferFolder(tokenId: string, fromOrgId: string, fromUserId: string, toOrgId: string, toUserId: string)" # Transfer the folder among participants. 
    - "updateFolderHASH(tokenId: string, newHash: string)" # Update HASH folder 
    - "getFolderHASH(tokenId: string)" # Check HASH folder 

في ملف المواصفات هذا، في الكيان الأول المحدد (folderNFT) يمكنك رؤية جميع الأقسام والسمات لتمثيل مقطع NFT. نظرة عامة على الأقسام المعرفة في الملف:

• الأصول: المكان الذي يتم فيه تحديد الأصول المختلفة (الكيانات القياسية، المعاملات المالية، المعاملات المالية الوطنية). داخل كل من الأصول يمكننا التمييز بين أقسام مختلفة والتي يمكن أن تختلف تبعا لنوع الأصول الممثلة. بالنسبة لـ NFTs و FTs، هذه هي الأقسام الفرعية المختلفة:
  • النوع/الرمز/القياسي: حدد أن هذا المقطع يستند إلى معيار ERC-721، وامنحه معرف رمز فريدًا.
  • التشريح: حدد أنه NFT وما إذا كان مقسمًا إلى كسور أصغر (في الوقت الحاضر "كامل" هو الخيار الوحيد لمقاطع NFT).
  • السلوك: يحدد ما إذا كان يمكن صبغ الرمز المميز أم لا، وفي هذه الحالة، ما هو الحد الأقصى لعدد الرموز المميزة القابلة للكتابة. هنا يجب أن تذكر أيضا أنه رمز غير قابل للتجزئة، إذا كان منفرد لكل فئة، قابلة للتحويل، وقابلة للحرق والتي تشبه حذفها (ولكن لا تختفي، لذلك لا يزال هناك ولكن لا يمكن استخدامها على الإطلاق). يمكنك أيضًا في هذا القسم قصر سلوك الرمز المميز على أدوار محددة.
  • ميتاديتا: تعريف نوع من الخصائص التي يجب تعيينها أثناء تكوين المقطع، ولا يمكن تغييرها في المستقبل. لذلك ستظل قيمتها ثابتة طوال حياة الرمز المميز.
  • الخصائص: يحدد السمات القياسية للمقطع التي يمكن أن تختلف أثناء عمر المقطع، مثل مصفوفة المستندات التي تشكل المجلد.
• customMethods: الموقع الذي يجب فيه تحديد قائمة الأساليب المخصصة. بالنسبة لهذه الأساليب، سيقوم Oracle Blockchain App Builder بإنشاء توقيع الأسلوب فقط، دون أي تنفيذ عليها. تنفيذ هذه الأساليب هو التعليمة البرمجية الوحيدة التي يمكن للمطور تنفيذها.

توضح الارتباطات التالية كيفية تكوين أي نوع من الكيانات (NFT أو FT أو الكيانات القياسية) استنادًا إلى احتياجات العمل:

• الكيان القياسي، راجع كيفية إنشاء ملف مواصفات مدخلات.
• يتم تمثيل الكيان كـ NFT، راجع ملف مواصفات المدخلات للمقاطع غير القابلة للفطريات.
• يتم تمثيل الكيان كمعاملات مالية، راجع ملف مواصفات المدخلات للمقاطع القابلة للطي.

بمجرد إنشاء ملف المواصفات، يمكننا تفويض Oracle Blockchain App Builder لإنشاء سقالات المشروع باتباع الخطوات التالية.

1. إذا تم إنشاء ملف المواصفات خارج Oracle Blockchain App Builder، فلا بد من استيراد ملف المواصفات إلى Oracle Blockchain App Builder. انقر على علامة الحذف بجوار إطار المواصفات، ومن النافذة المنبثقة، انقر على استيراد المواصفات.
2. حدد ملف المواصفات، وانقر على استيراد المواصفات.
3. للتمكن من إنشاء مشروع chaincode جديد استنادًا على ملف المواصفات الذي تم استيراده، انقر على أيقونة + في الركن العلوي الأيمن من إطار CHAINCODES. يتم فتح معالج تكوين رمز سلسلة الفنادق.
4. في معالج تكوين رمز سلسلة، يجب تحديد التفاصيل التالية:
   • الاسم: اسم المشروع.
   • اللغة: لغة إنشاء سقالات المشروع. يمكنك الاختيار بين Typescript وGoLang فقط. نظرًا لأننا نستخدم Typescript في كتيب الحلول هذا لتنفيذ الأساليب المخصصة، نوصي بتحديد Typescript.
   • المواصفات: حدد ملف المواصفات الذي قمنا بتكوينه للتو في الخطوات السابقة.
   • الموقع/النطاق: بناءً على اللغة المحددة، ستتم مطالبتك بتعريف الموقع الذي سيتم وضع المشروع فيه للغة Typescript أو النطاق للغة GoLang.
   إذا كانت كافة التفاصيل صحيحة، يجب أن نرى رسالة خضراء في المعالج. إذا لم يكن الأمر كذلك، تحقق من المخرجات التي تم إنشاؤها أثناء إنشاء سقالة المشروع.
5. في قسم CHAINCODES، فستجد أن المشروع الجديد الذي تم إنشاؤه. النقر في المشروع، والانتقال إلى مجلد src داخل المشروع، حيث تم إنشاء التعليمات البرمجية المصدر:
   • في مجلد src/controller، سنرى الفئة الرئيسية التي تمثل عقدنا الذكي، مع جميع الأساليب التي تم إنشاؤها تلقائيًا لإدارة كياناتنا.
   • في مجلد src/model، سنرى الكلاس الذي يمثل كيان NFT.
6. انتقل إلى مجلد src/controller، وحدد كلاس وحدة التحكم، وسنرى جميع التعليمات البرمجية التي تم إنشاؤها تلقائيًا بواسطة Oracle Blockchain App Builder، وانتقل إلى نهاية الملف، وسنرى جميع توقيعات الأساليب المخصصة دون أي تنفيذ عليها.
7. في هذه المرحلة، يتعين علينا إنشاء تنفيذ للأساليب المخصصة. من أجل البساطة، قمنا بتوفير جميع تعليمات التنفيذ البرمجية لهذه الأساليب في الملف CMS_customMethods.ts المتاح في GitHub. يلزمك فقط استبدال التوقيعات التي تم إنشاؤها تلقائيًا بواسطة Oracle Blockchain App Builder، باستخدام المحتوى في الملف المشار إليه.

تشتمل فئة وحدة التحكم، التي تقع قبل الأساليب المخصصة، على جميع التعليمات البرمجية المكونة تلقائيًا لإدارة دورة حياة مقاطع NFT. توضح الصورة التالية المناطق المختلفة التي تغطيها هذه الطرق.

وصف الشكل التوضيحي oracle-blockchain-nft-token.png

oracle-blockchain-nft-token-oracle.zip

عند هذه النقطة، يكون رمز السلسلة جاهزًا للاستخدام، حتى نتمكن من نشر رمز السلسلة واختباره محليًا باتباع التعليمات من اختبار رمز السلسلة الخاص بك على شبكة Hyperledger Fabric محلية.

نشر العقد الذكي

بمجرد اختبار رمز السلسلة محليًا، تابع نشره في الشبكة الحقيقية التي تم إنشاؤها مسبقًا باستخدام وحدة تحكم خدمة Oracle Blockchain من خلال:

• تعبئة مشروع chaincode.
• تثبيت حزمة chaincode ونشرها في المثيل الواحد (المؤسس).

يوضح القسم التالي الخطوات التفصيلية لتنفيذ النشر.

1. أنشئ الحزمة القابلة للتوزيع من مشروع chaincode. من Visual Studio، انقر فوق الزر الأيمن أعلى اسم مشروع chaincode، من القائمة المنبثقة حدد خيار الحزمة وحدد الدليل لحفظ ملف حزمة chaincode.
2. الوصول إلى وحدة تحكم خدمة Oracle Blockchain لتثبيت حزمة رمز السلسلة ونشرها في مثيل المؤسس.
3. انتقل إلى علامة التبويب رمز السلسلة، وانقر على نشر رمز سلسلة جديدة.
4. حدد خيار النشر المتقدم.
5. قم بتعيين جميع القيم لتثبيت حزمة chaincode في مثيل المؤسس وانقر على التالي.
   • تسمية الحزمة: قم بإدخال اسم يمكن أن يساعدك في تحديد الحزمة المثبتة في القنوات الموجودة المختلفة. نظرًا لأنه يمكنك نشر أكثر من إصدار واحد من نفس العقد الذكي في قنوات مختلفة، فمن الممارسات الجيدة تعيين اسم تسمية حزمة مثل:

     <smartContractName>_<channel>_<version>
     

   • لغة رمز السلسلة: حدد من بين اللغات المختلفة، بناءً على اللغة التي قمت بتطوير رمز السلسلة بها.
   • الأقران الهدف: حدد الأقران الذين تريد تثبيت حزمة chaincode بهم.
   • Is Packaged Chaincode: اترك مربع الاختيار هذا غير محدد إذا كنت تقوم بتحميل ملف مضغوط. حدد مربع الاختيار لملفات tar.gz.
   • مصدر رمز السلسلة: انقر على تحميل ملف رمز السلسلة وحدد الملف المضغوط لرمز السلسلة.
6. إذا نجح التثبيت، فسترى رسالة النجاح. الخطوة التالية هي نشر رمز السلسلة في القناة المحددة، لذا يجب تعيين جميع القيم المرتبطة بمرحلة النشر والنقر على التالي.
   • القناة: حدد القناة التي تريد نشر العقد الذكي بها.
   • اسم رمز السلسلة: قم بتعيين الاسم الذي سيتم نشر العقد الذكي به على القناة.
   • الإصدار: تعيين رقم لهذا النشر، والذي تتم محاذاته مع الحزمة المثبتة مسبقًا. وبهذه الطريقة، ستتمكن من ربط الحزم المثبتة برموز السلسلة المنشورة في قنوات مختلفة.
   • مطلوب أوليًا: حدد مربع الاختيار هذا إذا كان يجب استدعاء طريقة init الخاصة برمز السلسلة قبل السماح بحركات المستخدم.
   • سياسة التظهير: تحديد سياسات التظهير أثناء النشر. في مثال دليل الحلول هذا، لا نستخدم سياسات التأييد.
   • تجميع البيانات الخاصة: تعيين مجموعات البيانات الخاصة إذا لزم الأمر. في مثال كتيب الحلول هذا، لن نقوم بتعيين جمع البيانات الخاصة.

إذا نجح النشر، فبعد إغلاق التثبيت والنشر، سترى كيف تم تثبيت الحزمة في نظيرتي المثيل، وتم تكوينها أيضًا في إحدى القنوات.

بدء العقد الذكي

عند التعامل مع المعاملات المالية ورموز NFT المميزة، هناك مجموعة من الإجراءات الإدارية التي يجب تنفيذها قبل التمكن من تنفيذ أساليب عملك. باستخدام Oracle Blockchain، يمكن تنفيذ جميع المهام الإدارية كمكالمات REST بسيطة وتقلل بشكل كبير من الجهد اللازم لتهيئة العقد الذكي.

ملاحظة:

قبل تنفيذ أي من الخطوات التالية، يجب تكوين enrollmentIDs في بروكسي REST للمستخدمين الذين تم منحهم صلاحية الوصول إلى طرق العقد الذكي. التسجيل هو تخطيط بين اسم المستخدم الذي يقوم باستدعاء الواجهة البرمجية للتطبيق لخدمة REST والحسابات المدارة داخليًا بواسطة سلسلة السجلات التي سيتم تخصيص المقاطع إليها كما هو موضح في موضوع تكوين التسجيلات في نقاط توصيل وكيل خدمة REST.

استخدم مجموعة Postman التالية لتهيئة العقد الذكي بسهولة: تنزيل مجموعة Postman

في مجلد AdminSteps الخاص بمجموعة Postman هذه، توجد ثلاث استدعاءات طلبات لتهيئة العقد الذكي.

مجموعة Postman جاهزة للاستخدام، ولكن هناك مجموعة من المتغيرات التي تحتاج إلى تكوين ملائمة لبيئتك الخاصة (كلمات المرور، عناوين URL، وما إلى ذلك). يتم تعيين هذه المتغيرات في علامة تبويب المتغيرات ضمن مجموعة Postman. يعرض الجدول التالي كل المتغيرات التي قمنا بتعريفها والتي يلزم تكييفها مع بيئتك.

اسم المتغير	قيمة المتغير
bc_founder_provider_url	https://org1-w....
bc_timeout	60000
bc_nft_founder_userid1	cmsleg001
bc_nft_founder_userid1_pwd	كلمة السر
bc_nft_founder_userid2	cmsfin001
bc_nft_founder_userid2_pwd	كلمة السر
bc_nft_founder_userid3	cmsrsk001
bc_nft_founder_userid4_pwd	كلمة السر
bc_channel_name	حفلات الزفاف
bc_chaincode_name	الأربعاء

ابحث عن نقطة الانتهاء التي يمكن الوصول فيها إلى واجهة برمجة تطبيقات REST من وحدة تحكم خدمة البلوك تشين.

1. الوصول إلى وحدة تحكم خدمة البلوك تشين من خلال وحدة تحكم OCI.
2. انتقل إلى علامة تبويب نقاط التوصيل. سيعرض لك كل نقاط التوصيل التي تشكل هذا المثيل، وفي نقطة توصيل Restproxy سترى عنوان URL لنقطة النهاية في عمود المسار.
   تذكر أن عمليات التسجيل يتم تكوينها على مستوى المثيل، وليس على مستوى الشبكة، وبالتالي فإن تسجيل المستخدم سيكون متاحًا فقط من خلال عنوان URL لـ restproxy الخاص بطبعة المؤسس، لذلك، إذا انضمت مثيلات جديدة إلى الشبكة، مع السماح للمستخدمين الجدد بالوصول إلى الشبكة، سيحتاج هؤلاء المستخدمين إلى الوجود في مثيل قاعدة البيانات المؤجر المناسب، ويجب أيضًا إنشاء تسجيلات هؤلاء المستخدمين في وكيل المثيل المقابل.

بمجرد تكوين مجموعة Postman بشكل صحيح، يمكننا متابعة تهيئة العقد الذكي. إن بدء العقد الذكي NFT أبسط بكثير من بدء العقد الذكي FT، نحتاج فقط إلى تنفيذ ثلاث خطوات:

1. تهيئة العقد الذكي (بدء حسابات المستخدمين المسئولين).
2. إنشاء محافظ للمستخدمين الذين يمكنهم امتلاك رموز NFT.
3. تعيين دور عامل المناجم للمستخدمين الذين يجب أن يتمتعوا بهذا الامتياز.

تتوافق استدعاءات API REST التالية مع الاستدعاءات في مجلد AdminSteps من مجموعة Postman المقدمة.

1. تهيئة رمز السلسلة (الخطوة 0: تهيئة حساب مستخدم المسئول) للإشارة إلى حسابات المستخدمين التي سيتم السماح لها بتنفيذ المهام الإدارية. من المهم تعيين وسائط الأسلوب init بشكل صحيح: args: Scaped array of user_ids with their org_ids.

   
   {
       "chaincode": "{{bc_nft_chaincode_name}}",
       "args": [
           "init",
           "[{\"orgId\":\"org1\",\"userId\":\"cmsleg001\"},{\"orgId\":\"org1\",\"userId\":\"cmsfin001\"},{\"orgId\":\"org1\",\"userId\":\"cmsrsk001\"}]"
       ],
       "timeout": {{bc_timeout}},
       "isInit": true,
       "sync": true
   }
   

2. تكوين حسابات مستخدم لكل المستخدمين الذين يمكن أن يكونوا أمناء لأصول NFT التي تمثل الأصول الفعلية. يمكن القيام بذلك عن طريق تنفيذ طلب الخطوة 1: تكوين حساب بوستمان. بالنسبة إلى تفاصيل حالة الاستخدام الخاصة بنا، لا يوجد سوى ثلاثة مستخدمين مرتبطين بنفس المؤسسة الفردية التي تنتمي إلى الشبكة. يجب تنفيذ هذه المكالمة بعدد المستخدمين الذين نريد إنشاء حساب لهم. في حالتنا ثلاث مرات، لكل منها المعلمات التالية:
   • "createAccount", "org1", "cmsleg001", "nonfungible"
   • "createAccount", "org1", "cmsfin001", "nonfungible"
   • "createAccount", "org1", "cmsrsk001", "nonfungible"

   
   {
       "chaincode": "{{bc_nft_chaincode_name}}", //Smartcontract name
       "args": [
           "createAccount", "org1","cmsleg001","nonfungible" //Method, OrgID, UserID, fungible for FT / nonfungible for NFT
       ],
       "timeout": 60000,
       "sync": true
   }
   

3. تعيين المستخدم المسموح له بنسخ الرموز المميزة، في هذه الحالة يعني كتابة رمز مميز تكوين مجلد جديد للاحتفاظ بمجموعة جديدة من المستندات، بحيث يمكنك تحديد أي من المستخدمين الثلاثة الموجودين (cmsleg001 أو cmsfin001 أو cmsrsk001) يمكنهم تنفيذ هذه الإجراءات، وبالنسبة لهؤلاء المستخدمين، يتم تنفيذ الطلب الخطوة 2: AddRole من مجموعة Postman.

   
   {
       "chaincode": "{{bc_nft_chaincode_name}}", //Smartcontract name
       "args": [
           "addRole", //Method name
           "minter","org1","cmsleg001" //Role, OrgId, UserID
           ],
       "timeout": 60000,
       "sync": true
   }