تخزين معاملات ETH الإصدار 2.5.0: سجل العناوين الذي تستضيفه بنفسك

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

تعد ETH Transactions Storage مفهرساً ذاتي الاستضافة يقرأ الكتل من عقدة Ethereum الخاصة بك، ويكتب تحويلات ETH الأصلية وطلبات تحويل ERC-20 في قاعدة بيانات PostgreSQL الخاصة بك، ويقدم سجل العناوين عبر واجهة برمجة تطبيقات REST للقراءة فقط. لا يوجد تتبع للبيانات، ولا حسابات طرف ثالث، ولا يوجد سوى اتصالين خارجيين: العقدة وقاعدة البيانات التي تقوم بتهيئتها. البنية بسيطة ومباشرة: عقدة Ethereum ← ethsync.py ← PostgreSQL ← PostgREST ← تطبيقك. تعمل هذه الأداة مع Geth وNethermind وBesu وErigon عبر HTTP أو WebSocket أو IPC، ومع الشبكات المتوافقة مع EVM التي تكشف عن نفس واجهة JSON-RPC.

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

المزامنة الموثوقة وترشيح العناوين

تتم كتابة كل كتلة مع نقطة التحقق الخاصة بها في معاملة قاعدة بيانات واحدة. تُستأنف العمليات عند إعادة التشغيل من حيث توقفت تماماً. عند بدء التشغيل، يقوم المفهرس بإزالة الكتلة الأعلى والرجوع خطوة واحدة، مما يضمن عدم بقاء كتلة مكتوبة جزئياً بعد حدوث عطل. لم تعد الكتل الفارغة والكتل المفلترة تخدع المؤشر؛ حيث يسجل صف sync_state مخصص آخر ارتفاع تمت معالجته حتى لو لم يقم هذا الارتفاع بتخزين أي صفوف. تؤدي أخطاء قاعدة البيانات إلى التراجع عن العملية وإعادة المحاولة بدلاً من ترك نقطة التحقق متقدمة على البيانات.

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

تحسين الفهرسة والأمان

تتكون مجموعة قاعدة البيانات الموصى بها الآن من خمسة فهارس B-tree، مشتقة من حركة استعلامات الإنتاج الفعلية بدلاً من فهرسة كل عمود قد يكون مفيداً. في مجموعة بيانات تحتوي على حوالي 490 مليون صف، توفر هذه المجموعة الأصغر ما يقدر بـ 90-110 جيجابايت. استخدام citext في حقول العناوين يحافظ على المطابقة دون مراعاة حالة الأحرف دون الحاجة إلى تغليف كل استعلام بـ LOWER().

يقوم مستخدم المفهرس بالكتابة، ولكن لا ينبغي لواجهة برمجة التطبيقات العامة القيام بذلك. يوثق هذا الإصدار ويوفر دور web_anon مع صلاحية SELECT فقط على ethtxs وaval وmax_block. تم تحديد سقف PostgREST بـ 10,000 صف لكل استجابة. يغطي دليل الأمان قواعد الوكيل العكسي (reverse-proxy) للنشر العام، بما في ذلك قوائم السماح بالطرق، ومرشحات العناوين الإلزامية على /ethtxs، والحماية ضد تجميعات العد المكلفة والإزاحات غير المحدودة. يتم تحميل بيانات الاعتماد من .env مع دعم معرفات موارد اتصال PostgreSQL، وتقوم التشخيصات بتنقيح كلمات المرور.

الحاوية وعقد واجهة برمجة التطبيقات

الصورة المنشورة هي ghcr.io/adamant-im/eth-transactions-storage:2.5.0، والمبنية لأنظمة linux/amd64 وlinux/arm64. وسوم الإصدار غير قابلة للتغيير؛ لذا قم بتثبيت 2.5.0 في بيئة الإنتاج. يقوم Docker Compose بتشغيل هذه الصورة افتراضياً إلى جانب PostgreSQL وPostPostREST وعقدة Geth محلية اختيارية والمفهرس. يوفر موقع التوثيق على eth-indexer.docs.adamant.im البنية، وبدايات التشغيل السريعة، والتهيئة، وتفاصيل الأمان.

لا يكون الإصدار بهذا الحجم مفيداً إلا إذا استمرت العملاء الحاليون في العمل. وهذا ما يحدث بالفعل. تظل نقاط النهاية /ethtxs و/max_block و/aval دون تغيير.

تحويلات ETH الأصلية، طلب واحد:

GET /ethtxs?and=(contract_to.eq.,or(txfrom.eq.{address},txto.eq.{address}))&order=time.desc&limit=25

تحويلات ERC-20 لعقد رمز:

GET /ethtxs?and=(txto.eq.{contract_address},or(txfrom.eq.{address},contract_to.eq.000000000000000000000000{address_without_0x}))&order=time.desc&limit=25

الحالة الصحية:

GET /max_block
GET /aval

تظل أسماء الأعمدة، والترميزات، والعناوين غير الحساسة لحالة الأحرف كما كانت. الأصفار الـ 24 البادئة في contract_to هي حشوة ABI، وليست خللاً يحتاج إلى معالجة لاحقاً.

النطاق والقيود

يخزن المفهرس تحويلات ETH الأصلية ذات القيمة غير الصفرية وتحويلات ERC-20 المقدمة كطلب transfer(address,uint256) مباشر من المستوى الأعلى. لا يخزن المفهرس التحويلات الداخلية لـ ETH، أو transferFrom، أو تدفقات المحافظ متعددة التوقيع أو الموجهات، أو معايير الرموز الأخرى، أو سجلات الأحداث. لا يقوم المفهرس تلقائياً بإصلاح إعادة تنظيم السلسلة العميقة بعد وقوعها؛ حيث يبقيها CONFIRMATIONS_BLOCK خلف الرأس، مما يعني أن إعادة التنظيم العميقة تتطلب إعادة فهرسة مخططة للنطاق المتأثر. إذا كان تطبيقك يحتاج إلى عكس كل حركة ممكنة للرموز، فأنت بحاجة إلى مفهرس يعتمد على السجلات. أما إذا كان يحتاج إلى التحويلات التي يبدأها المستخدم - وهو السجل الذي تعرضه المحفظة فعلياً - فهذه الأداة مصممة لهذا الغرض وتظل منخفضة التكلفة في التشغيل.

يجب على المشغلين الحاليين قراءة دليل الترقية قبل النشر. قم بتطبيق المخطط الإضافي أولاً، واحتفظ بقيم بيئة الإنتاج الخاصة بك، ولا تعامل تحديث وسم صورة Compose كترقية لـ PostgreSQL. ETH Transactions Storage هي بنية تحتية مفتوحة المصدر يتم صيانتها من قبل مجتمع مطوري ADAMANT وcryptofoundry.