مواصفات Solana Pay الإصدار 1

ملخص

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

يستمد هذا المعيار الإلهام من BIP 21 و EIP 681.

الدافع

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

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

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

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

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

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

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

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

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

المستلم

حقل recipient واحد مطلوب كمسار. يجب أن تكون القيمة المفتاح العام المشفر بنظام base58 لحساب SOL أصلي. يجب عدم استخدام حسابات الرموز المرتبطة.

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

المبلغ

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

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

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

رمز SPL

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

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

إذا لم يتم توفير الحقل، فإن عنوان URL يصف تحويل 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 لطلب معاملة سولانا Pay طلبًا تفاعليًا لأي معاملة على شبكة سولانا.

solana:<link>

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

الرابط

يُطلب حقل واحد link كمسار. يجب أن تكون القيمة عبارة عن رابط URL مطلق HTTPS مشفر بشروط.

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

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

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

طلب GET

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

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

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

استجابة GET

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

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

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

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

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

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

طلب POST

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

{ "account": "<account>" }

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

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

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

استجابة POST

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

{ "transaction": "<transaction>" }

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

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

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

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

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

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

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

• يجب على التطبيق تعيين feePayer إلى المفتاح العام للتوقيع الأول.
• يجب على التطبيق تعيين recentBlockhash إلى أحدث تجزئة كتلة.
• يجب على التطبيق تسلسل المعاملة وإلغاء تسلسلها قبل التوقيع عليها. هذا يضمن ترتيباً متسقاً لمفاتيح الحساب، كحل بديل لـ هذه المشكلة.
• يجب على المحفظة عدم تعيين 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 لاقتراح تغييرات على المواصفات من أجل الحصول على ملاحظات من مطوري التطبيقات والمحافظ.

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

انظر أيضًا

• مواصفات سولانا Pay الإصدار 1.1 - أحدث إصدار مع التحسينات
• دليل البدء السريع - أدلة التنفيذ
• مستودع GitHub - التنفيذات المرجعية