إضافة التوقيع الواضح إلى بروتوكولك باستخدام ⁦ERC-7730⁩

كانت الخطوة الأخيرة في معظم اختراقات إيثيريوم الكبرى هي نفسها: مستخدم يوافق على معاملة لا يمكنه فهمها بشكل هادف. تعرض محافظ الأجهزة بيانات الاستدعاء (calldata) السداسية العشرية الخام، والأسوأ من ذلك أنها تجبرك على تفعيل التوقيع الأعمى. تعرض محافظ البرامج الحقول التي تم فك تشفيرها، ولكن فقط عندما تتعرف على العقد. وعندما لا تتعرف عليه، سواء لأن البروتوكول جديد، أو التطبيق مخترق، أو الجهاز غير متصل بالإنترنت، يقوم المستخدمون بالتوقيع بشكل أعمى.

يحدد ERC-7730 (opens in a new tab) تنسيق JSON قياسيًا لوصف معنى استدعاءات دوال العقد الخاص بك.

تقرأ المحفظة التي تدعم ERC-7730 الواصف الخاص بك وتعرض:

مبادلة
إرسال: 1,000 USDC
الحد الأدنى للاستلام: 0.42 WETH
البروتوكول: يونيسواب V3

أو جملة واحدة مركبة قابلة للقراءة من قبل البشر والوكلاء على حد سواء:

مبادلة 1,000 USDC مقابل 0.42 WETH على الأقل

بدلاً من محدد الدالة وقائمة من القيم الصحيحة الخام.

هذا هو التوقيع الواضح (opens in a new tab) — "ما تراه هو ما توقعه". يرشدك هذا البرنامج التعليمي خلال كتابة واصف للعقد الخاص بك، والتحقق من صحته باستخدام أداة سطر الأوامر (CLI) الرسمية، وإرساله إلى السجل المفتوح.

المتطلبات الأساسية

• الإلمام بلغة Solidity وواجهات التطبيق الثنائية (ABI) للعقود الذكية
• عقد ذكي منشور مع واجهة تطبيق ثنائية (ABI) تم التحقق منها (التحقق من Sourcify (opens in a new tab) مطلوب قبل قبول الواصف في السجل)
• Python 3.12+ لأداة سطر الأوامر (CLI) الخاصة بالتحقق
• معرفة أساسية بتنسيق JSON

ما هو واصف ⁦ERC-7730⁩؟

الواصف هو ملف JSON واحد يتكون من ثلاثة أقسام:

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

الخطوة 1: إنشاء هيكل الملف

قم بإنشاء ملف باسم calldata-<contractname>-<descriptorversion>.json. تخبر البادئة calldata- السجل أن هذا الواصف يغطي استدعاءات دوال العقد، على عكس eip712- لرسائل البيانات المكتوبة. يخبر descriptorversion السجل بإصدار ملف الواصف، وهو 0 افتراضيًا إذا لم يتم توفير إصدار.

{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v2.schema.json",
  "context": {},
  "metadata": {},
  "display": {
    "formats": {}
  }
}

الخطوة 2: كتابة قسم السياق

يربط قسم context الواصف بعملية نشر عقد واحدة أو أكثر. تستخدم المحافظ هذا لمطابقة معاملة واردة مع الواصف الصحيح.

"context": {
  "$id": "uniswap-v3-router-mainnet",
  "contract": {
    "deployments": [
      { "chainId": 1, "address": "0xYourContractAddressOnMainnet" },
      { "chainId": 137, "address": "0xYourContractAddressOnPolygon" }
    ]
  }
}

حقول السياق

• context.$id — معرف فريد لمستند الواصف هذا أو تكوين النشر.
• contract.deployments — مجموعة عمليات النشر التي ينطبق عليها هذا الواصف.
• deployments[].chainId — معرف سلسلة آلة إيثيريوم الافتراضية (EVM) لعملية النشر. قم بتضمين كل سلسلة يتم نشر العقد الخاص بك عليها.
• deployments[].address — عنوان العقد الذي يجب أن تربطه المحافظ بهذا الواصف. استخدم عنوان التنفيذ الذي يحتوي على منطق التنفيذ.

الخطوة 3: كتابة قسم البيانات الوصفية

يوفر قسم البيانات الوصفية معلومات قابلة للقراءة البشرية حول المشروع والعقد الموصوف في هذا الملف. قد تستخدم المحافظ هذه المعلومات لعرض أسماء البروتوكولات والروابط والتفاصيل السياقية الأخرى أثناء التوقيع.

"metadata": {
  "owner": "Example Swap Protocol",
  "info": { "url": "https://example.xyz" },
  "contractName": "SwapRouter"
}

حقول البيانات الوصفية

• owner — المشروع أو البروتوكول أو المؤسسة أو المشرف المسؤول عن هذا الواصف.
• info.url — عنوان URL أساسي للمشروع أو الوثائق قد تعرضه المحافظ للمستخدمين للحصول على سياق إضافي.
• contractName — اسم العقد أو التنفيذ الموصوف في هذا الملف، والذي يتطابق عادةً مع الكود المصدري الذي تم التحقق منه أو واجهة التطبيق الثنائية (ABI).

إذا كان ملف ERC-7730 الخاص بك يصف عقد ERC-20، فيجب عليك إضافة كائن رمز مميز أيضًا.

الخطوة 4: كتابة قسم تنسيقات العرض

يعين كائن display.formats تواقيع الدوال إلى تعليمات توقيع قابلة للقراءة البشرية. هذه هي الطريقة التي تعرض بها المحافظ الدالة الخاصة بك للمستخدمين قبل أن يوافقوا على معاملة!

كل مفتاح عبارة عن جزء من واجهة التطبيق الثنائية (ABI) قابل للقراءة البشرية — توقيع الدالة بما في ذلك أسماء المعلمات وأنواعها تمامًا كما تظهر في واجهة التطبيق الثنائية (ABI) الخاصة بك.

مثال: وصف مبادلة رمز مميز

"display": {
  "formats": {
    "swapExactTokensForTokens(uint256 amountIn,uint256 amountOutMin,address[] path,address to,uint256 deadline)": {
      "intent": "Swap",
      "interpolatedIntent": "Swap {amountIn} for at least {amountOutMin}",
      "fields": [
        {
          "path": "#.amountIn",
          "label": "Send",
          "format": "tokenAmount",
          "params": {
            "tokenPath": "#.path[0]"
          }
        },
        {
          "path": "#.amountOutMin",
          "label": "Receive minimum",
          "format": "tokenAmount",
          "params": {
            "tokenPath": "#.path[1]"
          }
        },
        {
          "path": "#.to",
          "label": "Recipient",
          "format": "addressName",
          "params": {
            "types": ["eoa", "contract"],
            "sources": ["local", "ens"]
          }
        },
        {
          "path": "#.deadline",
          "label": "Expires",
          "format": "date",
          "params": {
            "encoding": "timestamp"
          }
        }
      ]
    }
  }
}

حقول العرض

• intent — (مطلوب) وصف قصير وسهل الاستخدام للإجراء، مثل "مبادلة".
• interpolatedIntent — (موصى به) قالب جملة أكثر ثراءً يدمج قيم الحقول المنسقة، مثل "Swap {amountIn} for at least {amountOutMin}". قم بتضمين هذا بجانب intent لتوفير واصف أكثر سهولة في الاستخدام يمكن للمحافظ اختيار عرضه بناءً على أي قيود عرض.
• fields — (مطلوب) القائمة المرتبة لحقول المعاملة التي يجب أن تعرضها المحافظ للمستخدمين.

  • path — (مطلوب) إشارة إلى بيانات المعاملة. يشير #.fieldName إلى معلمة بيانات استدعاء (calldata) تم فك تشفيرها بالاسم الموجود في واجهة التطبيق الثنائية (ABI). يشير @.value إلى قيمة ETH المرسلة مع المعاملة.

  • label — (مطلوب) التسمية القابلة للقراءة البشرية المعروضة بجانب القيمة.

  • format — (موصى به) يتحكم في كيفية عرض القيمة. تشمل التنسيقات الشائعة:

    • tokenAmount
    • addressName
    • date

    استخدم raw عندما لا تكون هناك حاجة إلى تنسيق إضافي. تقبل بعض التنسيقات تكوين params إضافي. على سبيل المثال:

    • يمكن لـ tokenAmount استخدام tokenPath لتحديد عنوان الرمز المميز الذي يوفر الخانات العشرية والبيانات الوصفية لرمز التداول.
    • يمكن لـ date استخدام encoding لوصف كيفية تشفير الطابع الزمني.

    إذا كان التنسيق المحدد لا يتطلب معلومات إضافية، فتجاهل params.

الواصف الكامل

{
  "$schema": "https://eips.ethereum.org/assets/eip-7730/erc7730-v2.schema.json",
  "context": {
    "$id": "uniswap-v3-router-mainnet",
    "contract": {
      "deployments": [
        {
          "chainId": 1,
          "address": "0xYourContractAddressOnMainnet"
        },
        {
          "chainId": 137,
          "address": "0xYourContractAddressOnPolygon"
        }
      ]
    }
  },
  "metadata": {
    "owner": "Example Swap Protocol",
    "info": {
      "url": "https://example.xyz"
    },
    "contractName": "SwapRouter"
  },
  "display": {
    "formats": {
      "swapExactTokensForTokens(uint256 amountIn,uint256 amountOutMin,address[] path,address to,uint256 deadline)": {
        "intent": "Swap",
        "interpolatedIntent": "Swap {amountIn} for at least {amountOutMin}",
        "fields": [
          {
            "path": "#.amountIn",
            "label": "Send",
            "format": "tokenAmount",
            "params": {
              "tokenPath": "#.path[0]"
            }
          },
          {
            "path": "#.amountOutMin",
            "label": "Receive minimum",
            "format": "tokenAmount",
            "params": {
              "tokenPath": "#.path[1]"
            }
          },
          {
            "path": "#.to",
            "label": "Recipient",
            "format": "addressName",
            "params": {
              "types": ["eoa", "contract"],
              "sources": ["local", "ens"]
            }
          },
          {
            "path": "#.deadline",
            "label": "Expires",
            "format": "date",
            "params": {
              "encoding": "timestamp"
            }
          }
        ]
      }
    }
  }
}

الخطوة 5: الإرسال إلى السجل

يعد سجل ⁦ERC-7730⁩ (opens in a new tab) مستودعًا مفتوحًا تستضيفه مؤسسة إيثيريوم كجهة راعية محايدة. يمكن لأي شخص استنساخه واستضافته ذاتيًا — وتقرر المحافظ بشكل مستقل مثيلات السجل التي تثق بها.

1. قم بعمل تفرع (Fork) للمستودع على GitHub
2. قم بإنشاء مجلد في registry/<your-project-name>/
3. ضع ملفك بداخله: registry/myproject/calldata-mycontract-0_0.json
4. قم بتحديث حقل $schema إلى المسار النسبي المستخدم داخل المستودع: "../../specs/erc7730-v2.schema.json"
5. افتح طلب سحب (Pull request)

عند فتح طلب السحب (PR)، يقوم التكامل المستمر (CI) تلقائيًا بتشغيل التحقق من صحة المخطط، ويتحقق من أن تواقيع الدوال تنتج محددات صالحة، ويؤكد أن عنوان العقد تم التحقق منه على Sourcify، ويشير إلى التناقضات في واجهة التطبيق الثنائية (ABI). تظهر نتائج الفحص مضمنة في طلب السحب. يقوم مشرفو السجل بفحص عمليات الإرسال بحثًا عن الواصفات المشوهة أو التي يحتمل أن تكون ضارة. الإدراج في السجل لا يعني التدقيق أو المصادقة.

ماذا يحدث بعد الدمج؟

جميع الواصفات في السجل مفتوحة للمدققين. بعد دمج طلب السحب (PR) الخاص بك، يمكن لأي مدقق مراجعة الواصف الخاص بك ونشر تصديق تشفيري (بموجب ERC-8176 (opens in a new tab)) يؤكد دقته.

تتيح إشارات التصديق هذه للمحافظ تطبيق سياسات الثقة الخاصة بها — فالواصف الذي يحتوي على تصديقات مستقلة متعددة يحمل وزنًا أكبر من الواصف الذي لا يحتوي عليها. يمكنك الوصول إلى مجتمع المدققين من خلال clearsigning.org (opens in a new tab).

تختار المحافظ السجل الذي ستدعمه. بمجرد وجود الواصف الخاص بك في السجل، ستبدأ المحافظ التي تدعم ERC-7730 في جلبه إذا كان موجودًا في سجلها وستعرض بيانات قابلة للقراءة البشرية عندما يتفاعل المستخدمون مع العقد الخاص بك.

قراءة إضافية

• مواصفات ⁦ERC-7730⁩ (opens in a new tab)
• سجل ⁦ERC-7730⁩ (opens in a new tab)
• clearsigning.org (opens in a new tab) — الأدوات، وحالة النظام البيئي، والحوكمة
• التحقق من العقود عبر Sourcify (opens in a new tab)
• مبادرة أمان التريليون دولار (opens in a new tab)

آخر تحديث للصفحة: 12 مايو 2026

p (opens in a new tab)

m (opens in a new tab)

عرض المساهمين