تخزين معاملات ETH: فلتر عناوين اختياري، فهارس أخف، وواجهة برمجة تطبيقات عامة أكثر أمانًا

ETH-transactions-storage هو مفهرس إيثيريوم ذاتي الاستضافة يتبع عقدة إيثيريوم، ويخزن نشاط ETH الأصلي و ERC-20 transfer(address,uint256) في قاعدة بيانات PostgreSQL، ويعرضه كواجهة برمجة تطبيقات REST للقراءة فقط عبر PostgREST. نظرًا لأن عقد إيثيريوم لا يمكنها الإجابة على استعلامات سجل العناوين مباشرة، تعتمد المحافظ والتطبيقات اللامركزية والخزائن والمشغلون عادةً على مستكشف تابع لجهة خارجية. هذا المشروع هو البديل الذي تشغله بنفسك — بدون بائع مفاتيح API، وبدون تتبع، وبدون قياس عن بُعد.

يتضمن فرع dev الآن فلتر عناوين اختياريًا، تم دمجه في PR #29. تظل فهرسة السلسلة الكاملة هي الوضع الافتراضي وهي ما تستخدمه محافظ ADAMANT. يستهدف الوضع المفلتر المشغلين الذين يحتاجون فقط إلى مجموعة معروفة من العناوين ولا يرغبون في تخزين بقية السلسلة.

لماذا يوجد الفلتر؟

يعد مفهرس إيثيريوم العام قاعدة بيانات ضخمة. في مجموعة بيانات الشبكة الرئيسية لمدة عام واحد بحجم 490 مليون صف تقريبًا، استهلكت مجموعة الفهرس الكامل القديمة مئات الجيجابايت. لا يحتاج العديد من المشغلين إلى هذا الحجم — فالمحفظة أو الواجهة الخلفية للحفظ التي تخدم مستخدميها فقط، أو خزينة المشروع التي تراقب حفنة من العناوين التشغيلية، أو المستكشف ذاتي الاستضافة لمجموعة عناوين خاصة بتطبيق معين، أو بيئة المختبر والتكامل المستمر (CI) التي يجب أن تظل صغيرة، جميعها تستفيد من التخزين الانتقائي. يحافظ الفلتر على عقد واجهة برمجة التطبيقات الحالي: لا يزال العملاء يستعلمون عن /ethtxs و /max_block و /aval. يقوم المشغلون بتغيير ما يتم تخزينه، وليس كيفية قراءته.

سلوك فلتر العناوين

يتم تعطيل الفلتر افتراضيًا (ADDRESS_FILTER_ENABLED=false). يؤدي تمكينه إلى توجيه ADDRESS_FILTER_FILE إلى قائمة خاصة (الافتراضي هو filter/addresses.txt الذي يتم تجاهله بواسطة git ولا يتم نسخه إلى صورة Docker). تقبل القائمة عنوانًا واحدًا مسبوقًا بـ 0x ومكونًا من 40 حرفًا سداسيًا عشريًا في كل سطر، مع تجاهل الأسطر الفارغة وتعليقات #، والمطابقة غير حساسة لحالة الأحرف. تطابق التحويلات الأصلية txfrom أو txto. تطابق استدعاءات ERC-20 transfer(address,uint256) المدعومة المرسل (txfrom)، وعقد الرمز المميز (txto)، والمستلم المشفر بـ ABI (contract_to).

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

تظل حدود المفهرس الحالية دون تغيير: لا يلتقط الفلتر تحويلات ETH الداخلية، أو تدفقات ERC-20 التي ليست transfer(address,uint256) مباشرة (مثل transferFrom أو الموجهات أو المحافظ متعددة التوقيع أو استدعاءات الدفعات/المجمع)، أو التعبئة التاريخية التلقائية عند إضافة عنوان. لا يؤدي تمكين الفلتر إلى حذف الصفوف المخزنة بالفعل. إعادة البناء هي خطوة يدوية للمشغل: أوقف المفهرس، وقم بقطع (truncate) كل من ethtxs و sync_state في معاملة واحدة (أو أعد كلاهما إلى الكتلة N)، واضبط START_BLOCK ثم أعد التشغيل. لن تؤدي عملية القطع لـ ethtxs وحدها إلى إعادة المسح لأن نقطة التحقق لا تزال تبلغ عن اكتمال السلسلة.

تقدم المزامنة الدائم

كانت الكتل المفلترة والفارغة تبدو سابقًا وكأنها “لم يحدث شيء”، لذا كان بإمكان المفهرس إعادة مسحها. يحتفظ فرع dev الآن بنقطة تحقق public.sync_state ذات صف واحد، يتم تحديثها في نفس معاملة PostgreSQL مثل عمليات الإدراج لتلك الكتلة. لا تزال نقطة النهاية /max_block تعيد { max, version }، حيث max هو GREATEST(MAX(ethtxs.block), sync_state.last_block). لا تزال عملية البدء تعيد الكتلة الأخيرة التي تمت معالجتها، الآن بشكل ذري مع نقطة التحقق. البرنامج النصي create_tables.sql متماثل (idempotent): فهو ينشئ sync_state، ويهيئها من أعلى كتلة معاملة موجودة، ويمنح صلاحيات DML لـ api_user و app_user عند وجود هذه الأدوار. لا يمكن لدور web_anon قراءة أو كتابة sync_state مباشرة.

الفهارس، تقوية واجهة برمجة التطبيقات، والعمليات

يعتمد فلتر العناوين على أعمال dev أخرى من PR #28، والتي لم تصبح إصدارًا على GitHub بعد (يظل أحدث إصدار هو v2.4.1). تغطي مجموعة من خمسة فهارس كحد أدنى أشكال استعلام ADAMANT Web و iOS، مما يوفر ما يقرب من 90-110 جيجابايت لكل مجموعة بيانات لمدة عام واحد مقارنة بمجموعة الفهارس الثمانية القديمة. أصبح دور PostgREST المجهول web_anon الآن للقراءة فقط (SELECT) على ethtxs و aval و max_block، ويحدد db-max-rows = 10000 حجم النتيجة المتسلسلة بحيث لا يمكن لـ GET /ethtxs غير محدود أن يستهلك ذاكرة واجهة برمجة التطبيقات.

تكتسب عمليات النشر العامة حماية nginx: قائمة سماح للطرق (GET/HEAD/OPTIONS)، ومتطلب لـ txfrom أو txto على /ethtxs، ورفض Prefer: count=exact والإزاحات الضخمة. تم توثيق سير عمل .env الآن باستخدام قالب، وتبقى الأسرار خارج Git، ولم يعد Compose يشحن كلمة مرور قاعدة بيانات مشفرة. تشخيصات قاعدة البيانات أكثر أمانًا — تعمل معرفات موارد الاتصال (URIs) بشكل صحيح ويتم تنقيح كلمات المرور من السجلات. يحدد ملف AGENTS.md عقد المساهم والمشغل للمستودع.

يجب أن تحتفظ مضيفات systemd الحالية بوحدتها الحالية أثناء ترقية الكود والمخطط. قم بتطبيق create_tables.sql مع ON_ERROR_STOP قبل بدء المفهرس الجديد، ولا تقم بنسخ ethsync.service الخاص بالمستودع حتى يوجد ملف .env للإنتاج بقيم مكافئة.

لمن هذا العمل؟

يستخدم ADAMANT هذا المفهرس حتى يتمكن adamant-im و adamant-iOS من عرض سجل إيثيريوم و ERC-20 بدون مستكشف مركزي. الثنائي نفسه هو خدمة مفتوحة المصدر للأغراض العامة للمحافظ ومعالجي الدفع ومصدري الرموز وأي شخص يريد سجل إيثيريوم مفهرسًا بالعناوين تحت سياسة PostgreSQL والوصول الخاصة به. قم باستضافته ذاتيًا، أو احتفظ بوضع السلسلة الكاملة لواجهة برمجة تطبيقات عامة، أو قم بتمكين الفلتر وتخزين العناوين التي تخدمها فعليًا فقط.