امتداد Enumerable

ما امتداد Enumerable؟

امتداد Enumerable هو جزء اختياري من معيار الرموز غير القابلة للاستبدال ERC-721، يتيح للعقود الذكية وتطبيقات العملات المشفرة اكتشاف معرّفات توكنات NFT عبر استعلامات الفهرسة على السلسلة.

يُعرف عادةً باسم الواجهة

أو اسم التنفيذ .

يعرّف مواصفات ERC-721 الرسمية هذا الامتداد بأنه وسيلة تتيح للعقد نشر القائمة الكاملة لتوكنات NFT الصالحة ومعرّفات التوكنات التي يملكها كل عنوان.

يضيف الامتداد ثلاث دوال هي

و و.

وتكمّل هذه الدوال واجهة الملكية والتحويل الأساسية في ERC-721.

ولا تحل محل دوال مثل

و و و.

امتداد Enumerable اختياري، لذلك يمكن لعقد NFT أن يكون متوافقاً بالكامل مع ERC-721 من دون دعمه.

لماذا يُسمى Enumerable؟

يعني تعداد مجموعة تحديد عناصرها واحداً تلو الآخر باستخدام فهرس أو طريقة منظمة أخرى.

تستطيع واجهة ERC-721 الأساسية إخبار التطبيق بمالك معرّف توكن معروف.

كما يمكنها إخبار التطبيق بعدد توكنات NFT التي يملكها عنوان ما.

لكن الواجهة الأساسية لا توفر دالة مباشرة على السلسلة لاكتشاف كل معرّفات التوكنات الموجودة أو كل معرّفات التوكنات التي يملكها مالك معين.

يسد امتداد Enumerable هذه الفجوة بإضافة إمكانية الوصول المفهرس إلى المجموعة بأكملها وإلى ممتلكات كل مالك.

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

ما معرّف واجهة امتداد Enumerable؟

معرّف واجهة ERC-165 لامتداد ERC-721 Enumerable هو

.

ينبغي للعقد المتوافق أن يعيد

عند استدعاء دالة بهذه القيمة.

يتيح معيار اكتشاف الواجهات ERC-165 للتطبيقات سؤال العقد الذكي عن الواجهات التي يعلن تنفيذها.

لواجهة ERC-721 الأساسية معرّف واجهة منفصل، لذا يمكن للتطبيق اختبار دعم الواجهة الأساسية وامتداد Enumerable كلٌّ على حدة.

يجب على العقد الذي ينفذ امتداد Enumerable أن ينفذ أيضاً واجهة ERC-721 الأساسية.

تحسّن الاستجابة الإيجابية لاكتشاف الواجهة التحقق من التوافق، لكنها لا تثبت صحة التنفيذ أو أمانه أو نزاهته.

الدوال التي يضيفها امتداد Enumerable

لا يضيف امتداد Enumerable سوى ثلاث دوال استعلام عامة.

تعيد دالة

عدد توكنات NFT الصالحة التي يتتبعها العقد حالياً.

تعيد دالة

معرّف توكن من قائمة التوكنات على مستوى العقد.

وتعيد دالة

معرّف توكن من الممتلكات الحالية لمالك واحد.

الدوال الثلاث كلها دوال عرض للقراءة فقط وفق الواجهة القياسية.

ولا يضيف الامتداد دوالاً جديدة للتحويل أو الموافقة أو السك أو الحرق أو البيانات الوصفية أو الإتاوات.

دالة totalSupply

تعيد دالة

عدد توكنات NFT الصالحة التي يملكها حالياً عنوان غير العنوان الصفري.

وهي تعرض المعروض النشط حالياً، لا الحد الأقصى الممكن للمعروض.

فعلى سبيل المثال، قد يعرض العقد إجمالي معروض قدره 8,000 مع احتفاظه بصلاحية سك المزيد من توكنات NFT لاحقاً.

إذا أُحرق توكن NFT وأُزيل من الملكية الصالحة، فعادةً ما ينخفض إجمالي المعروض المعروض.

لذلك لا تساوي قيمة

بالضرورة عدد توكنات NFT التي سُكّت على الإطلاق.

كما أنها لا تثبت وجود حد أقصى دائم للمجموعة.

يتعين على المستخدمين فحص منطق السك والصلاحيات المميزة للتحقق من ادعاءات الندرة.

دالة tokenByIndex

تعيد دالة

معرّف التوكن الموجود في موضع محدد ضمن التعداد على مستوى العقد.

يبدأ الفهرس من صفر.

يجب أن يكون الفهرس صالحاً وأقل من القيمة التي تعيدها

.

إذا كان إجمالي المعروض 100، فالفهارس الصالحة هي من صفر إلى 99.

ويفشل الاستعلام باستخدام الفهرس 100 أو أي رقم أكبر.

ليس مطلوباً أن يساوي معرّف التوكن المعاد الفهرس.

فقد يعيد الفهرس صفر معرّف التوكن 500، بينما يعيد الفهرس واحد معرّف التوكن 12.

يجب ألا تفترض التطبيقات مطلقاً أن معرّفات التوكنات متتابعة لمجرد أن فهارس التعداد متتابعة.

دالة tokenOfOwnerByIndex

تعيد دالة

معرّف توكن واحد يملكه عنوان محدد.

يبدأ الفهرس من صفر ويجب أن يكون أقل من نتيجة

لذلك المالك.

إذا كان عنوان ما يملك ثلاثة توكنات NFT، ففهارس المالك الصالحة هي صفر وواحد واثنان.

ويجب أن تفشل الدالة عندما يكون الفهرس خارج رصيد المالك الحالي.

كما يجب أن تفشل عندما يكون المالك المُمرر هو العنوان الصفري.

تتيح الدالة للتطبيقات على السلسلة وخارجها عرض توكنات NFT الخاصة بعنوان ما من دون البحث في كل معرّف توكن محتمل.

كيف تعمل الدوال الثلاث معاً؟

يمكن للتطبيق استدعاء

لمعرفة عدد توكنات NFT الصالحة الموجودة حالياً.

بعد ذلك، يمكنه استدعاء

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

وبالنسبة إلى كل معرّف توكن معاد، يمكنه استدعاء

لتحديد المالك الحالي.

ولعرض ممتلكات عنوان معين، يمكن للتطبيق استدعاء

ثم الاستعلام عن لكل فهرس صالح للمالك.

تتيح هذه العملية اكتشاف التوكنات عبر دوال موحدة على السلسلة.

قد تتطلب المجموعات الكبيرة عدداً كبيراً من استدعاءات RPC، لذا تستخدم تطبيقات الإنتاج عادةً الصفحات أو تجميع الطلبات أو التخزين المؤقت أو فهرسة الأحداث.

ترتيب التعداد غير مضمون

لا تحدد مواصفات ERC-721 ترتيباً مطلوباً للفرز في

أو .

ولا يلزم أن يتبع الترتيب المعاد معرّف التوكن أو وقت السك أو التحويل أو الندرة أو البيانات الوصفية أو مدة الملكية.

يمكن للعقد تغيير موضع توكن عند تحويل توكن آخر أو حرقه.

يجب ألا تتعامل التطبيقات مع فهرس التعداد على أنه معرّف دائم.

معرّف التوكن هو المعرّف الثابت ضمن العقد، أما الفهرس فليس سوى موضع بحث حالي.

إذا أرادت واجهة ما نتائج مرتبة، فعليها فرز معرّفات التوكنات المعادة خارج السلسلة وفق قواعدها الخاصة.

التعداد باستخدام Swap-and-Pop

يستخدم أحد أساليب التنفيذ الشائعة تقنية تسمى Swap-and-Pop لإزالة معرّفات التوكنات بكفاءة من المصفوفات.

عند إزالة توكن، يضع التنفيذ التوكن الأخير في المصفوفة في موضع التوكن المُزال السابق.

ثم يحذف العنصر الأخير من المصفوفة.

يمنع ذلك الحاجة إلى تحريك كل التوكنات التالية، ويحافظ على انخفاض نسبي في تعقيد الإزالة.

لكن هذه الطريقة تغيّر ترتيب معرّفات التوكنات المتبقية.

يستخدم تنفيذ OpenZeppelin ERC721Enumerable الحالي هذه الطريقة للفهرسة العامة وفهرسة المالكين.

لذلك ينبغي للتطبيق إعادة بدء التصفح بالصفحات أو تسوية النتائج بعناية إذا تغيرت الملكية أثناء عملية تعداد طويلة.

مثال على التعداد على مستوى المجموعة

لنفترض أن عقد ERC-721 يعرض إجمالي معروض قدره أربعة.

يستدعي التطبيق

باستخدام الفهارس صفر وواحد واثنين وثلاثة.

يعيد العقد معرّفات التوكنات 18 و42 و7 و105.

أصبح التطبيق يعرف الآن مجموعة معرّفات التوكنات الصالحة كاملة، رغم أن المعرّفات غير متتابعة.

ويمكنه استدعاء

و لكل معرّف لعرض الملكية والبيانات الوصفية.

إذا أُحرق معرّف التوكن 42 لاحقاً، فقد يعيد التعداد العام 18 و105 و7، لأن التنفيذ قد ينقل العنصر الأخير إلى الموضع الذي أُزيل منه التوكن.

هذا التغيير صحيح لأن المعيار لا يضمن ترتيب التعداد.

مثال على تعداد توكنات المالك

لنفترض أن أليس تملك معرّفات التوكنات 9 و30 و88 في عقد NFT يدعم التعداد.

تعيد دالة

في العقد القيمة ثلاثة لعنوان أليس.

يستعلم التطبيق عن فهارس المالك صفر وواحد واثنين باستخدام

.

يعيد العقد معرّفات توكنات أليس الثلاثة.

ثم تحول أليس معرّف التوكن 30 إلى بوب.

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

ينبغي للتطبيق قراءة الرصيد المحدّث قبل تكرار تعداد توكنات المالك.

امتداد Enumerable مقارنةً بمعيار ERC-721 الأساسي

يوفر معيار ERC-721 الأساسي الملكية والتحويلات والموافقات والأحداث وفحوصات المستلمين الآمنة.

ويمكنه الإجابة عن سؤالَي ما إذا كان معرّف توكن معروف موجوداً ومن يملكه.

لكنه لا يوفر قائمة موحدة على السلسلة بكل معرّفات التوكنات.

يضيف امتداد Enumerable طبقة اكتشاف هذه التوكنات.

يمكن لمجموعة لا تدعم التعداد تحويل توكنات NFT بشكل طبيعي والعمل مع المحافظ المتوافقة مع ERC-721.

ولا يعني غياب التعداد أن توكن NFT غير صالح أو غير متوافق.

ينبغي للتطبيقات دعم المجموعات التي تدعم التعداد والتي لا تدعمه إذا كانت تريد توافقاً واسعاً مع ERC-721.

امتداد Enumerable مقارنةً بامتداد Metadata

يحدد امتداد Enumerable معرّفات التوكنات الموجودة وممتلكات المالكين.

أما امتداد Metadata فيوفر اسم المجموعة ورمزها وURI التوكن.

لا يصف التعداد الصورة أو السمات أو العنوان أو المحتوى الخارجي المرتبط بتوكن NFT.

ولا يوفر دعم البيانات الوصفية قائمة كاملة بالتوكنات.

يمكن للعقد تنفيذ أي من الامتدادين أو كليهما أو عدم تنفيذ أي منهما مع الاستمرار في تنفيذ وظائف ERC-721 الأساسية.

ينبغي للتطبيقات التحقق من كل واجهة على حدة.

امتداد Enumerable مقارنةً بدالة totalSupply وحدها

تضيف بعض عقود NFT دالة

مخصصة من دون تنفيذ امتداد Enumerable كاملاً.

وجود اسم دالة مألوف لا يثبت دعم

أو .

وقد يختلف أيضاً معنى دالة المعروض المخصصة عن تعريف التعداد في ERC-721.

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

ينبغي للتطبيقات استخدام ERC-165 لاختبار الواجهة الكاملة للتعداد بدلاً من الاعتماد على محدد دالة واحد.

لماذا تستهلك إضافة Enumerable مزيداً من الغاز؟

يتطلب التعداد من العقد صيانة هياكل تخزين إضافية.

يخزن التنفيذ الشائع مصفوفة تضم جميع معرّفات التوكنات الموجودة.

كما يخزن قائمة توكنات مفهرسة لكل مالك وخرائط تسجل مواضع التوكنات.

يجب أن تضيف عملية السك التوكن الجديد إلى القائمة العامة وقائمة المالك معاً.

ويجب أن يزيل التحويل التوكن من قائمة المالك السابق ويضيفه إلى قائمة المالك الجديد.

كما يجب أن يزيل الحرق التوكن من قائمة المالك والقائمة العامة.

تزيد عمليات الكتابة الإضافية هذه تكلفة الغاز للمعاملات التي تغير الحالة.

تشير إرشادات تنفيذ ERC-721 الحالية إلى أن الامتداد يُستبعد في كثير من الأحيان لأنه يضيف عبئاً كبيراً على الغاز.

هل استعلامات التعداد مجانية؟

يمكن للمستخدم استدعاء دوال العرض عبر نقطة نهاية RPC من دون إرسال معاملة إلى البلوكشين.

في هذه الحالة لا تُدفع رسوم غاز على السلسلة، لأن العقدة تحاكي القراءة محلياً.

لكن العقدة لا تزال تنفذ عمليات حسابية، وقد تفرض حدوداً لمعدل الطلبات أو قيوداً عليها.

إذا استدعى عقد ذكي دالة تعداد أثناء معاملة، تستهلك العملية غاز المعاملة.

وقد تصبح الحلقة التي تستعلم على السلسلة عن مئات أو آلاف فهارس التوكنات باهظة جداً إلى حد يتعذر معه إكمالها.

ينبغي للمطورين عدم الخلط بين القراءة خارج السلسلة من دون رسوم غاز وبين القدرة غير المحدودة على الحساب على السلسلة.

الحلقات وحدود غاز الكتلة

ينبغي للعقد الذكي تجنب الدوال التي تغير الحالة وتدور على كل توكن NFT في مجموعة أو كل توكن NFT يملكه عنوان غير محدد القيود.

قد يزداد عدد التكرارات بمرور الوقت إلى أن تتجاوز المعاملة حد غاز الكتلة.

تحذر وثائق أمان Solidity من أن الحلقات المعتمدة على التخزين قد تجعل عمليات العقد غير قابلة للإكمال في نهاية المطاف.

لا تنشئ دوال العرض المستدعاة خارج السلسلة رسوم المعاملة نفسها، لكنها قد تثقل أيضاً كاهل مزود RPC.

ينبغي للتطبيقات استخدام صفحات محدودة أو استعلامات فهرس فردية أو فهرسة خارج السلسلة لمجموعات البيانات الكبيرة.

فهرسة الأحداث خارج السلسلة كبديل

يصدر كل عقد ERC-721 متوافق أحداث

عند سك توكنات NFT أو تحويلها أو حرقها.

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

ويمثل السك عادةً تحويلاً من العنوان الصفري.

ويمثل الحرق عادةً تحويلاً إلى العنوان الصفري.

أما التحويلات العادية فتنقل الملكية بين عنوانين غير صفريين.

تتجنب فهرسة الأحداث عمليات الكتابة الإضافية إلى التخزين التي يتطلبها التعداد على السلسلة.

كما تدعم البحث والفرز والتصفية وتقسيم النتائج إلى صفحات بكفاءة أكبر للمجموعات الكبيرة.

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

امتداد Enumerable مقارنةً بفهرسة الأحداث

يوفر التعداد على السلسلة للعقود الذكية وصولاً موحداً ومباشراً إلى فهارس التوكنات.

أما فهرسة الأحداث فتوفر اكتشافاً أغنى وأكثر قابلية للتوسع خارج السلسلة.

يفيد التعداد عندما يحتاج عقد ذكي آخر إلى التحقق من معرّفات التوكنات أو اختيارها من دون الاعتماد على قاعدة بيانات خارجية.

وتكون فهرسة الأحداث عادةً أكثر عملية لواجهات المحافظ وصفحات المجموعات والتحليلات والبحث التاريخي.

يمكن للمشروع دعم الطريقتين معاً.

يعتمد الخيار الأنسب على ما إذا كانت إمكانية الاكتشاف على السلسلة تستحق الغاز الإضافي المدفوع عند كل عملية سك أو تحويل أو حرق.

هل يوفر التعداد تقسيم النتائج إلى صفحات؟

لا يعرّف الامتداد دالة تعيد صفحة من معرّفات التوكنات.

بل يوفر معرّف توكن واحداً لكل استعلام عن فهرس.

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

فعلى سبيل المثال، قد تستعلم الصفحة الأولى عن الفهارس من صفر إلى 49، والصفحة الثانية عن الفهارس من 50 إلى 99.

يجب على التطبيق مراعاة التغيرات في المعروض والترتيب أثناء الانتقال بين الصفحات.

قد يؤدي تحويل أو حرق إلى نقل التوكنات بين الفهارس، ما يسبب فقدان معرّف أو تكراره في عملية تصفح طويلة.

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

هل يسرد التعداد جميع المالكين؟

يسرد الامتداد معرّفات التوكنات على مستوى المجموعة ومعرّفات التوكنات التي يملكها مالك معروف.

لكنه لا يوفر دالة تعيد كل عناوين المالكين الفريدة.

يمكن للتطبيق استنتاج المالكين باستدعاء

لكل معرّف توكن أو بمعالجة أحداث التحويل.

قد يظهر المالك نفسه مرات كثيرة لأن العنوان الواحد يمكن أن يمتلك عدة توكنات NFT.

لذلك، عادةً ما يكون إنشاء قائمة حاملي التوكنات الفريدين مهمة فهرسة خارج السلسلة.

هل يثبت التعداد أصالة التوكن؟

لا، فالتعداد لا يعرض سوى معرّفات التوكنات التي يتتبعها عقد ذكي معين.

يمكن لأي شخص نشر عقد ERC-721 يدعم التعداد بأسماء أو صور أو رموز أو بيانات وصفية منسوخة.

تظل شبكة البلوكشين وعنوان العقد الكامل جزءين أساسيين من هوية توكن NFT.

ولا يثبت تنفيذ واجهة التعداد بشكل صحيح أن الجهة المصدرة تملك العمل الفني أو تتحكم في الأصل المزعوم أو تتصرف بنزاهة.

ينبغي للمستخدمين التحقق من العقد عبر معلومات موثوقة عن المشروع ومراجعة صلاحياته بأنفسهم.

هل تثبت totalSupply الندرة؟

لا يثبت عدد المعروض الحالي وجود حد أقصى دائم للمعروض.

فقد يحتوي العقد على دالة سك عامة أو دور سك للمسؤول أو نظام سك عبر جسر أو صلاحية ترقية.

وقد يكون من الممكن سك معرّف توكن لا يملكه أحد حالياً في وقت لاحق.

كما يمكن للعقود القابلة للترقية تغيير قواعد المعروض بعد النشر.

ينبغي للمستخدمين فحص الشفرة البرمجية ونموذج التحكم في الوصول قبل الاعتماد على ادعاء الندرة.

يسهّل التعداد الاستعلام عن المعروض الحالي، لكنه لا يفرض الوعود الاقتصادية.

السك والتعداد

عند سك توكن NFT جديد، يجب على التنفيذ الداعم للتعداد إضافة معرّف التوكن إلى الفهرس العام وفهرس المالك الأول.

ثم يرتفع إجمالي المعروض بمقدار واحد.

يمكن أن يظهر معرّف التوكن في أي فهرس عام صالح يسمح به التنفيذ.

لا تفرض سياسة السك المتتابع بقاء فهرس التعداد مساوياً لمعرّف التوكن.

يجب أن يحدّث منطق السك المخصص كل هياكل التعداد المطلوبة باتساق.

قد يؤدي التحديث غير المكتمل إلى اختلاف الأرصدة وسجلات الملكية وإجمالي المعروض ونتائج التعداد.

التحويلات والتعداد

لا يغير التحويل عادةً إجمالي المعروض.

بل يزيل معرّف التوكن من تعداد المالك السابق ويضيفه إلى تعداد المستلم.

وتظل قائمة التوكنات العامة عادةً محتفظة بمعرّف التوكن نفسه.

قد تتغير مواضع الفهارس الخاصة بالمالك أثناء عملية الإزالة.

تتطلب التحويلات الذاتية، التي يكون فيها المرسل والمستلم العنوان نفسه، تنفيذاً دقيقاً.

تعالج التطبيقات التي خضعت للمراجعة هذه الحالة من دون إزالة التوكن أو تكراره على نحو خاطئ.

الحرق والتعداد

يزيل حرق التوكن من ملكية ERC-721 الصالحة.

ويزيل التنفيذ الداعم للتعداد معرّف التوكن المحروق من قائمة المالك والقائمة العامة.

وينخفض إجمالي المعروض.

ولا ينبغي استخدام فهارس المالك والفهارس العامة القديمة للتوكن.

قد تنتقل توكنات أخرى إلى تلك المواضع عند الإزالة باستخدام Swap-and-Pop.

ينبغي للتطبيقات التاريخية استخدام الأحداث بدلاً من التعداد الحالي عندما تحتاج إلى سجل توكنات NFT المحروقة.

التوافق مع السك الدفعي

تدعم بعض تطبيقات ERC-721 السك الدفعي المضغوط أو المتتابع أثناء إنشاء العقد.

قد تحسب هذه الأنظمة الملكية من دون تسجيل كل توكن عبر منطق تحديث التعداد المعتاد.

يحذر تنفيذ OpenZeppelin الحالي من أن امتداد السك المتتابع يتعارض مع

، وينبغي عدم دمجهما.

كما يرفض تنفيذ التعداد الحالي مسار تحديث الأرصدة الدفعي غير المدعوم.

ينبغي للمطورين ألا يجمعوا بين امتدادات لمجرد أن كل واحد منها يعمل مستقلاً.

يجب مراجعة الوراثة والتخزين والأحداث والأرصدة وسلوك خطافات التحديث معاً.

التعداد والعقود القابلة للترقية

يمكن لعقد NFT قابل للترقية إضافة المنطق أو تعديله بعد النشر إذا سمح نظام الحوكمة بذلك.

وتتطلب إضافة التعداد بعد وجود عدد كبير من توكنات NFT عناية خاصة.

فقد يبدأ تخزين التعداد الجديد فارغاً رغم أن العقد الأساسي يتتبع بالفعل آلاف التوكنات.

قد تكون هناك حاجة إلى عملية ترحيل لملء الفهارس العامة وفهارس المالكين.

وقد تتجاوز حلقات الترحيل الكبيرة على السلسلة حدود الغاز.

كما يمكن لأخطاء تخطيط التخزين إفساد بيانات الملكية أو الموافقات الموجودة.

ينبغي لمسؤولي الترقية استخدام إجراءات ترحيل مختبرة ومعاملات محدودة ومراجعة أمنية مستقلة.

التعداد ومنطق balanceOf المخصص

يعتمد تعداد المالك على دقة معلومات رصيد ERC-721.

قد يتعارض الامتداد الذي يحسب

بطريقة مخصصة أو مضغوطة مع فهارس المالك المخزنة.

تحذر إرشادات التنفيذ الحالية تحديداً من احتمال عدم توافق الامتدادات التي تستخدم منطقاً مخصصاً للأرصدة مع التعداد.

يجب على المطورين التأكد من أن كل عملية سك وتحويل وحرق تحدّث أعداد الملكية والفهارس عبر مسارات برمجية متوافقة.

فالعقد الذي يعرض رصيداً للمالك قدره خمسة، لكنه لا يخزن سوى أربعة معرّفات توكنات مفهرسة، عقد غير متسق داخلياً.

مخاطر الأمان للتطبيقات المتكاملة

ينبغي للتطبيق التحقق من دعم التعداد قبل استدعاء دوال الامتداد.

وعليه التعامل مع أخطاء تجاوز حدود الفهارس بدلاً من افتراض صلاحية فهرس سبق رصده.

كما يجب ألا يعتمد على ترتيب التعداد في حسابات الندرة أو الأولوية أو الحسابات المالية.

وينبغي له الحماية من النتائج المكررة أو المفقودة إذا تغيرت الحالة أثناء تقسيم النتائج إلى صفحات.

وعليه أيضاً التحقق من أن كل معرّف توكن معاد يتبع العقد والشبكة المتوقعين.

قد تحتاج القرارات عالية القيمة إلى لقطة متسقة للكتلة ومستوى نهائية مناسب.

اتساق بيانات RPC

قد تعيد نقطة نهاية RPC بيانات التعداد من كتلة حديثة أو آمنة أو نهائية أو تاريخية، بحسب الشبكة وإعدادات الطلب.

قد تنتج عن استدعاءين أُجريا عند ارتفاعي كتلة مختلفين قائمتان مختلفتان للمعروض أو المالكين.

قد يظهر توكن NFT نُقل حديثاً ضمن مالكين مختلفين في مصادر بيانات غير متزامنة.

ينبغي للتطبيقات تسجيل رقم الكتلة المستخدم في استعلامات التعداد المتعددة كلما كان الاتساق مهماً.

ويمكن للأنظمة الحيوية مقارنة عدة عقد أو تشغيل عقدة يجري التحقق منها بصورة مستقلة.

يقلل التعداد الاعتماد على واجهة API خاصة بالمجموعة، لكنه لا يلغي جميع اعتبارات الثقة بنظام RPC.

فوائد امتداد Enumerable

يوفر الامتداد طريقة موحدة لاكتشاف جميع معرّفات التوكنات الحالية.

ويتيح لعقد ذكي آخر الاستعلام عن ممتلكات مالك من توكنات NFT من دون فهرس خارجي.

كما يوفر دالة قياسية للمعروض الحالي.

وقد يبسّط التعامل مع المجموعات الصغيرة وألعاب البلوكشين وأنظمة العضوية والتطبيقات التي تتطلب اختيار التوكنات مباشرة.

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

قيود امتداد Enumerable

يزيد الامتداد تكاليف الغاز عند السك والتحويل والحرق.

ولا يضمن ثبات ترتيب التوكنات.

ولا يوفر وظائف مدمجة لتقسيم النتائج إلى صفحات أو فرزها أو تصفيتها أو تعداد حامليها.

كما يعرض التوكنات الحالية لا سجلاً تاريخياً كاملاً.

وقد لا يتوافق مع السك الدفعي المضغوط أو أنظمة الأرصدة المخصصة.

وتظل الحلقات الكبيرة على السلسلة مقيدة بحدود غاز المعاملة.

ولا يوفر الامتداد أيضاً بيانات وصفية أو إتاوات أو أسعاراً أو إثباتاً للأصالة أو ضماناً لحد المعروض.

متى ينبغي للمشروع استخدام التعداد؟

قد يستفيد المشروع من التعداد عندما تحتاج العقود الذكية إلى اكتشاف معرّفات التوكنات مباشرةً على السلسلة.

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

قد تستخدمه لعبة عندما يحتاج منطق العقد إلى اختيار أحد توكنات NFT الخاصة باللاعب حسب الفهرس.

وقد يستخدمه عقد عضوية عندما تحتاج عملية على السلسلة إلى فحص توكنات العضوية الحالية لحاملها.

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

متى قد يتجنب المشروع التعداد؟

قد تتجنب مجموعة NFT كبيرة التعداد لخفض تكلفة كل عملية سك وتحويل وحرق.

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

قد تستخدم أنظمة السك الدفعي المضغوط نماذج ملكية لا تعمل بكفاءة مع تخزين التعداد القياسي.

وقد لا يستفيد مشروع لا يحتاج مطلقاً إلى عرض التوكنات على السلسلة كثيراً من دفع تكلفة الفهارس الدائمة عليها.

ينبغي أن يستند القرار إلى متطلبات التطبيق الفعلية، لا إلى افتراض أن كل امتداد اختياري ضروري.

كيفية تنفيذ الامتداد للمطورين

ينبغي للمطورين البدء بتنفيذ ERC-721 قابل للتعداد، خضع للمراجعة وتستمر صيانته.

وعليهم التأكد من أن

يعيد .

يجب أن يحدّث كل مسار للسك والتحويل والحرق التعداد العام وتعداد المالكين على نحو صحيح.

كما يجب التحقق من عدم تعارض الامتدادات المخصصة مع الملكية والأرصدة والسك الدفعي والتغليف والإيقاف والترقيات.

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

ينبغي لاختبارات الثوابت التحقق من أن

يساوي عدد التوكنات القابلة للتعداد عالمياً.

كما ينبغي أن تتحقق من أن عدد التوكنات القابلة للتعداد لكل مالك يساوي نتيجة

.

كيفية تحقق المستخدمين من دعم التعداد

تتمثل الخطوة الأولى في التحقق من عنوان عقد NFT وشبكة البلوكشين.

والخطوة الثانية هي استدعاء

بالقيمة .

والخطوة الثالثة هي التأكد من دعم واجهة ERC-721 الأساسية أيضاً.

والخطوة الرابعة هي مقارنة

بعينة صغيرة من الفهارس الصالحة.

والخطوة الخامسة هي مقارنة نتيجة

لمالك ما بمعرّفات التوكنات التي يعيدها تعداد المالك.

يمكن لهذه الفحوص اكتشاف التناقضات الواضحة، لكنها لا تغني عن مراجعة العقد بالكامل.

أخطاء شائعة في امتداد Enumerable

من الأخطاء الشائعة افتراض أن كل عقد ERC-721 يدعم التعداد.

ومنها أيضاً التعامل مع فهرس التعداد على أنه معرّف توكن دائم.

والخطأ الثالث هو افتراض ظهور معرّفات التوكنات بترتيب رقمي أو وفق ترتيب سكها.

والخطأ الرابع هو اعتبار

حداً دائماً للمعروض.

والخطأ الخامس هو إنشاء حلقة على مجموعة غير محدودة داخل معاملة تغير الحالة.

والخطأ السادس هو تجاهل تغير الترتيب أثناء تقسيم النتائج إلى صفحات.

والخطأ السابع هو افتراض أن دالة

المخصصة تثبت دعم الامتداد كاملاً.

والخطأ الثامن هو الجمع بين تطبيقات غير متوافقة للسك الدفعي والتعداد.

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

والخطأ العاشر هو اعتبار دعم واجهة التعداد دليلاً على أصالة مجموعة NFT أو قيمتها.

الأسئلة الشائعة

ما المقصود بامتداد Enumerable في الكريبتو؟

يشير عادةً إلى امتداد ERC-721 الاختياري الذي يتيح للتطبيقات عرض جميع معرّفات توكنات NFT الحالية ومعرّفات التوكنات التي يملكها عنوان محدد.

هل امتداد Enumerable مطلوب في ERC-721؟

لا، يمكن لعقد NFT أن يتوافق مع ERC-721 الأساسي من دون دعم التعداد.

ما معرّف واجهة امتداد Enumerable؟

معرّف واجهة ERC-165 هو

.

ما الدوال التي يضيفها الامتداد؟

يضيف

و و.

ما القيمة التي تعيدها totalSupply؟

تعيد عدد توكنات NFT الصالحة حالياً التي يتتبعها العقد.

هل تعرض totalSupply الحد الأقصى الممكن للمعروض؟

لا، فهي تعرض المعروض الحالي ولا تثبت استحالة السك مستقبلاً.

ما القيمة التي تعيدها tokenByIndex؟

تعيد معرّف التوكن المخزن عند فهرس تعداد عام محدد.

ما القيمة التي تعيدها tokenOfOwnerByIndex؟

تعيد معرّف توكن واحداً يملكه عنوان محدد عند فهرس محدد للمالك.

هل تبدأ فهارس التعداد من صفر؟

نعم، تبدأ الفهارس الصالحة من صفر وتنتهي قبل الموضع الذي يساوي المعروض أو الرصيد ذي الصلة بواحد.

هل فهرس التعداد هو نفسه معرّف التوكن؟

لا، فالفهرس موضع مؤقت في القائمة، بينما يحدد معرّف التوكن توكن NFT ضمن العقد.

هل تعاد معرّفات التوكنات بترتيب رقمي؟

لا، لا يفرض المعيار ترتيباً معيناً للتعداد.

هل يمكن أن يتغير ترتيب التعداد؟

نعم، قد تغير التحويلات وعمليات الحرق مواضع الفهارس، خاصةً في التطبيقات التي تستخدم الإزالة بطريقة Swap-and-Pop.

هل يؤدي حرق NFT إلى خفض totalSupply؟

نعم، يزيل العقد الذي ينفذ التعداد على نحو صحيح توكن NFT المحروق ويخفض إجمالي المعروض الحالي.

هل يغير تحويل NFT قيمة totalSupply؟

لا، يغير التحويل العادي تعداد المالك، لكنه لا يغير عدد توكنات NFT الموجودة.

لماذا يُعد الامتداد مكلفاً؟

لأنه يتطلب عمليات كتابة إضافية إلى التخزين لصيانة فهارس التوكنات العامة والخاصة بالمالكين عند السك والتحويل والحرق.

هل استدعاءات التعداد مجانية؟

لا تتطلب قراءات RPC خارج السلسلة دفع غاز على السلسلة، لكن استدعاءات العقود الذكية أثناء المعاملة تستهلك الغاز.

هل يمكن للعقد المرور على كل توكنات NFT القابلة للتعداد؟

يمكنه محاولة ذلك، لكن الحلقة غير المحدودة على السلسلة قد تتجاوز في نهاية المطاف حد غاز الكتلة.

هل يوفر الامتداد تقسيم النتائج إلى صفحات؟

لا، تنشئ التطبيقات الصفحات من خلال الاستعلام عن نطاقات مختارة من الفهارس.

هل يسرد الامتداد كل حاملي توكنات NFT؟

لا، فهو يسرد معرّفات التوكنات عالمياً ولدى مالك معروف، لكنه لا يعيد قائمة فريدة بكل عناوين المالكين.

هل يمكن لفهرسة الأحداث أن تحل محل التعداد؟

نعم، يستطيع فهرس خارج السلسلة إعادة تكوين المعروض والملكية من أحداث Transfer في ERC-721.

هل يشمل التعداد البيانات الوصفية لتوكنات NFT؟

لا، توفر البيانات الوصفية عبر امتداد ERC-721 اختياري منفصل.

هل يثبت التعداد أصالة NFT؟

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

هل يمكن إضافة التعداد بعد النشر؟

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

هل يتوافق ERC721Enumerable مع كل امتدادات ERC-721؟

لا، فقد يتعارض السك الدفعي المضغوط وتطبيقات الأرصدة المخصصة مع تخزين التعداد القياسي.

متى يكون امتداد Enumerable مفيداً أكثر؟

يكون مفيداً أكثر عندما تحتاج العقود أو التطبيقات إلى وصول موحد على السلسلة إلى قائمة التوكنات الحالية أو معرّفات توكنات مالك ما.

الخاتمة

امتداد Enumerable ميزة اختيارية في ERC-721 تتيح اكتشاف معرّفات توكنات NFT عبر استعلامات موحدة على السلسلة.

معرّف واجهته هو

.

ويضيف الامتداد

و و.

يمكن لهذه الدوال عرض المجموعة الحالية ومعرّفات التوكنات التي يملكها عنوان معروف.

فهارس التعداد ليست معرّفات دائمة، ولا يضمن المعيار ترتيبها.

كما لا يوفر الامتداد بيانات وصفية أو إتاوات أو قوائم حاملي التوكنات أو سجلات تاريخية أو إثباتاً لوجود معروض ثابت.

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

غالباً ما تستخدم التطبيقات الكبيرة أحداث ERC-721 Transfer والفهرسة خارج السلسلة بدلاً من دفع تكلفة التعداد الكامل على السلسلة.

يجب على المطورين الذين ينفذون الامتداد إبقاء جميع هياكل الملكية والأرصدة والفهارس متزامنة في كل مسارات تغيير الحالة.

وينبغي للمستخدمين التحقق بصورة مستقلة من دعم الواجهة وهوية العقد وصلاحية السك وأذونات الترقية والمعروض الحالي.

يساعد فهم امتداد Enumerable مستخدمي الكريبتو على التمييز بين اكتشاف توكنات NFT مباشرةً على السلسلة وبين البيانات الوصفية وسجل الملكية والندرة وخدمات الفهرسة خارج السلسلة.