Ongeza kusaini kwa wazi kwenye itifaki yako ukitumia ERC-7730

Unyonyaji mwingi mkubwa wa Ethereum ulikuwa na hatua ya mwisho sawa: mtumiaji kuidhinisha muamala ambao hakuweza kuuelewa kwa maana. Mikoba ya maunzi huonyesha data za mwito za heksadesimali ghafi, na mbaya zaidi inakulazimisha kuwasha kusaini bila kuona. Mikoba ya programu huonyesha sehemu zilizosimbuliwa, lakini tu wakati inatambua mkataba. Wakati haitambui, iwe kwa sababu itifaki ni mpya, programu imedukuliwa, au kifaa hakiko mtandaoni, watumiaji husaini bila kuona.

ERC-7730 (opens in a new tab) inafafanua umbizo la kawaida la JSON la kuelezea kile ambacho miito ya utendaji ya mkataba wako inamaanisha.

Mkoba unaotumia ERC-7730 husoma kifafanuzi chako na kuonyesha:

Badilishano
Tuma: 1,000 USDC
Pokea kima cha chini: 0.42 WETH
Itifaki: Uniswap V3

Au sentensi moja iliyoundwa inayosomeka na binadamu na mawakala vile vile:

Badilishano la 1,000 USDC kwa angalau 0.42 WETH

Badala ya kiteuzi cha utendaji na orodha ya thamani ghafi za nambari kamili.

Huku ni kusaini kwa wazi (opens in a new tab) — "Kile Unachokiona Ndicho Unachosaini." Mafunzo haya yanakuongoza katika kuandika kifafanuzi cha mkataba wako mwenyewe, kukithibitisha kwa zana rasmi ya CLI, na kukiwasilisha kwenye sajili iliyo wazi.

Mahitaji ya awali

• Uelewa wa Solidity na ABI za mkataba mahiri
• Mkataba mahiri uliosambazwa wenye ABI iliyothibitishwa (uthibitishaji wa Sourcify (opens in a new tab) unahitajika kabla ya kifafanuzi kukubaliwa kwenye sajili)
• Python 3.12+ kwa ajili ya CLI ya uthibitishaji
• Ujuzi wa kimsingi wa JSON

Kifafanuzi cha ERC-7730 ni nini?

Kifafanuzi ni faili moja la JSON lenye sehemu tatu:

Kwa sababu kifafanuzi kimetenganishwa na mkataba wenyewe, unaweza kuongeza usaidizi wa kusaini kwa wazi kwenye itifaki yoyote iliyopo bila usambazaji upya. Mikoba hurejesha vifafanuzi kutoka kwenye sajili na kuvitumia wakati wa kusaini.

Hatua ya 1: Unda kiunzi cha faili

Unda faili linaloitwa calldata-<contractname>-<descriptorversion>.json. Kiambishi awali cha calldata- huiambia sajili kuwa kifafanuzi hiki kinashughulikia miito ya utendaji wa mkataba, tofauti na eip712- kwa ujumbe wa data iliyochapwa. descriptorversion huiambia sajili toleo la faili la kifafanuzi, 0 kwa chaguo-msingi ikiwa hakuna toleo lililotolewa.

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

Hatua ya 2: Andika sehemu ya muktadha

Sehemu ya context hufunga kifafanuzi kwenye usambazaji mmoja au zaidi wa mkataba. Mikoba hutumia hii kulinganisha muamala unaoingia na kifafanuzi sahihi.

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

Sehemu za muktadha

• context.$id — Kitambulisho cha kipekee cha hati hii ya kifafanuzi au usanidi wa usambazaji.
• contract.deployments — Seti ya usambazaji ambayo kifafanuzi hiki kinatumika.
• deployments[].chainId — Kitambulisho cha mnyororo wa EVM kwa usambazaji. Jumuisha kila mnyororo ambapo mkataba wako umesambazwa.
• deployments[].address — Anwani ya mkataba ambayo mikoba inapaswa kuhusisha na kifafanuzi hiki. Tumia anwani ya utekelezaji inayoshikilia mantiki ya utekelezaji.

Hatua ya 3: Andika sehemu ya data fafanuzi

Sehemu ya data fafanuzi hutoa maelezo yanayosomeka na binadamu kuhusu mradi na mkataba uliofafanuliwa na faili hili. Mikoba inaweza kutumia maelezo haya kuonyesha majina ya itifaki, viungo, na maelezo mengine ya kimuktadha wakati wa kusaini.

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

Sehemu za data fafanuzi

• owner — Mradi, itifaki, shirika, au mtunzaji anayehusika na kifafanuzi hiki.
• info.url — URL ya mradi au nyaraka rasmi ambayo mikoba inaweza kuonyesha kwa watumiaji kwa muktadha wa ziada.
• contractName — Jina la mkataba au utekelezaji lililofafanuliwa na faili hili, kwa kawaida linalolingana na msimbo wa chanzo uliothibitishwa au ABI.

Ikiwa faili lako la ERC-7730 linafafanua mkataba wa ERC-20, unapaswa kuongeza kipengee cha tokeni pia.

Hatua ya 4: Andika sehemu ya miundo ya onyesho

Kipengee cha display.formats hulinganisha sahihi za utendaji na maagizo ya kusaini yanayosomeka na binadamu. Hivi ndivyo mikoba inavyoonyesha utendaji wako kwa watumiaji kabla ya kuidhinisha muamala!

Kila ufunguo ni kipande cha ABI kinachosomeka na binadamu — sahihi ya utendaji ikijumuisha majina ya vigezo na aina za vigezo kama zinavyoonekana kwenye ABI yako.

Mfano: Kufafanua badilishano la tokeni

"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"
          }
        }
      ]
    }
  }
}

Sehemu za onyesho

• intent — (Inahitajika) Maelezo mafupi, yanayofaa mtumiaji ya kitendo, kama vile "Badilishano".
• interpolatedIntent — (Inapendekezwa) Kiolezo cha sentensi tajiri zaidi kinachopachika thamani za sehemu zilizoumbizwa, kama vile "Swap {amountIn} for at least {amountOutMin}". Jumuisha hii pamoja na intent ili kutoa kifafanuzi kinachofaa zaidi kwa mtumiaji ambacho mikoba inaweza kuchagua kuonyesha ikizingatiwa vikwazo vyovyote vya onyesho.
• fields — (Inahitajika) Orodha iliyopangwa ya sehemu za muamala ambazo mikoba inapaswa kuonyesha kwa watumiaji.

  • path — (Inahitajika) Rejeleo la data ya muamala. #.fieldName inaelekeza kwenye kigezo cha data za mwito kilichosimbuliwa kwa jina kwenye ABI. @.value inarejelea thamani ya ETH iliyotumwa na muamala.

  • label — (Inahitajika) Lebo inayosomeka na binadamu inayoonyeshwa kando ya thamani.

  • format — (Inapendekezwa) Hudhibiti jinsi thamani inapaswa kuonyeshwa. Miundo ya kawaida ni pamoja na:

    • tokenAmount
    • addressName
    • date

    Tumia raw wakati hakuna uumbizaji wa ziada unaohitajika. Baadhi ya miundo inakubali usanidi wa ziada wa params. Kwa mfano:

    • tokenAmount inaweza kutumia tokenPath kutambua ni anwani gani ya tokeni inatoa desimali na data fafanuzi ya tiki.
    • date inaweza kutumia encoding kuelezea jinsi muhuri wa muda umesimbwa.

    Ikiwa muundo uliochaguliwa hauhitaji maelezo ya ziada, ondoa params.

Kifafanuzi kamili

{
  "$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"
            }
          }
        ]
      }
    }
  }
}

Hatua ya 5: Wasilisha kwenye sajili

Sajili ya ERC-7730 (opens in a new tab) ni hazina wazi inayosimamiwa na Taasisi ya Ethereum kama msimamizi asiyeegemea upande wowote. Mtu yeyote yuko huru kuiga na kujisimamia mwenyewe — mikoba huamua kwa uhuru ni matukio gani ya sajili wanayoamini.

1. Chepua hazina kwenye GitHub
2. Unda folda kwenye registry/<your-project-name>/
3. Weka faili lako ndani yake: registry/myproject/calldata-mycontract-0_0.json
4. Sasisha sehemu ya $schema kwa njia ya jamaa inayotumika ndani ya hazina: "../../specs/erc7730-v2.schema.json"
5. Fungua ombi la kuvuta (pull request)

Unapofungua PR, CI huendesha uthibitishaji wa skema kiotomatiki, hukagua kuwa sahihi za utendaji hutoa viteuzi halali, huthibitisha anwani ya mkataba imethibitishwa kwenye Sourcify, na kuashiria kutokubaliana kwa ABI. Matokeo ya ukaguzi yanaonekana ndani ya PR. Watunzaji wa sajili hukagua mawasilisho kwa vifafanuzi vilivyoundwa vibaya au vinavyoweza kuwa na nia mbaya. Kujumuishwa kwenye sajili hakumaanishi ukaguzi au uidhinishaji.

Nini kinatokea baada ya kuunganisha?

Vifafanuzi vyote kwenye sajili viko wazi kwa wakaguzi. Baada ya PR yako kuunganishwa, mkaguzi yeyote anaweza kukagua kifafanuzi chako na kuchapisha uthibitisho wa kificho (chini ya ERC-8176 (opens in a new tab)) kuthibitisha usahihi wake.

Ishara hizi za uthibitisho huruhusu mikoba kutumia sera zao wenyewe za uaminifu — kifafanuzi chenye uthibitisho mwingi wa kujitegemea hubeba uzito zaidi kuliko kile kisicho na uthibitisho. Unaweza kufikia jumuiya ya wakaguzi kupitia clearsigning.org (opens in a new tab).

Mikoba huchagua ni sajili gani itakayounga mkono. Pindi kifafanuzi chako kikiwa kwenye sajili, mikoba inayotumia ERC-7730 itaanza kukichukua ikiwa kiko kwenye sajili yao na itaonyesha data inayosomeka na binadamu wakati watumiaji wanaingiliana na mkataba wako.

Usomaji zaidi

• Uainishaji wa ERC-7730 (opens in a new tab)
• Sajili ya ERC-7730 (opens in a new tab)
• clearsigning.org (opens in a new tab) — zana, hali ya mfumo wa ikolojia, na utawala
• Uthibitishaji wa mkataba wa Sourcify (opens in a new tab)
• Mpango wa Usalama wa Trilioni ya Dola (opens in a new tab)

Ukurasa ulisasishwa mwisho: 12 Mei 2026

p (opens in a new tab)

m (opens in a new tab)

Tazama wachangiaji