مواصفات سولانا Pay الإصدار 1.1

ملخص

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

تم التوصل إلى إجماع تقريبي حول هذه المواصفات، وتوجد تطبيقات في Phantom وFTX وSlope.

تستمد هذه المواصفات الإلهام من BIP 21 وEIP 681.

الدافع

يتيح بروتوكول URL قياسي لطلب تحويلات SOL الأصلية، وتحويلات رموز SPL، ومعاملات سولانا تجربة مستخدم أفضل عبر التطبيقات والمحافظ في نظام سولانا البيئي.

يمكن ترميز عناوين URL هذه في رموز QR أو علامات NFC، أو إرسالها بين المستخدمين والتطبيقات لطلب الدفع وتكوين المعاملات.

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

يجب على المحافظ المحمولة التسجيل للتعامل مع مخطط URL لتوفير تجربة سلسة وآمنة عند مواجهة عناوين URL الخاصة بـ سولانا Pay في البيئة.

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

المواصفات: طلب التحويل

يصف عنوان URL لطلب تحويل سولانا Pay طلبًا غير تفاعلي لتحويل SOL أو رمز SPL.

solana:<recipient>
      ?amount=<amount>
      &spl-token=<spl-token>
      &reference=<reference>
      &label=<label>
      &message=<message>
      &memo=<memo>

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

المستلم

حقل recipient واحد مطلوب كمسار. يجب أن تكون القيمة هي pubkey المشفر بـ base58 لحساب SOL الأصلي. يجب عدم استخدام associated token account.

بدلاً من ذلك، لطلب تحويل رمز SPL، يجب استخدام حقل spl-token لتحديد رمز mint لرمز SPL، والذي يجب منه اشتقاق عنوان الرمز المرتبط للمستلم.

المبلغ

يُسمح بحقل amount واحد كمعامل استعلام اختياري. يجب أن تكون القيمة عدداً صحيحاً غير سالب أو رقماً عشرياً من وحدات "المستخدم". بالنسبة لـ SOL، فهذا يعني SOL وليس lamports. بالنسبة للرموز، استخدم uiAmountString وليس amount.

0 قيمة صالحة. إذا كانت القيمة رقماً عشرياً أقل من 1، فيجب أن يكون لها 0 في البداية قبل .. التدوين العلمي محظور.

إذا لم يتم توفير قيمة، يجب على المحفظة مطالبة المستخدم بالمبلغ. إذا تجاوز عدد الأرقام العشرية ما هو مدعوم لـ SOL (9) أو رمز SPL (خاص بـ mint)، فيجب على المحفظة رفض الرابط باعتباره مشوهاً.

رمز SPL

يُسمح بحقل spl-token واحد كمعامل استعلام اختياري. يجب أن تكون القيمة هي المفتاح العام المشفر بصيغة base58 لحساب mint لرمز SPL.

إذا تم توفير الحقل، فيجب استخدام اصطلاح حساب الرمز المرتبط ويجب على المحفظة تضمين تعليمة TokenProgram.Transfer أو TokenProgram.TransferChecked كآخر تعليمة في المعاملة.

إذا لم يتم توفير الحقل، فإن الرابط يصف تحويل SOL أصلي، ويجب على المحفظة تضمين تعليمة SystemProgram.Transfer كآخر تعليمة في المعاملة بدلاً من ذلك.

يجب على المحفظة اشتقاق عنوان ATA من حقلي recipient وspl-token. التحويلات إلى حسابات الرموز المساعدة غير مدعومة.

المرجع

يُسمح بحقول reference متعددة كمعاملات استعلام اختيارية. يجب أن تكون القيم عبارة عن مصفوفات من 32 بايت مشفرة بصيغة base58. قد تكون أو لا تكون مفاتيح عامة، على المنحنى أو خارجه، وقد تتوافق أو لا تتوافق مع حسابات على سولانا.

إذا تم توفير القيم، يجب على المحفظة تضمينها بالترتيب المحدد كمفاتيح للقراءة فقط وغير موقّعة إلى تعليمات SystemProgram.Transfer أو TokenProgram.Transfer/TokenProgram.TransferChecked في معاملة الدفع. قد تكون القيم فريدة أو غير فريدة لطلب الدفع، وقد تتوافق أو لا تتوافق مع حساب على سولانا.

نظرًا لأن مدققي سولانا يفهرسون المعاملات حسب مفاتيح الحسابات هذه، يمكن استخدام قيم reference كمعرّفات عميل (معرّفات قابلة للاستخدام قبل معرفة معاملة الدفع النهائية). يمكن استخدام طريقة getSignaturesForAddress من RPC لتحديد موقع المعاملات بهذه الطريقة.

التسمية

يُسمح بحقل label واحد كمعامل استعلام اختياري. يجب أن تكون القيمة عبارة عن سلسلة UTF-8 مشفّرة بتنسيق URL تصف مصدر طلب التحويل.

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

الرسالة

يُسمح بحقل message واحد كمعامل استعلام اختياري. يجب أن تكون القيمة عبارة عن سلسلة UTF-8 مشفّرة بتنسيق URL تصف طبيعة طلب التحويل.

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

المذكرة

يُسمح بحقل memo واحد كمعامل استعلام اختياري. يجب أن تكون القيمة عبارة عن سلسلة UTF-8 مشفّرة بتنسيق URL يجب تضمينها في تعليمات SPL Memo في معاملة الدفع.

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

إذا تم توفير الحقل، يجب على المحفظة تضمين تعليمة MemoProgram كثاني آخر تعليمة في المعاملة، مباشرة قبل تعليمة نقل SOL أو رمز SPL، لتجنب الالتباس مع التعليمات الأخرى في المعاملة.

أمثلة

رابط URL يصف طلب تحويل لـ 1 SOL

solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN?amount=1&label=Michael&message=Thanks%20for%20all%20the%20fish&memo=OrderId12345

رابط URL يصف طلب تحويل لـ 0.01 USDC

solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN?amount=0.01&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

رابط URL يصف طلب تحويل لـ SOL (مع مطالبة المستخدم بإدخال المبلغ)

solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN?label=Michael

المواصفات: طلب المعاملة

يصف رابط URL لطلب معاملة سولانا باي طلباً تفاعلياً لأي معاملة على سولانا.

solana:<link>

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

الرابط

حقل link واحد مطلوب كمسار. يجب أن تكون القيمة عبارة عن رابط URL مطلق بصيغة HTTPS مُرمَّز شرطياً.

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

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

في كلتا الحالتين، يجب على المحفظة فك ترميز القيمة. هذا لا يؤثر إذا لم تكن القيمة مُرمَّزة. إذا لم تكن القيمة المفكوكة رابط URL مطلق بصيغة HTTPS، فيجب على المحفظة رفضها باعتبارها مشوهة.

طلب GET

يجب على المحفظة إجراء طلب JSON من نوع GET عبر HTTP إلى الرابط URL. يجب ألا يحدد الطلب هوية المحفظة أو المستخدم.

يجب على المحفظة إجراء الطلب مع رأس Accept-Encoding، ويجب على التطبيق الرد مع رأس Content-Encoding لضغط HTTP.

يجب أن تعرض المحفظة نطاق الرابط أثناء تنفيذ الطلب.

استجابة GET

يجب على المحفظة معالجة أخطاء العميل في HTTP، أخطاء الخادم، و استجابات إعادة التوجيه. يجب على التطبيق الرد بأحد هذه الأنواع، أو باستجابة JSON من نوع HTTP OK مع محتوى:

{ "label": "<label>", "icon": "<icon>" }

يجب أن تكون قيمة <label> نصاً بترميز UTF-8 يصف مصدر طلب المعاملة. على سبيل المثال، قد يكون هذا اسم علامة تجارية أو متجر أو تطبيق أو شخص يقوم بالطلب.

يجب أن تكون قيمة <icon> رابطاً مطلقاً بروتوكول HTTP أو HTTPS لصورة أيقونة. يجب أن يكون الملف بصيغة SVG أو PNG أو WebP، وإلا يجب على المحفظة رفضه باعتباره غير صحيح.

يجب ألا تقوم المحفظة بتخزين الاستجابة مؤقتاً إلا وفقاً لتعليمات التخزين المؤقت لـ HTTP الموجودة في رؤوس الاستجابة.

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

طلب POST

يجب على المحفظة إرسال طلب JSON من نوع HTTP POST إلى الرابط مع محتوى:

{ "account": "<account>" }

يجب أن تكون قيمة <account> هي المفتاح العام المشفر بترميز base58 للحساب الذي قد يوقع المعاملة.

يجب على المحفظة إرسال الطلب مع رأس Accept-Encoding، ويجب على التطبيق الرد مع رأس Content-Encoding لضغط HTTP.

يجب على المحفظة عرض نطاق الرابط أثناء تنفيذ الطلب. إذا تم إجراء طلب GET، يجب على المحفظة أيضاً عرض التسمية وإظهار صورة الأيقونة من الاستجابة.

استجابة POST

يجب على المحفظة معالجة أخطاء العميل في HTTP، أخطاء الخادم، و استجابات إعادة التوجيه. يجب على التطبيق الرد بأحد هذه الأنواع، أو باستجابة JSON من نوع HTTP OK مع محتوى:

{ "transaction": "<transaction>" }

يجب أن تكون قيمة <transaction> عبارة عن معاملة متسلسلة مشفرة بصيغة base64. يجب على المحفظة فك تشفير المعاملة من base64 و إلغاء تسلسلها.

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

التوقيعات الفارغة

إذا كانت signatures الخاصة بالمعاملة فارغة:

• يجب على التطبيق تعيين feePayer إلى account في الطلب، أو القيمة الصفرية (new PublicKey(0) أو new PublicKey("11111111111111111111111111111111")).
• يجب على التطبيق تعيين recentBlockhash إلى أحدث blockhash، أو القيمة الصفرية (new PublicKey(0).toBase58() أو "11111111111111111111111111111111").
• يجب على المحفظة تجاهل feePayer في المعاملة وتعيين feePayer إلى account في الطلب.
• يجب على المحفظة تجاهل recentBlockhash في المعاملة وتعيين recentBlockhash إلى أحدث blockhash.

إذا كانت signatures الخاصة بالمعاملة غير فارغة:

• يجب على التطبيق تعيين feePayer إلى المفتاح العام للتوقيع الأول.
• يجب على التطبيق تعيين recentBlockhash إلى أحدث blockhash.
• يجب على التطبيق تسلسل المعاملة وإلغاء تسلسلها قبل التوقيع عليها. يضمن ذلك ترتيباً متسقاً لمفاتيح الحسابات، كحل بديل لـ هذه المشكلة.
• يجب على المحفظة عدم تعيين feePayer و recentBlockhash.
• يجب على المحفظة التحقق من التوقيعات، وإذا كان أي منها غير صالح، يجب على المحفظة رفض المعاملة باعتبارها مشوهة.

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

إذا كان أي توقيع باستثناء التوقيع الخاص بـ account في الطلب متوقعاً، فيجب على المحفظة رفض المعاملة باعتبارها خبيثة.

قد يتضمن التطبيق أيضًا حقل message اختياري في نص الاستجابة:

{ "message": "<message>", "transaction": "<transaction>" }

يجب أن تكون قيمة <message> عبارة عن سلسلة نصية بترميز UTF-8 تصف طبيعة استجابة المعاملة.

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

يجب أن تسمح المحفظة والتطبيق بحقول إضافية في نص الطلب ونص الاستجابة، والتي قد تتم إضافتها من خلال المواصفات المستقبلية.

مثال

عنوان URL يصف طلب معاملة.

solana:https://example.com/solana-pay

عنوان URL يصف طلب معاملة مع معاملات الاستعلام.

solana:https%3A%2F%2Fexample.com%2Fsolana-pay%3Forder%3D12345

طلب GET

GET /solana-pay?order=12345 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate

استجابة GET

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Content-Length: 62
Content-Encoding: gzip

{"label":"Michael Vines","icon":"https://example.com/icon.svg"}

طلب POST

POST /solana-pay?order=12345 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate
Content-Type: application/json
Content-Length: 57

{"account":"mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN"}

استجابة POST

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Content-Length: 298
Content-Encoding: gzip

{"message":"Thanks for all the fish","transaction":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAECC4JMKqNplIXybGb/GhK1ofdVWeuEjXnQor7gi0Y2hMcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQECAAAMAgAAAAAAAAAAAAAA"}

الإضافات

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

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

مثال فعلي لمثل هذا الاقتراح.