⁦ERC-7730⁩ کے ساتھ اپنے پروٹوکول میں واضح دستخط کرنا شامل کریں

ERC-7730

سیکیورٹی

دستخط کرنا

سمارٹ کنٹریکٹس

والیٹس

درمیانی

ہیسٹر بروکمین

۱۱ مئی، ۲۰۲۶

10 منٹ کی پڑھائی

زیادہ تر بڑے ایتھیریم حملوں کا آخری مرحلہ ایک ہی تھا: ایک صارف ایسی ٹرانزیکشن کو منظور کرنا جسے وہ بامعنی طور پر سمجھ نہیں سکتا تھا۔ ہارڈویئر والیٹس خام ہیکس کال ڈیٹا دکھاتے ہیں، اور اس سے بھی بدتر یہ کہ آپ کو بلائنڈ سائننگ (اندھا دستخط) آن کرنے پر مجبور کرتے ہیں۔ سافٹ ویئر والیٹس ڈی کوڈ شدہ فیلڈز دکھاتے ہیں، لیکن صرف اس وقت جب وہ کنٹریکٹ کو پہچانتے ہوں۔ جب وہ ایسا نہیں کرتے، چاہے اس کی وجہ یہ ہو کہ پروٹوکول نیا ہے، ایپ سے سمجھوتہ کیا گیا ہے، یا ڈیوائس آف لائن ہے، تو صارفین اندھے دستخط کرتے ہیں۔

ERC-7730 (opens in a new tab) ایک معیاری JSON فارمیٹ کی وضاحت کرتا ہے جو یہ بیان کرتا ہے کہ آپ کے کنٹریکٹ کی فنکشن کالز کا مطلب کیا ہے۔

ایک والیٹ جو ERC-7730 کو سپورٹ کرتا ہے وہ آپ کا ڈسکرپٹر پڑھتا ہے اور دکھاتا ہے:

تبادلہ
بھیجیں: 1,000 USDC
کم از کم وصول کریں: 0.42 WETH
پروٹوکول: یونی سویپ V3

یا ایک واحد تشکیل شدہ جملہ جو انسانوں اور ایجنٹس دونوں کے لیے پڑھنے کے قابل ہو:

کم از کم 0.42 WETH کے لیے 1,000 USDC کا تبادلہ کریں

فنکشن سلیکٹر اور خام انٹیجر ویلیوز کی فہرست کے بجائے۔

یہ واضح دستخط کرنا (opens in a new tab) ہے — "جو آپ دیکھتے ہیں وہی آپ دستخط کرتے ہیں۔" یہ ٹیوٹوریل آپ کو اپنے کنٹریکٹ کے لیے ڈسکرپٹر لکھنے، اسے آفیشل CLI ٹول کے ساتھ درست ثابت کرنے، اور اسے اوپن رجسٹری میں جمع کرانے کے عمل سے گزارتا ہے۔

پیشگی شرائط

Solidity اور سمارٹ کنٹریکٹ ABIs سے واقفیت
ایک تصدیق شدہ ABI کے ساتھ تعینات شدہ سمارٹ کنٹریکٹ (ڈسکرپٹر کو رجسٹری میں قبول کیے جانے سے پہلے Sourcify (opens in a new tab) کی تصدیق درکار ہے)
توثیق کرنے والے CLI کے لیے Python 3.12+
JSON کا بنیادی علم

ERC-7730 ڈسکرپٹر کیا ہے؟

ڈسکرپٹر ایک واحد JSON فائل ہے جس کے تین حصے ہوتے ہیں:

سیکشن	مقصد
`context`	ڈسکرپٹر کو چین ID اور پتہ کے ذریعے مخصوص کنٹریکٹ کی تعیناتیوں سے جوڑتا ہے
`metadata`	پروجیکٹ کا نام دیتا ہے اور دوبارہ استعمال کے قابل کنسٹنٹس کی وضاحت کرتا ہے
`display`	ہر فنکشن کے دستخط کو انسانی پڑھنے کے قابل لیبلز اور فیلڈ فارمیٹس سے میپ کرتا ہے

چونکہ ڈسکرپٹر خود کنٹریکٹ سے الگ ہوتا ہے، اس لیے آپ دوبارہ تعیناتی کے بغیر کسی بھی موجودہ پروٹوکول میں واضح دستخط کرنے کی سپورٹ شامل کر سکتے ہیں۔ والیٹس رجسٹری سے ڈسکرپٹرز بازیافت کرتے ہیں اور انہیں دستخط کرنے کے وقت استعمال کرتے ہیں۔

مرحلہ 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 چین ID۔ ہر اس چین کو شامل کریں جہاں آپ کا کنٹریکٹ تعینات ہے۔
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 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) ایک اوپن ریپوزٹری ہے جس کی میزبانی ایتھیریم فاؤنڈیشن ایک غیر جانبدار منتظم کے طور پر کرتی ہے۔ کوئی بھی اسے کلون کرنے اور خود میزبانی کرنے کے لیے آزاد ہے — والیٹس آزادانہ طور پر فیصلہ کرتے ہیں کہ وہ کن رجسٹری انسٹینسز پر بھروسہ کرتے ہیں۔

GitHub پر ریپوزٹری کو فورک کریں
registry/<your-project-name>/ پر ایک فولڈر بنائیں
اپنی فائل کو اس کے اندر رکھیں: registry/myproject/calldata-mycontract-0_0.json
$schema فیلڈ کو ریپو کے اندر استعمال ہونے والے متعلقہ پاتھ پر اپ ڈیٹ کریں: "../../specs/erc7730-v2.schema.json"
ایک پل ریکوئسٹ (pull request) کھولیں

جب آپ PR کھولتے ہیں، تو CI خود بخود سکیما کی توثیق چلاتا ہے، چیک کرتا ہے کہ فنکشن کے دستخط درست سلیکٹرز تیار کرتے ہیں، تصدیق کرتا ہے کہ کنٹریکٹ کا پتہ Sourcify پر تصدیق شدہ ہے، اور ABI کی تضادات کی نشاندہی کرتا ہے۔ چیک کے نتائج PR پر ان لائن ظاہر ہوتے ہیں۔ رجسٹری کے منتظمین خراب یا ممکنہ طور پر نقصان دہ ڈسکرپٹرز کے لیے جمع کرائی گئی درخواستوں کی جانچ پڑتال کرتے ہیں۔ رجسٹری میں شمولیت کا مطلب آڈٹ یا توثیق نہیں ہے۔

نوٹ: آپ کی PR قبول ہونے سے پہلے آپ کے کنٹریکٹ کی Sourcify پر تصدیق ہونی چاہیے۔ اگر اس کی ابھی تک تصدیق نہیں ہوئی ہے، تو پہلے تصدیق جمع کرائیں۔

ضم ہونے کے بعد کیا ہوتا ہے؟

رجسٹری میں موجود تمام ڈسکرپٹرز آڈیٹرز کے لیے کھلے ہیں۔ آپ کی 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)

صفحہ کی آخری اپ ڈیٹ: ۱۲ مئی، ۲۰۲۶