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

البنية

تصف هذه الصفحة البنية المستهدفة لمنظومة OrcaRail غير الاحتجازية، ولكل مكوّن مسار الكود القديم الذي يحل محله.

مخطط النظام​

المكونات​

PaymentLinkFactory (EVM)​

واحد لكل سلسلة. عناوين CREATE2 حتمية مشتقة من تجزئة بطول 32 بايت لمعرّف UUID الخاص برابط الدفع. يوفّر:

  • computeAddress(bytes32 linkId) view returns (address): العنوان قبل النشر لواجهة المستخدم وAPI.
  • deployAndPay(bytes32 linkId, Split split, address token, uint256 amount): نشر مؤجَّل وتحويل في معاملة واحدة.
  • isDeployed(bytes32 linkId) view returns (bool).

قابل للترقية خلف وكيل UUPS يملكه توقيع Safe متعدد 3 من 5، مع timelock مدته 48 ساعة. المستقبِلات الخاصة بكل رابط غير قابلة للترقية.

يحل محل: فرع EVM من generateAddressForNetwork في api/src/payments/wallet.service.ts (اشتقاق HD وحساب عنوان smart account الافتراضي من Alchemy).

PaymentLinkReceiver (EVM)​

نسخة EIP-1167 مصغّرة، واحدة لكل رابط دفع. يقبل العملة الأصلية وERC-20 (SafeERC20 للرموز غير القياسية مثل USDT). يطلق Paid(linkId, payer, token, amount). يستدعي FeeSplitter.split() ذريًا.

يحل محل: خطوة التجميع في SmartAccountWalletService.drainSmartAccountWallet في api/src/withdrawals/services/smart-account-wallet.service.ts.

FeeSplitter (EVM)​

منطق تقسيم بلا حالة. يأخذ بنية Split بنقاط الأساس ومبلغًا، ويوزّعه على عناوين التاجر والمنصة والإحالة ورسوم الجسر. يذهب الباقي إلى التاجر (دون فتات).

يحل محل: حسابات التقسيم بـ TypeScript في drainSmartAccountWallet وbuildNativeDrainCalls / فرع ERC-20 المكافئ في الخدمة نفسها.

SubscriptionHub (EVM)​

واحد لكل سلسلة. يخزّن بنية Subscription لكل bytes32 id. الدالة charge(id) عامة ولا تتطلب صلاحيات، وتفرض:

  • block.timestamp >= nextChargeAt
  • lastChargedAt رتيب
  • amountCharged + amount <= cap
  • فحوص allowance والرصيد في ERC-20

يطلق Charged وChargeSkipped(reason) وCanceled وSubscriptionCreated.

يحل محل: السحب الاحتجازي في api/src/scheduler/processors/subscription-auto-charge.processor.ts الذي يستخدم اليوم smart account تتحكم فيه OrcaRail.

برنامج Anchor مع PDA لكل رابط مشتق من [b"pl", link_id]. التعليمات: initialize وpay وrefund. التقسيم عبر CPI.

يحل محل: فرع Solana من generateAddressForNetwork في api/src/payments/wallet.service.ts (اشتقاق ed25519-hd-key) ومسار تجميع SOL في api/src/withdrawals/services/solana-withdrawal-transfer.service.ts.

برنامج subscription ‏(Solana)​

برنامج Anchor يستخدم Approve / Revoke في SPL كأداة أساسية لصلاحية التفويض. تعكس charge(id) دلالات SubscriptionHub.charge(id) في EVM.

يحل محل: فرع SOL في subscription-auto-charge.processor.ts والسحب الاحتجازي عبر حسابات رموز تتحكم فيها OrcaRail.

توقيع BTC متعدد 2 من 2 + استرداد موقّع مسبقًا​

عنوان taproot لكل رابط مع مفتاح عام للتاجر ومفتاح عام للمنصة. تُخزَّن معاملة PSBT للاسترداد موقّعة مسبقًا خارج السلسلة وقت الإيداع. لا تستطيع المنصة نقل الأموال منفردةً.

يحل محل: المحفظة الساخنة الأحادية في api/src/withdrawals/services/bitcoin-hot-wallet.service.ts. يُحتفَظ بمسار التجميع في api/src/withdrawals/services/bitcoin-withdrawal-transfer.service.ts لكنه يوقّع عبر التوقيع المتعدد بدلًا من مفتاح أحادي.

مُفهرِس الأحداث​

خدمة جديدة، payments/indexer/*، تشترك في:

  • أحداث EVM ‏Paid وSubscriptionCreated وCharged وChargeSkipped وCanceled (watchContractEvent من viem، مع Alchemy أساسيًا وRPC عام احتياطيًا).
  • سجلات برامج Solana (webhooks من Helius أو تدفقات Triton).

تُدرج صفوف PaymentTransaction وSubscriptionAutoCharge أو تحدّثها، وترسل أحداث الـ webhook القائمة في api/src/webhooks/webhooks.service.ts.

يحل محل: استطلاع أرصدة الإيداع واستدعاءات اكتمال التجميع التي تطلق الـ webhooks اليوم.

تدفقات البيانات​

دفعة لمرة واحدة (EVM)​

خصم الاشتراك (EVM)​

الاسترداد​

EVM: يستدعي EOA الـ keeper الخاص بالتاجر أو التوقيع المتعدد PaymentLinkReceiver.refund(txId). Solana: ينفّذ الموقّع تعليمة refund. BTC: يبث التاجر معاملة PSBT للاسترداد الموقّعة مسبقًا.

التسوية عبر السلاسل​

لا يزال Relay مستخدمًا (راجع api/src/withdrawals/services/bridge)، لكن المُطلِق صار على السلسلة بدلًا من الاحتجازي: يستدعي المستقبِل منفّذ Relay في المعاملة نفسها، أو يفعل الـ keeper ذلك فور حدث Paid.

ما يحل محله في قاعدة الكود​

قائمة مختصرة للمهندسين. يُستبدَل أو يُتجاوَز في المراحل 1–4، ويُحذف في المرحلة 7.

الملف / المسار القديمالبديل
api/src/payments/wallet.service.ts: اشتقاق HD وsmart account من AlchemycomputeAddress في الـ factory + findProgramAddressSync في Solana
api/src/withdrawals/services/smart-account-wallet.service.ts: التفريغ / التحويلتقسيم ذري في PaymentLinkReceiver.pay
api/src/withdrawals/services/solana-withdrawal-transfer.service.ts: تجميع SOLتعليمة pay في برنامج payment_link
api/src/scheduler/processors/subscription-auto-charge.processor.ts: السحب الاحتجازيSubscriptionHub.charge + charge في Anchor
api/src/withdrawals/services/bitcoin-hot-wallet.service.ts: مفتاح BTC أحاديتوقيع متعدد 2 من 2 لكل رابط مع موقّع من التاجر
جدول hd_wallet_seed + WALLET_ENCRYPTION_KEYأُزيل لـ EVM/SOL؛ ويُؤرشف في المرحلة 7

انظر أيضًا​