सुरक्षा फ़्रेमवर्क

सुरक्षा स्थिति एक अनुच्छेद में

संदर्भ टोकन में एक चोक पॉइंट (_update), एक निश्चित मूल्यांकन क्रम, पूरे हुक अनुक्रम के चारों ओर रीएंट्रेंसी लॉक, भूमिका-आधारित प्राधिकार जो कभी बैलेंस से व्युत्पन्न नहीं होता, ERC-7201 स्टोरेज, और एक छोटी सतह है: ERC-1155 के अतिरिक्त आठ बाह्य स्थिति-परिवर्तनकारी फ़ंक्शन। सबसे शक्तिशाली क्षमताएँ — फ़्रीज़ करना, बलपूर्वक ट्रांसफ़र, हुक प्रशासन, अपग्रेड — अलग-अलग भूमिकाएँ हैं जो मल्टीसिग और टाइमलॉक के लिए अभिप्रेत हैं, और उनका प्रत्येक उपयोग एक इवेंट है।

इनवेरिएंट

थ्रेट मॉडल

कर्ता और क्षमताएँ

परिदृश्य

दुर्भावनापूर्ण या बग-युक्त हुक (सेवा-अवरोध)। जो हुक हमेशा अस्वीकार करता है वह टोकन के सभी ट्रांसफ़र ब्लॉक कर देता है; जो check में रिवर्ट करता है वह भी यही करता है। शमन: HOOK_ADMIN_ROLE किसी भी समय कोई भी हुक हटा सकती है (क्रम बना रहता है); जाँच के दौरान PAUSER_ROLE सब कुछ रोक सकती है; बलपूर्वक ट्रांसफ़र फिर भी चलते हैं, इसलिए प्रवर्तन खोता नहीं। पंजीकरण ERC-165 समर्थन और गैर-शून्य फ़्लैग सत्यापित करता है, और EOA को अस्वीकार करता है। अनुशंसा: पंजीकरण से पहले हुक का ऑडिट करें; संख्या कम रखें; प्रशासक को टाइमलॉक के पीछे रखें ताकि हुक परिवर्तन प्रभावी होने से पहले दिखाई दें।

हुक रीएंट्रेंसी। हुक की onExecuted वापस safeTransferFrom को कॉल करती है। शमन: लॉक; कॉल ARexReentrantCall के साथ रिवर्ट होती है। ध्यान दें कि ERC-1155 का रिसीवर कॉलबैक (onERC1155Received) लॉक जारी होने के बाद चलता है, जैसा हर ERC-1155 टोकन में होता है; तब तक टोकन की स्थिति अंतिम होती है।

रिसीवर कॉलबैक में ऑपरेशन संदर्भ। कोई कॉन्ट्रैक्ट प्राप्तकर्ता onERC1155Received के भीतर से ट्रांसफ़र या बर्न शुरू करता है। वह नेस्टेड कॉल अपने data के साथ एक OP_TRANSFER या OP_BURN है, न कि उस ऑपरेशन का हिस्सा जिसने टोकन पहुँचाए। 2.0.0-alpha.2 तक संदर्भ टोकन बाहरी ऑपरेशन को स्टोरेज में तब तक रखता था जब तक बाहरी कॉल लौट न जाए, इसलिए forcedTransfer के बाद की नेस्टेड कॉल OP_FORCED_TRANSFER के रूप में चलती थी (पॉज़, पात्रता और फ़्रीज़ किए गए बैलेंस को छोड़ते हुए), और transform के बाद की कॉल OP_TRANSFORM के रूप में, जिसे केवल OP_TRANSFER पर रोक लगाने वाले हुक जाने देते हैं। शमन: _update किसी भी जाँच या बाहरी कॉल से पहले ऑपरेशन संदर्भ को पढ़ता और साफ़ करता है, इसलिए कॉलबैक से की गई कॉल का मूल्यांकन उसी के रूप में होता है; OpContext.test.js ऐसे प्राप्तकर्ता का उपयोग करता है जो अपने कॉलबैक के भीतर से ट्रांसफ़र और बर्न करता है।

री-बैचिंग द्वारा डिलीवरी। transform के दोनों लेग हुक को OP_TRANSFORM के साथ चलाते हैं। यदि कोई धारक किसी अन्य खाते में री-बैच कर पाता, तो वस्तुएँ उन हुक की जाँचों के बिना हाथ बदल लेतीं जो केवल OP_TRANSFER पर रोक लगाते हैं, जैसे बिक्री से पहले आवश्यक सत्यापन या किसी डिलीवरी के लिए लॉक की गई इकाइयाँ। शमन: TRANSFORMER_ROLE के बिना, री-बैच केवल तब अनुमत है जब to == from; री-लॉट की गई वस्तुएँ किसी अन्य धारक तक एक सामान्य ट्रांसफ़र के माध्यम से पहुँचती हैं जो हर ट्रांसफ़र नियम चलाता है (ADR-007, 2026-10-20 को संशोधित)।

बर्न या री-लॉटिंग द्वारा लॉक से बचना। प्रति बैच id रखी गई हुक स्थिति किसी लॉट के आउटपुट तक नहीं पहुँचती। जो हुक इकाइयाँ लॉक करता है और केवल OP_TRANSFER जाँचता है, वह धारक को लॉक की गई इकाइयाँ बर्न करने से, या उन्हें उसी खाते में एक नई id में री-लॉट करने से नहीं रोकता जिसे लॉक कवर नहीं करता। शमन: DeliveryHook किसी भी ऐसे बर्न या transform इनपुट लेग को IN_TRANSIT के साथ अस्वीकार करता है जो बैलेंस को लॉक की गई इकाइयों से नीचे ले जाए; फ़ोर्स्ड ट्रांसफ़र असीमित रहते हैं, और ज़ब्ती के बाद हुक रिवर्ट होने के बजाय एक कोड लौटाता है। इकाइयाँ आरक्षित करने वाले हुक को OP_TRANSFER के साथ-साथ OP_BURN और OP_TRANSFORM भी जाँचने चाहिए।

समझौता-ग्रस्त प्रवर्तन कुंजी। जिसके पास ENFORCER_ROLE है वह कोई भी टोकन ट्रांसफ़र कर सकता है। शमन: प्रलेखित प्रक्रिया (न्यायालय आदेश, गिरवी करार, प्रतिबंध सूचना) के साथ मल्टीसिग; प्रत्येक कार्रवाई ForcedTransfer/Frozen इमिट करती है; हुक ट्रांसफ़र डेटा में आदेश संदर्भ अनिवार्य कर सकते हैं (OP_FORCED_TRANSFER हुक से मुक्त नहीं है)। गैर-तात्कालिक प्रवर्तन के लिए टाइमलॉक पर विचार करें।

समझौता-ग्रस्त अपग्रेडर। पूर्ण समझौता। शमन: मल्टीसिग के साथ टाइमलॉक; CI में OpenZeppelin अपग्रेड वैलिडेशन; लेआउट संबंधी दुर्घटनाओं से बचने के लिए ERC-7201 स्टोरेज।

स्टेटस का दुरुपयोग। STATUS_ROLE दूसरों द्वारा धारित बैच को रिटायर कर सकती है। यह जान-बूझकर है — वेयरहाउस, निरीक्षक या नियामक द्वारा किसी लॉट को अनुपयुक्त घोषित करना — और धारकों को इसका प्रकटीकरण किया जाना अनिवार्य है। शमन: किसी जवाबदेह संस्था को सौंपें; प्रत्येक परिवर्तन कारण सहित एक इवेंट है।

जारीकर्ता धोखाधड़ी। ISSUER_ROLE ऐसा बैच बना सकती है जो भौतिक रूप से मौजूद नहीं है। टोकन इसे रोक नहीं सकता; वह इसे जिम्मेदार पक्ष से जोड़े जाने योग्य बनाता है (issuer, originRef, metadataHash) और AttestationHook के माध्यम से ट्रांसफ़र से पहले स्वतंत्र पक्षों (वेयरहाउस, निरीक्षक, रजिस्ट्री) के एटेस्टेशन की अपेक्षा करने देता है।

उद्गम संदर्भ में छिपा स्थान। originRef में प्लॉट निर्देशांकों का हैश, जियोहैश या कोई अन्य एन्कोडिंग अनाम दिखती है, परंतु उसे किसी अनुमानित प्लॉट से दोबारा परिकलित किया जा सकता है, और उसे लेजर से कभी मिटाया नहीं जा सकता। शमन: originRef साक्ष्य का एक संदर्भ या एक यादृच्छिक संदर्भ है; जियोलोकेशन ऑफ़-चेन रहता है (EUDR के लिए, EU Information System में)। ADR-019 (प्रस्तावित) के साथ रखा गया मसौदा "कभी स्थान से व्युत्पन्न नहीं" को MUST बनाता है; यह पहले से ADR-008 का निर्णय था।

असत्यापित अपस्ट्रीम संदर्भ। किसी अन्य टोकन के बैच से बना बैच अपने मेटाडेटा की upstream सूची में उसका नाम देता है। यह डाउनस्ट्रीम जारीकर्ता का दावा है: वह ऐसे बैच का नाम दे सकता है जो उसके पास कभी नहीं था, या ऐसे बैच को छोड़ सकता है जो था। शमन: इंडेक्सर, ऑडिटर और रिकॉल टूल प्रत्येक संदर्भ को अपस्ट्रीम टोकन से मिलाते हैं (बैच मौजूद है, मेटाडेटा हैश मेल खाता है, और ट्रांज़ैक्शन हैश दिए जाने पर जारीकर्ता को ट्रांसफ़र हुआ था) और जिनकी जाँच नहीं हो सकी उन्हें असत्यापित दिखाते हैं।

मेटाडेटा प्रतिस्थापन। setBatchMetadata हैश और URI बदलती है। शमन: भूमिका-गेटेड; BatchMetadataUpdated और URI इवेंट इतिहास रखते हैं; पुराने दस्तावेज़ पुराने हैश के विरुद्ध सत्यापन-योग्य रहते हैं।

transferCheck की फ़्रंट-रनिंग। प्री-फ़्लाइट जाँच ट्रांज़ैक्शन के निष्पादन से पहले पुरानी पड़ सकती है (हुक की स्थिति बदल जाती है)। ट्रांज़ैक्शन पुनः मूल्यांकन करता है; सबसे बुरी स्थिति सटीक कोड के साथ रिवर्ट है।

हुक के माध्यम से गैस ग्रीफ़िंग। प्रत्येक हुक प्रति चरण प्रति प्रभावित आईडी एक बाह्य कॉल जोड़ता है। असीमित लूप वाला हुक ट्रांसफ़र को वहन-योग्य नहीं रहने देता। शमन: हुक लेखन नियम (सीमाबद्ध check), पंजीकरण से पहले समीक्षा।

अपग्रेड-योग्य हुक पर विश्वास। प्रॉक्सी के पीछे डिप्लॉय किया गया हुक टोकन में किसी बदलाव के बिना ट्रांसफ़र नीति बदल सकता है। शमन: हुक प्रशासक कुंजियों को HOOK_ADMIN_ROLE जितनी ही सावधानी से संभालें; प्रोडक्शन के लिए इम्यूटेबल हुक को प्राथमिकता दें।

एक्सेस नियंत्रण मॉडल

OpenZeppelin AccessControl जिसमें टोकन पर आठ भूमिकाएँ और एटेस्टेशन रजिस्ट्री पर एक है; DEFAULT_ADMIN_ROLE उन सभी का प्रशासन करती है। अनुशंसित प्रोडक्शन लेआउट:

initialize सुविधा के लिए सब कुछ एक प्रशासक को दे देता है; डिप्लॉयमेंट चेकलिस्ट प्रोडक्शन से पहले पुनर्वितरण अनिवार्य करती है।

प्रवर्तन और पॉज़ शब्दार्थ

• पॉज़ मिंट, ट्रांसफ़र, बर्न और ट्रांसफ़ॉर्म को ब्लॉक करता है; यह बलपूर्वक ट्रांसफ़र को ब्लॉक नहीं करता, ताकि किसी घटना के दौरान वैध आदेश निष्पादित किया जा सके।
• बलपूर्वक ट्रांसफ़र canSend/canReceive और फ़्रीज़-बैलेंस जाँच को छोड़ देते हैं, फ़्रीज़ की गई राशि को शेष मात्रा तक घटा देते हैं, और फिर भी हुक को OP_FORCED_TRANSFER के साथ चलाते हैं। संदर्भ हुक उस ऑपरेशन के लिए OK लौटाते हैं; प्रवर्तन को शासित करने वाला हुक data में आदेश संदर्भ अनिवार्य कर सकता है।
• फ़्रीज़ बैलेंस से अधिक हो सकता है (ERC-7943), ताकि ग्रहणाधिकार भावी जमा को भी कवर कर सके।

मानक में क्षमताएँ, प्रोफ़ाइल में नीति

ADR-019 (प्रस्तावित) हर प्रवर्तन सुविधा के बीच से एक रेखा खींचता है। मानक तय करता है कि क्या मौजूद है और वह क्या गारंटी देता है: भूमिकाएँ, इवेंट, पॉज़ क्या रोकता है, कोड AREX:PAUSED और AREX:SANCTIONED, एटेस्टेशन कौन निरस्त कर सकता है, और गोपनीयता नियम। प्रति क्षेत्राधिकार और प्रति संगठन रखी गई, और किसी विनियम की तरह तिथियों के साथ संस्करणित, नीति प्रोफ़ाइल यह बताती है कि प्रत्येक क्षमता का उपयोग कौन और किन शर्तों पर कर सकता है:

तब कानून में बदलाव एक प्रोफ़ाइल अपडेट बन जाता है, कभी कोई नया कॉन्ट्रैक्ट या मानक का नया संस्करण नहीं।

अपग्रेड सुरक्षा

• UUPS; _authorizeUpgrade UPGRADER_ROLE द्वारा गेटेड।
• ERC-7201 नेमस्पेस्ड स्टोरेज स्ट्रक्ट; केवल-जोड़ने योग्य।
• OpenZeppelin अपग्रेड प्लगइन वैलिडेशन टेस्ट में चलते हैं और किसी भी अपग्रेड ट्रांज़ैक्शन से पहले CI में चलने चाहिए।
• प्रति-फ़ाइल optimizer.runs = 1 सेटिंग इम्प्लीमेंटेशन को EIP-170 के भीतर रखती है; इसे सीमा से ऊपर धकेलने वाला परिवर्तन कंपाइल समय पर चेतावनी के साथ और डिप्लॉयमेंट पर रिवर्ट के साथ विफल होता है।

डिपेंडेंसी और बिल्ड सुरक्षा

• OpenZeppelin Contracts और Contracts-Upgradeable 5.3.0 पर पिन किए गए; लॉकफ़ाइल कमिट की गई; CI npm ci का उपयोग करता है।
• Solidity 0.8.22, viaIR, EVM paris (ट्रांज़िएंट स्टोरेज पर कोई निर्भरता नहीं, उन चेन पर भी डिप्लॉय-योग्य जिन्होंने Cancun नहीं अपनाया)।
• कोई बाह्य लाइब्रेरी लिंक नहीं की गई; UUPS प्रॉक्सी के बाहर कोई delegatecall नहीं।

ऑडिट स्थिति

• संदर्भ कार्यान्वयन, हुक और एक्सटेंशन पर 46 टेस्ट ऊपर के प्रत्येक इनवेरिएंट को कवर करते हैं, जिनमें एक सीडेड यादृच्छिक इनवेरिएंट रन शामिल है।
• गैस और आकार रिपॉज़िटरी की स्क्रिप्टों द्वारा मापे जाते हैं।
• ARexToken, ARexAttestations और संदर्भ हुक का तृतीय-पक्ष ऑडिट प्रोडक्शन एंकर के लिए और ERC सबमिट करने के लिए एक घोषित पूर्व-शर्त है (देखें भावी विकास)।
• पाइपलाइन इनवेरिएंट का औपचारिक सत्यापन रोडमैप पर है; इनवेरिएंट इतने छोटे हैं कि उन्हें प्रॉपर्टी के रूप में कहा जा सकता है।

सुरक्षा परामर्श

2.0.0-alpha.3 ने 2.0.0-alpha.2 का स्थान लिया है। तैनात टोकन प्रॉक्सी को UPGRADER_ROLE के माध्यम से नए कार्यान्वयन पर अपग्रेड किया जाता है; स्टोरेज लेआउट अपरिवर्तित है। DeliveryHook अपग्रेड योग्य नहीं है: नया संस्करण तैनात करें, उसे registerHook से पंजीकृत करें, पुराने को removeHook से हटाएँ, और सक्रिय डिलीवरी को फिर से शेड्यूल करें, क्योंकि उनके लॉक पुराने हुक के स्टोरेज में रहते हैं। जो इंटीग्रेशन सीधे किसी क्रेता के खाते में विभाजन या मर्ज करते हैं, उन्हें उसी खाते में री-लॉट करके फिर ट्रांसफ़र करना होगा, या TRANSFORMER_ROLE वाले खाते का उपयोग करना होगा। मानक के इंटरफ़ेस नहीं बदलते।

शेष जोखिम जिन्हें मानक दूर नहीं करता

• लॉट का भौतिक अस्तित्व और गुणवत्ता एटेस्ट की जाती है, सिद्ध नहीं; टोकन दावों को जिम्मेदार पक्ष से जोड़े जाने योग्य बनाता है, सत्य नहीं।
• ऑफ़-चेन मेटाडेटा की उपलब्धता चुने गए स्टोरेज पर निर्भर करती है; हैश अखंडता की गारंटी देता है, उपलब्धता की नहीं।
• हुक और मॉड्यूल गवर्नेंस उतना ही अच्छा है जितनी उसे नियंत्रित करने वाली कुंजियाँ।