Solana Pay Spesifikasyonu v1.1

Özet

URL'ler içinde Solana işlem taleplerini kodlamak için ödemeleri ve diğer kullanım senaryolarını mümkün kılan standart bir protokol.

Bu spesifikasyon üzerinde genel bir uzlaşmaya varılmıştır ve Phantom, FTX ve Slope'ta uygulamalar mevcuttur.

Bu standart, BIP 21 ve EIP 681'den ilham almaktadır.

Motivasyon

Yerel SOL transferleri, SPL Token transferleri ve Solana işlemleri için standart bir URL protokolü, Solana ekosistemindeki uygulamalar ve cüzdanlar arasında daha iyi bir kullanıcı deneyimi sağlar.

Bu URL'ler QR kodlarında veya NFC etiketlerinde kodlanabilir ya da ödeme talep etmek ve işlemleri oluşturmak için kullanıcılar ve uygulamalar arasında gönderilebilir.

Uygulamalar, satılan mal veya hizmetleri teslim etmeden veya nesnelere ya da etkinliklere erişim vermeden önce bir işlemin onaylandığından ve geçerli olduğundan emin olmalıdır.

Mobil cüzdanlar, ortamda Solana Pay URL'leriyle karşılaşıldığında sorunsuz ancak güvenli bir deneyim sağlamak için URL şemasını işleyecek şekilde kaydolmalıdır.

Bu sorunları çözmeye yönelik basit bir yaklaşımı standartlaştırarak, geliştiricilerin daha üst düzey soyutlamalara odaklanabilmesi için uygulamaların ve cüzdanların temel uyumluluğunu garanti ederiz.

Spesifikasyon: Transfer Talebi

Bir Solana Pay transfer talebi URL'si, SOL veya SPL Token transferi için etkileşimsiz bir talebi tanımlar.

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

Talep etkileşimsizdir çünkü URL'deki parametreler bir cüzdan tarafından doğrudan bir işlem oluşturmak için kullanılır.

Alıcı

Yol adı olarak tek bir recipient alanı gereklidir. Değer, yerel bir SOL hesabının base58 kodlu genel anahtarı olmalıdır. Associated token account kullanılmamalıdır.

Bunun yerine, bir SPL Token transferi istemek için spl-token alanı kullanılmalıdır; bu alan, alıcının ilişkili token adresinin türetilmesi gereken bir SPL Token mint hesabını belirtir.

Miktar

İsteğe bağlı bir sorgu parametresi olarak tek bir amount alanına izin verilir. Değer, "kullanıcı" birimlerinde negatif olmayan bir tamsayı veya ondalık sayı olmalıdır. SOL için bu, lamport değil SOL'dur. Token'lar için, uiAmountString kullanın, amount değil.

0 geçerli bir değerdir. Değer 1'den küçük bir ondalık sayı ise, .'den önce başta bir 0 olmalıdır. Bilimsel gösterim yasaktır.

Bir değer sağlanmazsa, cüzdan kullanıcıdan miktarı istemelidir. Ondalık basamak sayısı SOL (9) veya SPL Token (mint'e özgü) için desteklenen miktarı aşarsa, cüzdan URL'yi hatalı biçimlendirilmiş olarak reddetmelidir.

SPL Token

İsteğe bağlı bir sorgu parametresi olarak tek bir spl-token alanına izin verilir. Değer, bir SPL Token mint hesabının base58 kodlu genel anahtarı olmalıdır.

Alan sağlanmışsa, Associated Token Account kuralı kullanılmalı ve cüzdan, işlemin son talimatı olarak bir TokenProgram.Transfer veya TokenProgram.TransferChecked talimatı içermelidir.

Alan sağlanmamışsa, URL yerel bir SOL transferini tanımlar ve cüzdan bunun yerine işlemin son talimatı olarak bir SystemProgram.Transfer talimatı içermelidir.

Cüzdan, ATA adresini recipient ve spl-token alanlarından türetmelidir. Yardımcı token hesaplarına transferler desteklenmez.

Referans

İsteğe bağlı sorgu parametreleri olarak birden fazla reference alanına izin verilir. Değerler, base58 kodlu 32 baytlık diziler olmalıdır. Bunlar genel anahtarlar olabilir veya olmayabilir, eğri üzerinde veya dışında olabilir ve Solana üzerindeki hesaplara karşılık gelebilir veya gelmeyebilir.

Değerler sağlanırsa, cüzdan bunları sağlanan sırada salt okunur, imzalayıcı olmayan anahtarlar olarak ödeme işlemindeki SystemProgram.Transfer veya TokenProgram.Transfer/TokenProgram.TransferChecked talimatına dahil etmelidir. Değerler ödeme talebine özgü olabilir veya olmayabilir ve Solana üzerindeki bir hesaba karşılık gelebilir veya gelmeyebilir.

Solana doğrulayıcıları işlemleri bu hesap anahtarlarına göre indekslediğinden, reference değerleri istemci kimlikleri (nihai ödeme işlemi bilinmeden önce kullanılabilir kimlikler) olarak kullanılabilir. Bu şekilde işlemleri bulmak için getSignaturesForAddress RPC yöntemi kullanılabilir.

Etiket

İsteğe bağlı bir sorgu parametresi olarak tek bir label alanına izin verilir. Değer, transfer talebinin kaynağını tanımlayan URL ile kodlanmış bir UTF-8 dizesi olmalıdır.

Örneğin, bu talebi yapan bir marka, mağaza, uygulama veya kişinin adı olabilir. Cüzdan değeri URL kod çözme ile çözmeli ve kod çözülmüş değeri kullanıcıya göstermelidir.

Mesaj

İsteğe bağlı bir sorgu parametresi olarak tek bir message alanına izin verilir. Değer, transfer talebinin niteliğini tanımlayan URL ile kodlanmış bir UTF-8 dizesi olmalıdır.

Örneğin, bu satın alınan bir ürünün adı, bir sipariş kimliği veya bir teşekkür notu olabilir. Cüzdan değeri URL kod çözme ile çözmeli ve kod çözülmüş değeri kullanıcıya göstermelidir.

Not

İsteğe bağlı bir sorgu parametresi olarak tek bir memo alanına izin verilir. Değer, ödeme işlemindeki bir SPL Memo talimatına dahil edilmesi gereken URL ile kodlanmış bir UTF-8 dizesi olmalıdır.

Cüzdan değeri URL kod çözme ile çözmeli ve kod çözülmüş değeri kullanıcıya göstermelidir. Not, doğrulayıcılar tarafından kaydedilecektir ve özel veya hassas bilgiler içermemelidir.

Alan sağlanmışsa, cüzdan, SOL veya SPL Token transfer talimatından hemen önce, işlemin sondan ikinci talimatı olarak bir MemoProgram talimatı içermelidir; böylece işlemdeki diğer talimatlarla belirsizlik oluşmaz.

Örnekler

1 SOL transfer talebi açıklayan URL

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

0.01 USDC transfer talebi açıklayan URL

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

SOL transfer talebi açıklayan URL (kullanıcıya miktar sorulur)

solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN?label=Michael

Spesifikasyon: İşlem Talebi

Bir Solana Pay işlem talebi URL'si, herhangi bir Solana işlemi için etkileşimli bir talep açıklar.

solana:<link>

Talep etkileşimlidir çünkü URL'deki parametreler, cüzdan tarafından bir işlem oluşturmak için HTTP isteği yapmak amacıyla kullanılır.

Bağlantı

Yol adı olarak tek bir link alanı gereklidir. Değer, koşullu olarak URL kodlanmış mutlak bir HTTPS URL'si olmalıdır.

URL sorgu parametreleri içeriyorsa, URL kodlanmış olmalıdır. Bu spesifikasyona protokol sorgu parametreleri eklenebilir. Değeri URL kodlamak, protokol parametreleriyle çakışmayı önler.

URL sorgu parametreleri içermiyorsa, URL kodlanmamalıdır. Bu, daha kısa bir URL ve daha az yoğun bir QR kodu üretir.

Her iki durumda da, cüzdan değeri URL kod çözme ile çözmelidir. Değer URL kodlanmamışsa bunun bir etkisi olmaz. Kod çözülmüş değer mutlak bir HTTPS URL'si değilse, cüzdan bunu hatalı biçimli olarak reddetmelidir.

GET İsteği

Cüzdan, URL'ye bir HTTP GET JSON isteği yapmalıdır. İstek, cüzdanı veya kullanıcıyı tanımlamamalıdır.

Cüzdan, isteği bir Accept-Encoding başlığı ile yapmalı ve uygulama, HTTP sıkıştırması için bir Content-Encoding başlığı ile yanıt vermelidir.

Cüzdan, istek yapılırken URL'nin alan adını görüntülemelidir.

GET Yanıtı

Cüzdan, HTTP istemci hatası, sunucu hatası ve yönlendirme yanıtlarını işlemelidir. Uygulama bunlarla veya aşağıdaki gövdeye sahip bir HTTP OK JSON yanıtıyla yanıt vermelidir:

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

<label> değeri, işlem isteğinin kaynağını açıklayan bir UTF-8 dizesi olmalıdır. Örneğin, bu isteği yapan bir markanın, mağazanın, uygulamanın veya kişinin adı olabilir.

<icon> değeri, bir simge görselinin mutlak HTTP veya HTTPS URL'si olmalıdır. Dosya bir SVG, PNG veya WebP görseli olmalıdır, aksi takdirde cüzdan bunu hatalı biçimlendirilmiş olarak reddetmelidir.

Cüzdan, yanıtı yalnızca HTTP önbellekleme yanıt başlıklarının talimatlarına uygun olarak önbelleğe almalıdır.

Cüzdan, etiketi görüntülemeli ve simge görselini kullanıcıya göstermelidir.

POST İsteği

Cüzdan, URL'ye aşağıdaki gövdeye sahip bir HTTP POST JSON isteği yapmalıdır:

{ "account": "<account>" }

<account> değeri, işlemi imzalayabilecek bir hesabın base58 kodlu genel anahtarı olmalıdır.

Cüzdan, isteği bir Accept-Encoding başlığı ile yapmalıdır ve uygulama, HTTP sıkıştırması için bir Content-Encoding başlığı ile yanıt vermelidir.

Cüzdan, istek yapılırken URL'nin alan adını görüntülemelidir. Eğer bir GET isteği yapıldıysa, cüzdan ayrıca etiketi görüntülemeli ve yanıttaki simge görselini göstermelidir.

POST Yanıtı

Cüzdan, HTTP istemci hatası, sunucu hatası ve yönlendirme yanıtlarını işlemelidir. Uygulama bunlarla veya aşağıdaki gövdeye sahip bir HTTP OK JSON yanıtıyla yanıt vermelidir:

{ "transaction": "<transaction>" }

<transaction> değeri, base64 ile kodlanmış bir serileştirilmiş işlem olmalıdır. Cüzdan, işlemi base64 ile çözmeli ve serileştirmesini kaldırmalıdır.

Uygulama, kısmen veya tamamen imzalanmış bir işlemle yanıt verebilir. Cüzdan, işlemi güvenilmez olarak doğrulamalıdır.

Boş İmzalar

İşlemin signatures boş ise:

• Uygulama, feePayer değerini istekteki account veya sıfır değerine (new PublicKey(0) veya new PublicKey("11111111111111111111111111111111")) ayarlamalıdır.
• Uygulama, recentBlockhash değerini en son blok hash'ine veya sıfır değerine (new PublicKey(0).toBase58() veya "11111111111111111111111111111111") ayarlamalıdır.
• Cüzdan, işlemdeki feePayer değerini yoksaymalı ve feePayer değerini istekteki account olarak ayarlamalıdır.
• Cüzdan, işlemdeki recentBlockhash değerini yoksaymalı ve recentBlockhash değerini en son blok hash'i olarak ayarlamalıdır.

İşlemin signatures boş değilse:

• Uygulama, feePayer değerini ilk imzanın genel anahtarı olarak ayarlamalıdır.
• Uygulama, recentBlockhash değerini en son blok hash'i olarak ayarlamalıdır.
• Uygulama, işlemi imzalamadan önce serileştirmeli ve serileştirmesini kaldırmalıdır. Bu, bu sorun için bir geçici çözüm olarak hesap anahtarlarının tutarlı sıralamasını sağlar.
• Cüzdan, feePayer ve recentBlockhash değerlerini ayarlamamalıdır.
• Cüzdan, imzaları doğrulamalı ve herhangi biri geçersizse, cüzdan işlemi hatalı biçimlendirilmiş olarak reddetmelidir.

Cüzdan, işlemi yalnızca istekteki account ile imzalamalı ve bunu yalnızca istekteki account için bir imza bekleniyorsa yapmalıdır.

İstekteki account için bir imza dışında herhangi bir imza bekleniyorsa, cüzdan işlemi kötü niyetli olarak reddetmelidir.

Uygulama ayrıca yanıt gövdesinde isteğe bağlı bir message alanı içerebilir:

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

<message> değeri, işlem yanıtının niteliğini açıklayan bir UTF-8 dizesi olmalıdır.

Örneğin, bu satın alınan bir ürünün adı, satın alma işlemine uygulanan bir indirim veya bir teşekkür notu olabilir. Cüzdan bu değeri kullanıcıya görüntülemelidir.

Cüzdan ve uygulama, gelecekteki spesifikasyonlar tarafından eklenebilecek istek gövdesi ve yanıt gövdesinde ek alanlar içerebilmelidir.

Örnek

İşlem isteğini açıklayan URL.

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

Sorgu parametreleriyle işlem isteğini açıklayan URL.

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

GET İsteği

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

GET Yanıtı

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 İsteği

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 Yanıtı

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"}

Uzantılar

Uygulamalar ve cüzdanlarla uyumluluğu sağlarken yeni kullanım senaryolarını desteklemek için bu spesifikasyona ek formatlar ve alanlar dahil edilebilir.

Uygulama ve cüzdan geliştiricilerinden geri bildirim almak için spesifikasyonda değişiklik önermek üzere lütfen bir Github sorunu açın.

Böyle bir önerinin gerçek bir örneği.