Action'lar ve Blinkler

Solana Actions, Solana blok zincirindeki işlemlerin önizlenmesini, imzalanmasını ve QR kodları, düğmeler + widget'lar ve internet üzerindeki web siteleri de dahil olmak üzere çeşitli bağlamlarda gönderilmesini sağlayan spesifikasyon uyumlu API'lerdir. Action'lar, geliştiricilerin Solana ekosisteminde yapabileceğiniz şeyleri doğrudan ortamınıza entegre etmelerini kolaylaştırarak farklı bir uygulamaya veya web sayfasına gitmenize gerek kalmadan blok zinciri işlemlerini gerçekleştirmenize olanak tanır.

Blok zinciri bağlantıları - ya da blinkler - herhangi bir Solana Action'ı paylaşılabilir, meta veri açısından zengin bir bağlantıya dönüştürür. Blinkler, Action'a duyarlı kullanıcı uygulamalarının (tarayıcı uzantısı cüzdanları, botlar) kullanıcı için ek özellikler görüntülemesine olanak tanır. Bir web sitesinde, bir blink, merkezsizleştirilmiş bir uygulamaya gitmeden bir cüzdanda bir işlem önizlemesini hemen tetikleyebilir; Discord'da bir bot, blink'i etkileşimli bir düğme kümesine genişletebilir. Bu, zincirin üzerinde etkileşim kurma becerisini bir URL görüntüleyebilen herhangi bir ağ yüzeyine taşır.

Get Started #

To quickly get started with creating custom Solana Actions:

npm install @solana/actions

• install the Solana Actions SDK in your application
• build an API endpoint for the GET request that returns the metadata about your Action
• create an API endpoint that accepts the POST request and returns the signable transaction for the user

When deploying your custom Solana Actions to production:

• ensure your application has a valid actions.json file at the root of your domain
• ensure your application responds with the required Cross-Origin headers on all Action endpoints, including the actions.json file

If you are looking for inspiration around building Actions and blinks, checkout the Awesome Blinks repository for some community creations and even ideas for new ones.

Actions #

Solana Actions spesifikasyonu, imzalanabilir işlemleri (ve nihayetinde imzalanabilir mesajları) bir uygulamadan doğrudan bir kullanıcıya sunmak için bir dizi standart API kullanır. Herkese açık URL'lerde barındırılırlar ve bu nedenle herhangi bir kullanıcının etkileşime girmesi için URL'leri ile erişilebilirler.

Actions API, bir Action'ın URL uç noktasına basit GET ve POST istekleri yapmak ve Actions arayüzüne uygun yanıtları işlemekten oluşur.

1. GET isteği, kullanıcılara bu URL'de hangi eylemlerin mevcut olduğu hakkında okunabilir bilgiler sağlayan meta verileri ve ilgili Actions'ların isteğe bağlı bir listesini döndürür.
2. POST isteği, imzalanabilir bir işlem veya mesaj döndürür ve bunun ardından kullanıcı cüzdanından blok zincirinde veya başka bir zincir dışı hizmette imzalamasını ve yürütmesini ister.

Action Yürütme ve Yaşam Döngüsü #

Pratikte, Action'lar ile etkileşim tipik bir REST API ile etkileşime çok benzer:

• Bir kullanıcı, mevcut Action'lar hakkındaki meta verileri almak için bir Action URL'sine ilk GET isteğini yapar
• Rest API uç noktası, uç nokta hakkındaki meta verileri (uygulamanın başlığı ve simgesi gibi) ve bu uç nokta için kullanılabilir eylemlerin bir listesini içeren bir yanıt döndürür
• Kullanıcı uygulaması (mobil cüzdan, sohbet botu veya web sitesi gibi) kullanıcının eylemlerden birini gerçekleştirmesi için bir kullanıcı arayüzü görüntüler
• Kullanıcı, bir eylem seçtikten sonra (bir düğmeye tıklayarak) uygulama, kullanıcının imzalayacağı işlemi almak için uç noktaya bir POST isteği yapar
• Cüzdan, kullanıcının işlemi imzalamasını kolaylaştırır ve nihayetinde işlemi onay için blok zincirine gönderir

Solana Actions Execution and Lifecycle

Bir Actions URL'sinden işlem alırken, kullanici uygulamalari bu işlemlerin blok zincirine gönderilmesini sağlamalı ve durum yaşam döngülerini yönetmelidir.

Actions ayrıca yürütmeden önce bir miktar iptal işlemini de destekler. GET ve POST isteği, action'ın gerçekleştirilip gerçekleştirilemeyeceğini belirten bazı meta veriler döndürebilir (disabled alanında olduğu gibi).

Örneğin, oylama penceresi kapanmış olan bir DAO teklifinin oylanmasını kolaylaştıran bir Action uç noktası varsa, ilk GET isteği "Bu teklif artık oylamaya açık değil" hata mesajını ve "Evet Oyu Ver" ve "Hayır Oyu Ver" düğmelerini "devre dışı" olarak döndürebilir.

Blinks #

Blinkler (blok zinciri bağlantıları), Action API'lerini gözlemleyen ve Action'larla etkileşim kurmak ve bunları yürütmek için kullanıcı arayüzleri oluşturan kullanıcı uygulamalarıdır.

Blinkleri destekleyen kullanıcı uygulamaları basitçe Action uyumlu URL'leri tespit eder, bunları ayrıştırır ve kullanıcıların standartlaştırılmış kullanıcı arayüzlerinde bunlarla etkileşime girmesine olanak tanır.

Blink URL Teknik Özellikler #

Bir blink URL'si, kullanıcının cüzdanıyla imzalama da dahil olmak üzere bir Action'ı yürütmenin tüm yaşam döngüsünü tamamlamasını sağlayan bir kullanıcı uygulamasını tanımlar.

https://example.domain/?action=<action_url>

Herhangi bir kullanıcı uygulamasının blink olabilmesi için:

• Blink URL'si, değeri URL kodlu bir Action URL'si olan bir Action sorgu parametresi içermelidir. Bu değer, diğer protokol parametreleriyle çakışmaması için URL kodlu olmalıdır.

• Kullanıcı uygulaması, Action sorgu parametresinin URL kodunu çözmeli ve sağlanan Action API bağlantısını incelemelidir (bkz. Action URL şeması).

• Kullanıcı uygulaması, kullanıcının cüzdanı ile imzalama da dahil olmak üzere bir Actions yürütmenin tüm yaşam döngüsünü tamamlamasını sağlayan zengin bir kullanıcı arayüzü oluşturmalıdır.

Aşağıdaki örnek, URL kodlu solana-action:https://actions.alice.com/donate action değerine sahip geçerli bir blink URL'sini göstermektedir:

https://example.domain/?action=solana-action%3Ahttps%3A%2F%2Factions.alice.com%2Fdonate

Actions'ları Blink'ler ile Algılama #

Blinkler, Actions'lar ile en az 3 şekilde bağlanabilir:

1. Açık bir Action URL'si paylaşma: solana-action:https://actions.alice.com/donate

   Bu durumda, yalnızca desteklenen uygulamalar blink oluşturabilir. Yedek bağlantı önizlemesi veya desteklenmeyen uygulama dışında ziyaret edilebilecek bir site olmayacaktır.

2. Web sitesinin alan adı kök dizinindeki actions.json dosyası aracılığıyla bir Actions API'ye bağlı bir web sitesine bağlantı paylaşma.

   Örneğin, https://alice.com/actions.json, kullanıcıların Alice'e bağış yapabileceği bir web sitesi URL'si olan https://alice.com/donate'i, Alice'e bağış yapmak için Action'ların barındırıldığı API URL'si https://actions.alice.com/donate ile eşleştirir.

3. Bir Action URL'sini, Action'ların nasıl ayrıştırılacağını anlayan bir " ara geçiş" site URL'sine gömmek.

   https://example.domain/?action=<action_url>
   

Blinkleri destekleyen uygulamalar, yukarıdaki formatlardan herhangi birini alabilmeli ve Action'ın doğrudan kullanıcı uygulamasının yürütülmesini kolaylaştırmak için doğru bir arayüz oluşturabilmelidir.

Blinkleri desteklemeyen kullanıcı uygulamaları için altyapı sağlayan web sitesi olmalıdır (tarayıcıyı evrensel yedek haline getirir).

Bir kullanıcı, kullanıcı uygulaması üzerinde aksiyon düğmesi veya metin giriş alanı olmayan herhangi bir yere dokunursa, temel siteye yönlendirilmelidir.

Blink Test ve Doğrulaması #

Solana Actions ve blinks izne tabi olmayan bir protokol/spesifikasyon olsa da, istemci uygulamaları ve cüzdanların, kullanıcıların işlemi imzalamasını nihai olarak kolaylaştırması gerekmektedir.

Bu kullanıcı uygulamalarının veya cüzdanlarının her biri, müşterilerinin hangi Action uç noktalarını otomatik olarak açacağı ve sosyal medya platformlarında kullanıcılarına hemen göstereceği konusunda farklı gereksinimlere sahip olabilir.

Örneğin, bazı kullanıcı uygulamaları, Dialect'in Actions Registry'si (aşağıda ayrıntılı olarak açıklanmıştır) gibi kullanıcılar için bir Action'ı açmadan önce doğrulama gerektirebilecek bir "izin listesi" yaklaşımıyla çalışabilir.

Tüm blinkler, Dialect'in dial.to blinks Interstitial sitesinde imzalanmaya devam edecek ve kayıt durumları blinkte görüntülenecektir.

Diyalekt'in Actions Registery'si #

Solana ekosistemi için bir ortak fayda olarak [Dialect] (https://dialect.to), Solana Foundation ve diğer topluluk üyelerinin yardımıyla, bilinen kaynaklardan önceden doğrulanmış blok zinciri bağlantılarının kamuya açık bir kaydını tutar. Başlangıçtan itibaren, yalnızca Dialect registery kaydedilen Eylemler yayınlandığında Twitter akışında açılacaktır.

Kullanıcı uygulamaları ve cüzdanlar, kullanıcı güvenliğini ve emniyetini sağlamaya yardımcı olmak için bu genel kayıt defterini veya başka bir çözümü kullanmayı özgürce seçebilir. Dialect kayıt defteri aracılığıyla doğrulanmazsa, blok zinciri bağlantısına blink istemcisi tarafından dokunulmayacak ve tipik bir URL olarak işlenecektir.

Geliştiriciler Dialect tarafından doğrulanmak için buradan başvurabilirler: dial.to/register

Teknik Özellikler #

Solana Actions spesifikasyonu, bir istek/yanıt etkileşim akışının parçası olan temel bölümlerden oluşur:

• Bir Action URL'si sağlayan Solana Action URL şeması
• CORS gereksinimlerini geçmek için bir Eylem URL'sine OPTIONS yanıtı.
• Bir Action URL'sine GET isteği
• Sunucudan gelen GET yanıtı
• Action URL'sine POST isteği
• Sunucudan POST yanıtı

Bu taleplerin her biri, zengin kullanıcı arayüzleri için belirli meta verileri toplamak ve Actions API'ye kullanıcı girişini kolaylaştırmak amacıyla Action uygulaması (örn. cüzdan uygulaması, tarayıcı uzantısı, dApp, web sitesi vb.) tarafından yapılır.

Yanıtların her biri bir uygulama (ör. web sitesi, sunucu arka ucu, vb.) tarafından hazırlanır ve Action kullanıcı uygulamasına geri gönderilir. Nihayetinde, kullanıcıdan onaylamasını, imzalamasını ve blok zincirine göndermesini istemek için bir cüzdan için imzalanabilir bir işlem veya mesaj sağlar.

URL Şeması #

Bir Solana Action URL'si, solana-action protokolünü kullanarak imzalanabilir bir Solana işlemi veya mesajı için etkileşimli bir isteği tanımlar.

İstek etkileşimlidir çünkü URL'deki parametreler bir uygulama tarafından, kullanıcının cüzdanıyla imzalaması için imzalanabilir bir işlem veya mesaj oluşturmak üzere bir dizi standartlaştırılmış HTTP isteği yapmak için kullanılır.

solana-action:<link>

• Yol adı olarak tek bir bağlantı alanı gereklidir. Yol adı, koşullu olarak URL kodlamalı mutlak HTTPS URL'si olmalıdır.

• URL sorgu parametreleri içeriyorsa, URL kodlu olmalıdır. Değerin URL ile kodlanması, protokol belirtimi aracılığıyla eklenebilecek herhangi bir Actions protokol parametresiyle çakışmayı önler.

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

Her iki durumda da, kullanıcı uygulamaları URL kodunun değerini çözmelidir. Değer, URL kodlu değilse bunun bir etkisi yoktur. Kodu çözülen değer mutlak bir HTTPS URL'si değilse, cüzdan bunu hatalı biçimlendirilmiş olarak reddetmelidir.

OPTIONS Yanıtı #

Actions uygulamaları ("blink" dahil) içinde Çapraz Kaynak Paylaşımına (CORS) izin vermek için, tüm Action uç noktaları OPTIONS yöntemi için HTTP isteklerine, istemcilerin aynı kaynak etki alanından gelen sonraki tüm istekler için CORS kontrollerini geçmesine izin verecek geçerli başlıklarla yanıt vermelidir.

Bir Actions uygulaması, Action URL'sine yönelik sonraki GET isteğinin tüm CORS kontrollerini geçip geçmeyeceğini kontrol etmek için Action URL uç noktasına "[preflight](https://developer.mozilla.org/en US/docs/Web/HTTP/CORS#preflighted_requests)" istekleri gerçekleştirebilir. Bu CORS ön kontrolleri OPTIONS HTTP yöntemi kullanılarak yapılır ve Action uygulamasının (blinks gibi) kaynak etki alanlarından sonraki tüm istekleri düzgün bir şekilde yapmasına izin verecek tüm gerekli HTTP başlıklarıyla yanıt vermelidir.

En azından gerekli HTTP üstbilgileri şunları içerir:

• * değerine sahip Access-Control-Allow-Origin
  • bu, tüm Action uygulamalarının gerekli tüm istekleri yapmak için CORS kontrollerini güvenli bir şekilde geçebilmesini sağlar
• GET,POST,PUT,OPTIONSdeğerine sahipAccess-Control-Allow-Methods`
  • Actions için gerekli tüm HTTP istek yöntemlerinin desteklenmesini sağlar
• Minimum değeri Access-Control-Allow-Headers olan Content-Type, Authorization, Content-Encoding, Accept-Encoding

Basitlik açısından, geliştiriciler OPTIONS isteklerine [GET yanıtı] (#get-response) ile aynı yanıtı ve üstbilgileri döndürmeyi düşünmelidir.

GET İsteği #

Action istemcisi (ör. cüzdan, tarayıcı uzantısı vb.) Action URL uç noktasına bir HTTP GET JSON isteği yapmalıdır.

• İstek, cüzdanı veya kullanıcıyı tanımlamamalıdır.
• Kullanıcı uygulaması, isteği [Accept-Encoding] başlığı ile yapmalıdır.
• Kullanıcı uygulaması, istek yapılırken URL'nin alan adını göstermelidir.

GET Yanıtı #

Action URL uç noktası (ör. uygulama veya sunucu arka ucu), HTTP OK JSON yanıtı (geçerli bir yük ile) veya uygun bir HTTP hatası ile yanıt vermelidir.

• Kullanıcı uygulaması, HTTP kullanıcı uygulaması hataları, sunucu hataları ve yönlendirme yanıtları ile başa çıkmalıdır.

• Uç nokta, HTTP sıkıştırması için [Content-Encoding] başlığı ile yanıt vermelidir.

• Endpoint, application/json içerik türünde bir Content-Type başlığı ile yanıt vermelidir.

• Kullanıcı uygulaması, HTTP önbelleğini kontrol eden yanıt başlıklarında belirtilen şekilde talimat verilmediği sürece yanıtı önbelleğe almamalıdır.

• Kullanıcı uygulaması, "title"ı göstermeli ve kullanıcıya "icon" görüntüsünü sunmalıdır.

GET Yanıt Gövdesi #

HTTP OK JSON yanıtı içeren bir GET yanıtı bir gövde yükü içermelidir arayüz spesifikasyonunu şöyledir:

export interface ActionGetResponse {
  /** action isteğinin kaynağını temsil eden resim url'si */
  icon: string;
  /** action talebinin kaynağını açıklar */
  title: string;
  /** gerçekleştirilecek actinon'ın kısa özeti */
  description: string;
  /** kullanıcıya gösterilen düğme metni */
  label: string;
  /** Kullanıcıya gösterilen düğme için UI durumu */
  disabled?: boolean;
  links?: {
    /** Bir kullanıcının gerçekleştirebileceği ilgili Action'ların listesi */
    actions: LinkedAction[];
  };
  /** kullanıcıya gösterilecek önemli olmayan hata mesajı */
  error?: ActionError;
}

• icon - Değer, bir simge görüntüsünün mutlak HTTP veya HTTPS URL'si olmalıdır. Dosya bir SVG, PNG veya WebP görüntüsü olmalıdır veya kullanıcı uygulaması / cüzdan bunu hatalı biçimlendirilmiş olarak reddetmelidir.

• title - Değer, action isteğinin kaynağını temsil eden bir UTF-8 dizesi olmalıdır. Örneğin, bu bir markanın, mağazanın, uygulamanın veya talebi yapan kişinin adı olabilir.

• description - Değer, action hakkında bilgi sağlayan bir UTF-8 dizesi olmalıdır. Açıklama kullanıcıya gösterilmelidir.

• label - Değer, kullanıcının tıklaması için bir düğme üzerinde oluşturulacak bir UTF-8 dizesi olmalıdır. Tüm etiketler 5 kelimelik ifadeleri geçmemeli ve kullanıcının yapmasını istediğiniz actioni'ı somutlaştırmak için bir fiil ile başlamalıdır. Örneğin, "Mint NFT", "Vote Yes" veya "Stake 1 SOL".

• disabled - Değer, devre dışı durumunu temsil etmek için boolean olmalıdır. işlenmiş düğme (label dizesini görüntüler). Eğer herhangi bir değer belirtilmezse, disabled varsayılan olarak false (yani varsayılan olarak etkin) olmalıdır. Örneğin, action uç noktası yönetim oylamasının kapanması içinse, setdisabled=true ve label "Vote Closed" olabilir.

• error - Önemli olmayan hatalar için isteğe bağlı bir hata göstergesi. Mevcutsa, kullanıcı uygulaması bunu kullanıcıya göstermelidir. Ayarlanırsa, kullanıcı uygulamasının eylemini yorumlamasını veya kullanıcıya görüntülemesini engellememelidir. Örneğin, hata, iş kısıtlamaları, yetkilendirme, durum veya dış kaynak hatası gibi nedenleri göstermek için devre dışı ile birlikte kullanılabilir.

export interface ActionError {
  /** kullanıcıya gösterilecek önemli olmayan hata mesajı */
  message: string;
}

• links.actions - Uç nokta için ilgili action'ların isteğe bağlı bir dizisi. Kullanıcılara listelenen eylemlerin her biri için UI gösterilmeli ve yalnızca birini gerçekleştirmeleri beklenmelidir. Örneğin, bir yönetişim oylaması eylem uç noktası kullanıcı için üç seçenek döndürebilir: "Evet Oyu Ver", "Hayır Oyu Ver" ve "Oylamada Çekimser Kal".

  • Eğer links.actions belirtilmemişse, kullanıcı uygulaması label dizesini kullanarak tek bir düğme oluşturmalı ve POST isteğini ilk GET isteği ile aynı action URL uç noktasına yapmalıdır.

  • Herhangi bir links.actions' sağlanmışsa, kullanıcı uygulaması yalnızca links.actions' alanında listelenen öğelere göre butonları ve giriş alanlarını oluşturmalıdır. Kullanıcı uygulaması, kök label içeriği için bir buton oluşturmamalıdır.

export interface LinkedAction {
  /** Bir action için URL uç noktası */
  href: string;
  /** kullanıcıya gösterilen buton metni */
  label: string;
  /** Bir action içinde kullanıcı girdisini kabul etmek için parametre */
  parameters?: [ActionParameter];
}
 
/** Bir action içinde kullanıcı girdisini kabul etmek için parametre */
export interface ActionParameter {
  /** url'deki parametre adı */
  name: string;
  /** kullanıcı giriş alanı için yer tutucu metin */
  label?: string;
  /** bu alanın gerekli olup olmadığını bildirir (varsayılan değer `false`) */
  required?: boolean;
}

Örnek GET Yanıtı #

Aşağıdaki örnek yanıt, kullanıcıya "Erişim Token'ı Talep Et" etiketiyle tek bir düğme olarak sunulması beklenen tek bir "kök" eylemi sağlar.

{
  "title": "HackerHouse Etkinlikleri",
  "icon": "<url-to-image>",
  "description": "HackerHouse erişim token'larını talep edin.",
  "label": "Erişim Jetonunu Talep Et" // buton metni
}

Aşağıdaki örnek yanıt, kullanıcının bir DAO önerisi için oy vermek üzere 3 butondan birine tıklamasına olanak tanıyan 3 ilgili action bağlantısı sağlar:

{
  "title": "Realms DAO Platformu",
  "icon": "<url-to-image>",
  "description": "DAO yönetim önerisi #1234 için oy verinç",
  "label": "Oy Ver",
  "links": {
    "actions": [
      {
        "label": "Evet Oyu Ver", // buton metni
        "href": "/api/proposal/1234/vote?choice=yes"
      },
      {
        "label": "Hayır Oyu Ver", // buton metni
        "href": "/api/proposal/1234/vote?choice=no"
      },
      {
        "label": "Oy Kullanma", // buton metni
        "href": "/api/proposal/1234/vote?choice=abstain"
      }
    ]
  }
}

Parametrelerle birlikte örnek GET Yanıtı #

Aşağıdaki örnekler, kullanıcıdan metin girişi kabul etmenin (parametreler aracılığıyla) ve bu girişi nihai POST isteği uç noktasına (LinkedAction içindeki href alanı aracılığıyla) dahil etmenin nasıl yapıldığını göstermektedir:

Aşağıdaki örnek cevap, kullanıcıya SOL yatırma için 3 bağlantılı işlem sunar: "Stake 1 SOL" adlı bir buton, "Stake 5 SOL" adlı başka bir buton ve kullanıcının belirli bir "amount" değerini girmesine izin veren bir metin giriş alanı. Bu girilen "amount" değeri, Action API'sine gönderilecek:

```json
{
  "title": "Stake-o-matic",
  "icon": "<url-to-image>",
  "description": "Stake SOL to help secure the Solana network.",
  "label": "Stake SOL", // `links.actions` sağlandığı için görüntülenmez
  "links": {
    "actions": [
      {
        "label": "Stake 1 SOL", // buton metni
        "href": "/api/stake?amount=1"
        // `parameters` olmadığı için metin giriş alanı değil
      },
      {
        "label": "Stake 5 SOL", // buton metni
        "href": "/api/stake?amount=5"
        // `parameters` olmadığı için metin giriş alanı değil
      },
      {
        "label": "Amount to stake", // metin giriş yer tutucu metni
        "href": "/api/stake?amount={amount}",
        "parameters": [
          {
            "name": "amount", // alan adı
            "label": "SOL amount" // metin giriş yer tutucu
          }
        ]
      }
    ]
  }
}
```

Aşağıdaki örnek yanıt, kullanıcının girebileceği bir amount (miktar) giriş alanı sağlar ve bu miktar POST isteğiyle gönderilir (ya bir sorgu parametresi olarak ya da bir alt yol olarak kullanılabilir):

{
  "icon": "<url-to-image>",
  "label": "SOL Bağışı",
  "title": "İyi Nedenler Derneği'ne Bağış Yapın",
  "description": "Bu derneği SOL bağışı yaparak destekleyin.",
  "links": {
    "actions": [
      {
        "label": "Bağış Yap", // buton metni
        "href": "/api/donate/{amount}", // veya /api/donate?amount={amount}
        "parameters": [
          // {amount} giriş alanı
          {
            "name": "amount", // giriş alanı adı
            "label": "SOL miktarı" // metin girişi yer tutucusu
          }
        ]
      }
    ]
  }
}

POST İsteği #

Kullanıcı uygulaması, şu gövde yüküyle birlikte eylem URL'sine bir HTTP POST JSON isteği yapmalıdır:

{
  "account": "<account>"
}

• account - Değer, işlemi imzalayabilecek bir hesabın base58 kodlu genel anahtarı olmalıdır.

Kullanıcı uygulaması, HTTP Sıkıştırması(Compression) için bir Accept-Encoding başlığı ile isteği yapmalıdır ve uygulama, HTTP sıkıştırması için bir Content-Encoding başlığı ile yanıt vermelidir.

İstek yapılırken kullanıcı uygulaması, Action URL'sinin alanını görüntülemelidir. Eğer bir GET isteği yapıldıysa, kullanıcı uygulaması ayrıca title'ı görüntülemeli ve bu GET yanıtından icon görüntüsünü oluşturmalıdır.

POST Yanıtı #

Action'ın POST uç noktası, geçerli bir yük içeren bir HTTP OK JSON yanıtı veya uygun bir HTTP hatasıyla yanıt vermelidir.

• Kullanıcı uygulaması, HTTP Kullanıcı uygulaması hatalarını, sunucu hatalarını ve yönlendirme yanıtlarını işlemelidir.
• Uç nokta, application/json içerik türünde bir Content-Type başlığı ile yanıt vermelidir.

POST Yanıt Gövdesi #

Bir HTTP OK JSON yanıtı ile birlikte gönderilecek bir POST yanıtı için gövde yükü şöyle olmalıdır:

export interface ActionPostResponse {
  /** base64 kodlu seri işlem */
  transaction: string;
  /** işlemin doğasını açıklar */
  message?: string;
}

• transaction - bu değer, bir seri işlem olan base64 kodlanmış olmalıdır. Kullanıcı uygulaması, işlemi base64'e çözüp bu bağlamda serileştirmelidir.

• message - bu değer, yanıt içinde bulunan işlemin doğasını açıklayan UTF-8 biçiminde bir dize olmalıdır. Kullanıcı uygulaması, bu değeri kullanıcıya göstermelidir. Örneğin, bu satın alınan bir öğenin adı, bir satın alma işlemine uygulanan bir indirim veya bir teşekkür notu olabilir.

• Kullanıcı uygulaması ve uygulama, gelecekteki belirti güncellemeleri tarafından eklenebilecek istek gövdesi ve yanıt gövdesindeki ek alanları kabul etmelidir.

POST Yanıtı - İşlem #

Eğer işlemdeki signatures boş değilse:

• Cüzdan, işlemdeki feePayer değerini yok saymalı ve feePayer değerini istekteki account olarak ayarlamalıdır.
• Kullanıcı uygulaması, işlemdeki recentBlockhash değerini yok saymalı ve recentBlockhash değerini en son blockhash'e ayarlamalıdır.
• Kullanıcı uygulaması, işlemi imzalamadan önce seri hale getirip serileştirmelidir. Bu, bu sorun için bir geçici çözüm olarak hesap anahtarlarının tutarlı sıralanmasını sağlar.

İşlem kısmen imzalanmışsa:

• Kullanıcı uygulaması, feePayer ve recentBlockhash değerlerini ayarlamamalıdır.
• Kullanıcı uygulaması, imzaları doğrulamalı ve geçersiz olan varsa işlemi hatalı biçimli olarak reddetmelidir.

Kullanıcı uygulaması, işlemi sadece istekteki account ile imzalamalı ve bunu sadece istekteki account için bir imza bekleniyorsa yapmalıdır.

Eğer istekteki account için olmayan bir imza bekleniyorsa, kullanıcı uygulaması işlemi kötü niyetli olarak reddetmelidir.

actions.json #

actions.json dosyasının amacı, bir uygulamanın kullanıcı uygulamalarına Solana Actions'ı destekleyen web sitesi URL'lerini hangilerinin desteklediği hakkında talimat vermek ve Actions API sunucusuna GET istekleri yapmak için kullanılabilecek bir eşleme sağlamaktır.

actions.json dosyası, alan adının kökünde saklanmalı ve evrensel olarak erişilebilir olmalıdır.

Örneğin, web uygulamanız my-site.com adresine dağıtıldıysa, actions.json dosyasına https://my-site.com/actions.json adresinden erişilebilir olmalıdır. This file should also be Cross-Origin accessible via any browser by having a Access-Control-Allow-Origin header value of *.

Kurallar #

rules (kurallar) alanı, bir uygulamanın bir web sitesinin göreceli yol yollarını başka bir yol kümesine eşlemesine izin verir.

Tür ActionRuleObject in dizisi.

interface ActionRuleObject {
  pathPattern: string; // kural eşlemesini yapmak için göreceli (tercih edilen) veya mutlak yol
  apiPath: string; // Action isteklerini destekleyen göreceli (tercih edilen) veya mutlak yol
}

• pathPattern - Gelen her yol adıyla eşleşen bir desen.

• apiPath - Mutlak bir yol adı veya harici bir URL olarak tanımlanan bir konum hedefi.

Kurallar - yolDeseni #

Gelen her yol adıyla eşleşen bir desen. Bu, mutlak veya göreceli bir yol olabilir ve aşağıdaki biçimleri destekler:

• Tam Eşleme: Tam URL yolunu eşleştirir.

  • Örnek: /tam-yol
  • Örnek: https://website.com/tam-yol

• Joker Eşleme: URL yolunda herhangi bir karakter dizisini eşleştirmek için joker karakterler kullanır. Bu, tek bir bölümü (* kullanarak) veya birden çok bölümü (** kullanarak) eşleştirebilir. (Bkz. Aşağıdaki Yol Eşleme).

  • Örnek: /trade/*, /trade/123 ve /trade/abc'yi eşleştirecek ve /trade/ sonrasındaki ilk bölümü yakalayacak.
  • Örnek: /category/*/item/**, /cateogry/123/item/456 ve /category/abc/item/def'yi eşleştirir.
  • Örnek:/api/actions/trade/*/confirm,/api/actions/trade/123/confirm i eşleştirir.

Kurallar - apiYolu #

Action isteği için hedef yol. Mutlak bir yol adı veya harici bir URL olarak tanımlanabilir.

• Örnek: /api/tam-yol
• Örnek:https://api.example.com/v1/donate/*
• Örnek: /api/category/*/item/*
• Example: /api/swap/**

Kurallar - Sorgu Parametreleri #

Orijinal URL'den gelen sorgu parametreleri her zaman korunur ve eşlenen URL'ye eklenir.

Kurallar - Yol Eşleme #

Aşağıdaki tablo, yol eşleme desenleri için sözdizimini açıklar:

Kurallar Örnekleri #

Aşağıdaki örnek, istekleri sitenizin kökünden(root) /buy yoluna tam eşleşen bir kuralı göstermektedir, bu istekleri sitenizin köküne göre /api/buy tam yoluna eşleştirir:

{
  "rules": [
    {
      "pathPattern": "/buy",
      "apiPath": "/api/buy"
    }
  ]
}

Aşağıdaki örnek, sitenizin kökünden /actions/' altındaki herhangi bir yola (alt dizinler hariç) gelen istekleri sitenizin köküne göre /api/actions/' altındaki karşılık gelen bir yolla eşleştirmek için joker yol eşleştirmesini kullanır:

{
  "rules": [
    {
      "pathPattern": "/actions/*",
      "apiPath": "/api/actions/*"
    }
  ]
}

Aşağıdaki örnek, joker karakter yol eşleştirme kullanarak, sitenizin kökünden /donate/ altındaki herhangi bir yol (alt dizinler dahil) isteğini, harici bir site olan https://api.dialect.com/api/v1/donate/ adresindeki karşılık gelen mutlak yola eşleştirir:

{
  "rules": [
    {
      "pathPattern": "/donate/*",
      "apiPath": "https://api.dialect.com/api/v1/donate/*"
    }
  ]
}

Aşağıdaki örnek, /api/actions/ kökü altındaki herhangi bir yol (alt dizinler dahil) için istekleri kendine eşlemek için idempotent bir kural için joker karakter yol eşleme kullanır:

{
  "rules": [
    {
      "pathPattern": "/api/actions/**",
      "apiPath": "/api/actions/**"
    }
  ]
}

Action Kimliği #

Action uç noktaları, kullanıcı tarafından imzalanması için POST yanıtları içinde döndürülen işlemlerde bir Action Kimliği içerebilir. Bu, indeksleyicilerin ve analiz platformlarının on-chain aktiviteleri kolayca ve doğrulanabilir bir şekilde belirli bir Action Sağlayıcıya (yani hizmete) atfetmesini sağlar.

Action Kimliği, Memo talimatı kullanarak işleme dahil edilen özel biçimlendirilmiş bir mesajı imzalamak için kullanılan bir anahtar çiftidir. Bu Tanımlayıcı Mesaj, belirli bir Action Kimliği'ne doğrulanabilir bir şekilde atfedilebilir ve bu şekilde işlemleri belirli bir Action Sağlayıcısına atar.

Anahtar çifti, işlemin kendisini imzalamak için gerekli değildir. Bu, cüzdanların ve uygulamaların, kullanıcının döndürülen işlemde başka imzalar olmadığında işlem teslim edilebilirliğini artırmasına olanak tanır (bkz. POST yanıt işlemi).

Bir Action Sağlayıcısının kullanım durumu, kullanıcıdan önce işlemi önceden imzalamak için arka uç hizmetlerini gerektiriyorsa, bu anahtar çiftini Action Kimliği olarak kullanmalıdır. Bu, işleme bir hesabın daha az dahil edilmesine izin vererek, toplam işlem boyutunu 32 bayt azaltır.

Action Tanımlayıcı Mesajı #

Action Tanımlayıcı Mesajı, tek bir SPL Memo talimatı kullanılarak işlem içinde yer alan, iki nokta ile ayrılmış UTF-8 dizisidir.

protocol:identity:reference:signature

• protocol - Kullanılan protokol değeri (yukarıdaki URL Şeması tarafından solana-action olarak ayarlanmış)
• identity - Bu değer, Action Kimlik anahtar çiftinin base58 kodlanmış genel anahtar adresi olmalıdır.
• reference - Değer, base58 ile kodlanmış 32 baytlık bir dizi olmalıdır. Bu, genel anahtarlar olabilir veya olmayabilir, eğri üzerinde veya dışında olabilir ve Solana'daki hesaplarla uyuşabilir veya uyuşmayabilir.
• signature - Yalnızca reference değerini imzalayan Action Kimlik anahtar çiftinden oluşturulan base58 ile kodlanmış bir imzadır.

reference değeri sadece bir kez ve tek bir işlemde kullanılmalıdır. İşlemleri bir Action Sağlayıcı ile ilişkilendirme amacıyla, reference değerinin yalnızca ilk kullanımı geçerli kabul edilir.

İşlemlerde birden fazla Memo talimatı olabilir. getSignaturesForAddress işlemi gerçekleştirirken, sonuçların memo alanı, her memo talimatının mesajını noktalı virgülle ayrılmış tek bir dize olarak döndürecektir.

Tanımlayıcı Mesajı Notu talimatının Memo talimatında başka veri bulunmamalıdır.

identity ve reference, Tanımlayıcı Mesajı Notu talimatı olmayan bir talimatta işlemde okuma-yazma olmayan, imzalamayan anahtarlar olarak dahil edilmelidir.

Tanımlayıcı Mesajı Notu talimatında hiçbir hesap belirtilmemelidir. Herhangi bir hesap sağlanırsa, Memo programının bu hesapların geçerli imzalayıcılar olmasını gerektirir. Actionsları tanımlama amaçları için, bu esnekliği sınırlar ve kullanıcı deneyimini olumsuz etkileyebilir. Bu nedenle, bu bir karşı kalıp olarak kabul edilir ve kaçınılmalıdır.

Action Kimlik Doğrulama #

identity hesabını içeren herhangi bir işlem, çok adımlı bir süreçte doğrulanabilir şekilde Action Sağlayıcı ile ilişkilendirilebilir:

1. Belirli bir identity için tüm işlemleri al.
2. Her işlemin memo dizesini ayrıştırın ve signature'ın saklanan reference için geçerli olduğundan emin olun.
3. reference on-chain üzerindeki belirli işlemin ilk on-chain oluşumu doğrulayın:
   • Bu işlem ilk kez gerçekleşiyorsa, işlem doğrulanmış kabul edilir ve güvenle Action Sağlayıcısına atfedilebilir.
   • Eğer bu işlem İLK kez gerçekleşmiyorsa, geçersiz olarak kabul edilir ve dolayısıyla Action Sağlayıcı'ya atfedilmez.

Solana doğrulayıcıları işlem bilgilerini hesap anahtarlarına göre dizinlerler, bu nedenle getSignaturesForAddress RPC yöntemi, idedntity hesabını içeren tüm işlemleri bulmak için kullanılabilir.

Bu RPC yönteminin yanıtı, tüm Memo verilerini memo alanında içerir. Eğer işlemde birden fazla Memo talimatı kullanıldıysa, her memo mesajı bu memo alanına dahil edilecek ve doğrulayıcı tarafından Kimlik Doğrulama Mesajı'nı elde etmek için buna uygun şekilde ayrıştırılmalıdır.

Bu işlemler başlangıçta DOĞRULANMAMIŞ olarak kabul edilmelidir. Bu durum, işlemi imzalamak için identity'nin gerekli olmamasından kaynaklanır, bu da herhangi bir işlemin bu hesabı imza atmayan bir katılımcı olarak içermesine izin verir. Potansiyel olarak sahiplik ve kullanım sayılarını yapay olarak artırabilir.

Kimlik Doğrulama Mesajı, signature'ın identity tarafından reference imzalanarak oluşturulduğundan emin olmak için kontrol edilmelidir. Bu imza doğrulaması başarısız olursa, işlem geçersizdir ve Action Sağlayıcısına atfedilmemelidir.

Eğer imza doğrulaması başarılı olursa, doğrulayıcı bu işlemin reference'ın zincir üzerindeki ilk gerçekleşmesi olduğundan emin olmalıdır. Eğer değilse, işlem geçersiz sayılır.