إنتقل إلى المحتوى الرئيسي

دليل الترحيل

يشرح هذا الدليل ما عليك فعله، وما تتوقعه، أثناء طرح OrcaRail للمنظومة غير الاحتجازية. الطرح مرحلي واختياري لكل سلسلة؛ ولا يُجبر أي رابط أو اشتراك قائم على الترحيل.

للتجار​

ما الذي يتغير في تكاملك​

لا شيء مطلوب. شكل استجابة API لروابط الدفع والاشتراكات إضافي خلال الانتقال:

  • تحصل روابط الدفع على حقل جديد receiver.contract_address (القيمة نفسها لعنوان الإيداع الحالي في الروابط ذات المستقبِل على السلسلة).
  • تحصل الاشتراكات على auto_charge.approval_spender_address الذي يشير إلى SubscriptionHub على السلسلة بدلًا من محفظة ساخنة. هذا الحقل موجود أصلًا في الخصم التلقائي؛ تتغير قيمته فقط.
  • تُطلق الـ webhooks في اللحظات نفسها (payment.succeeded وsubscription.charge.* وغيرها).

ما الذي يتغير في لوحة التحكم​

  • تظهر شارة «غير احتجازي» على روابط الدفع والاشتراكات التي تستخدم المنظومة الجديدة.
  • يدعوك شريط على الاشتراكات النشطة القائمة إلى عرض الترحيل على الدافع عند التجديد التالي.
  • يتيح لك مفتاح لكل سلسلة في الإعدادات تفعيل المستقبِلات غير الاحتجازية سلسلةً تلو الأخرى بعد اجتياز السلسلة مرحلة الـ canary (Base أولًا).

متى تتصرف​

  • المرحلة 1 (Base): لا شيء مطلوب. تستخدم الروابط الجديدة على Base المستقبِل الجديد تلقائيًا بمجرد تفعيل علامة مؤسستك.
  • المرحلة 2: عند ظهور الشريط، أعد توجيه إشعار التجديد إلى مشتركيك ليعيدوا توقيع approve لـ SubscriptionHub الجديد. قالب البريد معبّأ مسبقًا.
  • المرحلة 3 (سلاسل EVM الأخرى): النمط نفسه كما في Base، لكل سلسلة.
  • المرحلة 4 (Solana): النمط نفسه، ويُفعَّل في دورة اشتراك SOL التالية لدى التاجر.
  • المرحلة 5 (Bitcoin): سجّل موقّع BTC ‏(xpub) في لوحة التحكم لتتمكن روابط BTC الجديدة من استخدام التوقيع المتعدد 2 من 2. راجع اعتبارات Bitcoin.
  • المرحلة 7: إذا كان أي من مشتركيك لا يزال على المسار الاحتجازي القديم، فتواصل معه بالإشعار النهائي ذي الثلاثين يومًا الذي نوفّره.

المسارات القديمة​

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

للدافعين​

المدفوعات لمرة واحدة​

لا شيء يتغير. ترى رابط الدفع نفسه والعنوان نفسه وواجهة المحفظة نفسها. في الخلفية، المستقبِل عقد ذكي بدلًا من محفظة على الخادم، لكن مسارك متطابق.

الاشتراكات​

مسار الإعداد هو نفسه اليوم: اربط محفظتك، ووقّع approve ‏(EVM) أو Approve في SPL ‏(Solana)، وانتهى الأمر. الفرق الوحيد الملحوظ أن الجهة المخوّلة بالإنفاق عنوان عقد (SubscriptionHub) بدلًا من محفظة ساخنة لـ OrcaRail. ستُظهر محفظتك بوضوح أن الجهة المخوّلة عقد.

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

إذا كنت مشتركًا حاليًا​

عند ظهور شريط الترحيل في صفحة إدارة اشتراكك، سترى عرضًا للترحيل. بالنقر عليه:

  1. يُطلب منك إلغاء الـ allowance القديم (اختياري؛ يصبح بلا أثر بعد الترحيل).
  2. يُطلب منك توقيع approve جديد لعقد SubscriptionHub.

هذا كل شيء. يستمر اشتراكك دون انقطاع.

إذا لم ترحّل، يستمر اشتراكك على المسار القديم حتى الإلغاء أو حتى نهاية نافذة الترحيل النهائية المُعلنة في المرحلة 7.

للمطوّرين المدمِجين (مستخدمي SDK)​

الحقول الإضافية​

شكل استجابة API متوافق تمامًا مع الإصدارات السابقة. الحقول الجديدة:

  • payment_intent.receiver.contract_address
  • subscription.auto_charge.approval_spender_address (قد تتغير القيمة إلى عنوان عقد)
  • subscription.on_chain.* (عنوان مركز الاشتراكات، وchain id، ومعرّف الاشتراك bytes32)
  • تضيف الـ webhooks علامة non_custodial: true حيث ينطبق ذلك.

الإهمال​

لا تُزال أي حقول خلال الانتقال. في المرحلة 7، ستُعلَّم الحقول التي تصف عناوين الموقّعين الاحتجازيين كمهملة في مرجع API، وتُزال في إصدار رئيسي لاحق من SDK ‏(@orcarail/[email protected]) مع إشعار مسبق بتسعين يومًا.

توافق الـ webhooks​

لا تتغير أنواع الأحداث وأشكال الحمولات لـ payment.* وsubscription.* وwebhook.*. يطلق المسار غير الاحتجازي الأحداث نفسها في اللحظات نفسها.

الإلغاء في منتصف الدورة​

إذا ألغى دافع الـ allowance بين دورتين:

  1. يطلق charge() التالي الحدث ChargeSkipped(InsufficientAllowance) على السلسلة.
  2. يحدّث المُفهرِس الاشتراك إلى past_due.
  3. يُرسل قالب البريد القائم subscription-insufficient-allowance.hbs إلى الدافع.
  4. يُطلق webhook التاجر subscription.payment_failed.
  5. يمكن للدافع استئناف الاشتراك بإعادة الموافقة من صفحة إدارة الاشتراك.

يطابق السلوك ما لديك اليوم في الخصم التلقائي. تغيّرت التمديدات الداخلية فقط.

اعتبارات عبر السلاسل​

إذا دفع الدافع على سلسلة غير سلسلة التسوية الخاصة بالتاجر، يتولى Relay الجسر (راجع استراتيجية السحب). تغيّر المنظومة غير الاحتجازية من يستدعي Relay (المستقبِل أو EOA الـ keeper، لا موقّع احتجازي) دون تغيير مسار الجسر نفسه.

مرجع الجدول الزمني​

راجع خارطة الطريق للحالة الحية. التواريخ أهداف وليست التزامات.

المرحلةما الذي تتوقعه
1تصبح روابط الدفع على Base غير احتجازية (canary اختياري ثم افتراضي)
2تُرحَّل اشتراكات EVM عند التجديد
3تُطلق Ethereum وArbitrum وOptimism وPolygon
4تُرحَّل روابط الدفع والاشتراكات على Solana
5ينتقل Bitcoin إلى توقيع متعدد 2 من 2 (تبقى اشتراكات BTC غير مدعومة)
6اختياري: keeper لامركزي. لا تغيير للتجار أو الدافعين.
7تُحذف المسارات الاحتجازية القديمة؛ إشعار ترحيل نهائي لمن تبقّى

انظر أيضًا​