Toiminnot ja Blinkit

Solana Actions ovat määritystenmukaiset API:t, jotka palauttavat transaktioita Solana-lohkoketjussa esikatseltavaksi, allekirjoitettavaksi ja lähetettäväksi eri yhteyksissä, kuten QR-koodeissa, painikkeissa ja widgeteissä sekä verkkosivustoilla ympäri internetiä. Toiminnot helpottavat kehittäjien mahdollisuutta integroida Solana-ekosysteemin toiminnallisuuksia suoraan omaan ympäristöönsä, mahdollistaen lohkoketjutransaktioiden suorittamisen ilman siirtymistä toiseen sovellukseen tai verkkosivulle.

Blockchain-linkit – eli blinkit – muuttavat minkä tahansa Solana-toiminnon jaettavaksi, metadatarikkaiksi linkeiksi. Blinkit mahdollistavat toimintoja tukeville asiakkaille (selainlaajennuslompakot, botit) lisäominaisuuksien näyttämisen käyttäjälle. Verkkosivustolla blink saattaa välittömästi käynnistää transaktioesikatselun lompakossa ilman siirtymistä hajautettuun sovellukseen; Discordissa botti voi laajentaa blinkin interaktiiviseksi painikesarjaksi. Tämä vie lohkoketjussa toimimisen mahdollisuuden mihin tahansa verkkoympäristöön, joka pystyy näyttämään URL-osoitteen.

Aloita

Aloittaaksesi nopeasti omien Solana-toimintojen luomisen:

npm install @solana/actions

• asenna Solana Actions SDK sovellukseesi
• rakenna API-päätepiste GET-pyyntöä varten, joka palauttaa toimintosi metatiedot
• luo API-päätepiste, joka hyväksyy POST-pyynnön ja palauttaa käyttäjälle allekirjoitettavan transaktion

Katso tämä videotutoriaali Solana-toiminnon rakentamisesta käyttäen @solana/actions SDK:ta.

Löydät myös toiminnon lähdekoodin, joka suorittaa natiivit SOL-siirrot täältä, sekä useita muita esimerkkitoimintoja tästä reposta.

Kun otat omat Solana-toimintosi käyttöön tuotannossa:

• varmista, että sovelluksellasi on voimassa oleva actions.json-tiedosto verkkotunnuksesi juuressa
• varmista, että sovelluksesi vastaa vaadittujen Cross-Origin-otsikoiden kanssa kaikissa Action-päätepisteissä, mukaan lukien actions.json-tiedosto
• testaa ja virheenkorjaa blinkkisi/toimintosi käyttäen Blinks Inspector -työkalua

Jos etsit inspiraatiota toimintojen ja blinkkien rakentamiseen, tutustu Awesome Blinks -repositorioon yhteisön luomuksista ja jopa ideoista uusiin.

Toiminnot

Solana Actions -määritys käyttää standardoituja API-sarjoja toimittaakseen allekirjoitettavia transaktioita (ja lopulta allekirjoitettavia viestejä) sovelluksesta suoraan käyttäjälle. Ne sijaitsevat julkisesti saavutettavissa URL-osoitteissa ja ovat siten minkä tahansa asiakkaan käytettävissä URL-osoitteensa kautta.

Voit ajatella toimintoja API-päätepisteenä, joka palauttaa metatietoja ja jotain käyttäjän allekirjoitettavaksi (joko transaktion tai todennusviestin) lohkoketjulompakollaan.

Actions API koostuu yksinkertaisista GET- ja POST-pyynnöistä toiminnon URL-päätepisteeseen sekä Actions-rajapinnan mukaisten vastausten käsittelystä.

1. GET-pyyntö palauttaa metatietoja, jotka tarjoavat ihmisluettavaa tietoa asiakkaalle siitä, mitä toimintoja tässä URL-osoitteessa on saatavilla, sekä valinnaisen luettelon liittyvistä toiminnoista.
2. POST-pyyntö palauttaa allekirjoitettavan transaktion tai viestin, jonka asiakas pyytää käyttäjän lompakkoa allekirjoittamaan ja suorittamaan lohkoketjussa tai muussa ketjun ulkopuolisessa palvelussa.

Toiminnon suoritus ja elinkaari

Käytännössä toimintojen kanssa toimiminen muistuttaa läheisesti tavallisen REST API:n käyttöä:

• asiakas tekee alustavan GET-pyynnön toiminnon URL-osoitteeseen noutaakseen metatietoja saatavilla olevista toiminnoista
• päätepiste palauttaa vastauksen, joka sisältää metatietoja päätepisteestä (kuten sovelluksen otsikon ja kuvakkeen) sekä luettelon tämän päätepisteen saatavilla olevista toiminnoista
• asiakassovellus (kuten mobiililompakko, chat-botti tai verkkosivusto) näyttää käyttöliittymän, jossa käyttäjä voi suorittaa jonkin toiminnoista
• sen jälkeen kun käyttäjä valitsee toiminnon (napsauttamalla painiketta), asiakas tekee POST-pyynnön päätepisteeseen saadakseen käyttäjän allekirjoitettavan transaktion
• lompakko helpottaa käyttäjän transaktion allekirjoittamista ja lähettää lopulta transaktion lohkoketjuun vahvistettavaksi

Solana Actions -suoritus ja elinkaari

Vastaanottaessaan transaktioita Actions-URL-osoitteesta asiakkaiden tulisi hoitaa näiden transaktioiden lähettäminen lohkoketjuun ja hallita niiden tilaelinkaareta.

Toiminnot tukevat myös tietyntasoista mitätöintiä ennen suoritusta. GET- ja POST-pyyntö voi palauttaa metatietoja, jotka ilmaisevat, onko toiminto suoritettavissa (kuten disabled-kentän avulla).

Esimerkiksi, jos oli olemassa Action-päätepiste, joka mahdollistaa äänestämisen DAO-hallintoehdotuksesta, jonka äänestysaika on päättynyt, alkuperäinen GET-pyyntö voi palauttaa virheilmoituksen "Tästä ehdotuksesta ei enää äänestä" ja "Äänestä kyllä"- ja "Äänestä ei" -painikkeet "poistettuina käytöstä".

Blinkit

Blinkit (blockchain-linkit) ovat asiakassovelluksia, jotka tutkivat Action-API:ja ja rakentavat käyttöliittymiä toimintojen kanssa vuorovaikuttamiseen ja suorittamiseen.

Blinkkejä tukevat asiakassovellukset yksinkertaisesti havaitsevat Action-yhteensopivat URL-osoitteet, jäsentävät ne ja mahdollistavat käyttäjien vuorovaikutuksen niiden kanssa standardoiduissa käyttöliittymissä.

Mikä tahansa asiakassovellus, joka tutkii täysin Actions-API:n rakentaakseen sille täydellisen käyttöliittymän, on blink. Siksi kaikki Actions-API:ja kuluttavat asiakkaat eivät ole blinkkejä.

Blink URL -määritys

Blink URL kuvaa asiakassovellusta, jonka avulla käyttäjä voi suorittaa toiminnon elinkaaren täysin, mukaan lukien allekirjoittaminen lompakollaan.

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

Jotta jokin asiakassovellus voisi tulla blink-sovellukseksi:

• Blink URL:n on sisällettävä action-kyselyparametri, jonka arvo on URL-koodattu Action URL. Tämä arvo on URL-koodattava jotta se ei ole ristiriidassa muiden protokollaparametrien kanssa.

• Asiakassovelluksen on URL-dekoodattava action-kyselyparametri ja tutkittava annettu Action API -linkki (katso Action URL -rakenne).

• Asiakkaan on renderöitävä monipuolinen käyttöliittymä, jonka avulla käyttäjä voi suorittaa toiminnon elinkaaren täysin, mukaan lukien allekirjoittaminen lompakollaan.

Kaikki blink-asiakassovellukset (esim. verkkosivustot tai dAppit) eivät tue kaikkia toimintoja. Sovellusten kehittäjät voivat valita, mitä toimintoja he haluavat tukea blink-käyttöliittymissään.

Seuraava esimerkki osoittaa kelvollisen blink URL:n, jossa action-arvo on solana-action:https://actions.alice.com/donate URL-koodattuna:

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

Toimintojen havaitseminen blinkkien kautta

Blinkit voidaan yhdistää toimintoihin vähintään kolmella tavalla:

1. Jakamalla eksplisiittinen Action URL: solana-action:https://actions.alice.com/donate

   Tässä tapauksessa vain tuetut asiakkaat voivat renderöidä blinkin. Siinä ei ole varavaihtoehtona linkin esikatselua tai sivustoa, joka olisi käytettävissä tukemattomien asiakkaiden ulkopuolella.

2. Jakamalla linkki verkkosivustolle, joka on yhdistetty Actions-API:iin actions.json-tiedoston kautta verkkosivuston verkkotunnuksen juuressa.

   Esimerkiksi https://alice.com/actions.json yhdistää https://alice.com/donate, verkkosivuston URL-osoitteen, jossa käyttäjät voivat lahjoittaa Alicelle, API URL:iin https://actions.alice.com/donate, jossa Alicelle lahjoittamisen toiminnot sijaitsevat.

3. Upottamalla Action URL "välisivuston" URL-osoitteeseen, joka osaa jäsentää toimintoja.

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

Blinkkejä tukevien asiakkaiden tulisi pystyä ottamaan mikä tahansa yllä olevista muodoista ja renderöimään oikein käyttöliittymä toiminnon suorittamiseksi suoraan asiakkaassa.

Asiakkaille, jotka eivät tue blinkkejä, tulisi olla olemassa taustalla oleva verkkosivusto (jolloin selaimesta tulee universaali varajärjestelmä).

Jos käyttäjä napauttaa mitä tahansa kohtaa asiakkaassa, joka ei ole toimintopainike tai tekstinsyöttökenttä, hänet pitäisi ohjata taustalla olevalle sivustolle.

Blinkin testaus ja verifiointi

Vaikka Solana Actions ja blinkit ovat luvattomia protokollia/määrityksiä, asiakassovellukset ja lompakot ovat silti velvollisia viime kädessä helpottamaan käyttäjiä allekirjoittamaan transaktion.

Käytä Blinks Inspector -työkalua blinkkiesi ja toimintojesi tutkimiseen, virheenkorjaukseen ja testaamiseen suoraan selaimessasi. Voit tarkastella GET- ja POST-vastauksen sisältöä, vastausotsikkoja ja testata kaikkia syötteitä kuhunkin linkitettyyn toimintoon.

Jokaisella asiakassovelluksella tai lompakolla voi olla eri vaatimukset sille, mitkä Action-päätepisteet heidän asiakkaansa automaattisesti avaavat ja näyttävät käyttäjilleen suoraan sosiaalisen median alustoilla.

Esimerkiksi jotkut asiakkaat saattavat toimia "sallittujen listalla" -periaatteella, joka saattaa vaatia verifioinnin ennen kuin asiakas avaa toiminnon käyttäjille, kuten Dialectin Actions Registry (kuvattu alla).

Kaikki blinkit renderöidään ja mahdollistavat allekirjoittamisen Dialectin dial.to-blinkkien välisivustolla, ja niiden rekisteröintistatus näkyy blinkissä.

Dialectin Actions Registry

Solana-ekosysteemin julkisena hyödykkeenä Dialect ylläpitää julkista rekisteriä – yhdessä Solana Foundationin ja muiden yhteisön jäsenten avustuksella – blockchain-linkeistä, jotka on esivalidoitu tunnetuista lähteistä. Julkaisuhetkestä lähtien vain Dialect-rekisteriin rekisteröidyt toiminnot avataan Twitter-feedissä julkaisun yhteydessä.

Asiakassovellukset ja lompakot voivat vapaasti valita käyttää tätä julkista rekisteriä tai muuta ratkaisua käyttäjien turvallisuuden varmistamiseksi. Jos toimintoa ei ole verifioitu Dialect-rekisterin kautta, blockchain-linkkiin ei kosketa blink-asiakkaan toimesta, ja se renderöidään tavallisena URL-osoitteena.

Kehittäjät voivat hakea Dialectin verifiointia täällä: dial.to/register

Määritys

Solana Actions -määritys koostuu keskeisistä osioista, jotka ovat osa pyyntö/vastaus-vuorovaikutuskulkua:

• Solana Action URL-rakenne, joka tarjoaa Action URL:n
• OPTIONS-vastaus Action URL:lle CORS-vaatimusten täyttämiseksi
• GET-pyyntö Action URL:lle
• GET-vastaus palvelimelta
• POST-pyyntö Action URL:lle
• POST-vastaus palvelimelta

Jokaisen näistä pyynnöistä tekee Action-asiakas (esim. lompakkosovellus, selainlaajennus, dApp, verkkosivusto jne.) tiettyjen metatietojen keräämiseksi monipuolisia käyttöliittymiä varten ja käyttäjän syötteen välittämiseksi Actions API:lle.

Jokaisen vastauksen muodostaa sovellus (esim. verkkosivusto, palvelimen taustajärjestelmä jne.) ja palauttaa sen Action-asiakkaalle. Lopulta tämä tuottaa allekirjoitettavan tapahtuman tai viestin, jonka lompakko voi pyytää käyttäjää hyväksymään, allekirjoittamaan ja lähettämään lohkoketjuun.

Tässä readme-tiedostossa ilmoitetut tyypit ja rajapinnat ovat usein tyyppien yksinkertaistettu versio luettavuuden parantamiseksi.

Paremman tyyppiturvallisuuden ja kehittäjäkokemuksen vuoksi @solana/actions-spec-paketti sisältää monimutkaisempia tyyppimäärityksiä. Voit löytää niiden lähdekoodin täältä.

URL-skeema

Solana Action -URL kuvaa interaktiivista pyyntöä allekirjoitettavalle Solana- tapahtumalle tai -viestille käyttäen solana-action-protokollaa.

Pyyntö on interaktiivinen, koska asiakas käyttää URL:n parametreja tehdäkseen sarjan standardoituja HTTP-pyyntöjä ja muodostaakseen allekirjoitettavan tapahtuman tai viestin, jonka käyttäjä allekirjoittaa lompakollaan.

solana-action:<link>

• Polkunimenä vaaditaan yksi link-kenttä. Arvon on oltava ehdollisesti URL-koodattu absoluuttinen HTTPS-URL.

• Jos URL sisältää kyselyparametreja, sen on oltava URL-koodattu. Arvon URL-koodaus estää ristiriidat Actions-protokollan parametrien kanssa, joita voidaan lisätä protokollamäärityksen kautta.

• Jos URL ei sisällä kyselyparametreja, sitä ei tulisi URL-koodata. Tämä tuottaa lyhyemmän URL:n ja vähemmän tiheän QR-koodin.

Kummassakin tapauksessa asiakkaiden on URL-purettava arvo. Tällä ei ole vaikutusta, jos arvoa ei ole URL-koodattu. Jos purettu arvo ei ole absoluuttinen HTTPS-URL, lompakon on hylättävä se virheellisesti muodostettuna.

OPTIONS-vastaus

Jotta Cross-Origin Resource Sharing (CORS) voidaan sallia Actions- asiakkaissa (mukaan lukien blinks), kaikkien Action-päätepisteiden tulisi vastata HTTP-pyyntöihin OPTIONS-metodille kelvollisilla otsakkeilla, joiden avulla asiakkaat läpäisevät CORS- tarkistukset kaikissa myöhemmissä pyynnöissä samasta alkuperäverkkotunnuksesta.

Actions-asiakas voi tehdä ”preflight”- pyyntöjä Action-URL-päätepisteeseen tarkistaakseen, läpäiseekö myöhempi GET-pyyntö Action-URL:ään kaikki CORS-tarkistukset. Nämä CORS-preflight-tarkistukset tehdään OPTIONS-HTTP-metodilla, ja niiden tulisi vastata kaikilla vaadituilla HTTP- otsakkeilla, joiden avulla Action-asiakkaat (kuten blinks) voivat tehdä kaikki myöhemmät pyynnöt oikein alkuperäverkkotunnuksestaan.

Vähintään vaaditut HTTP-otsakkeet sisältävät:

• Access-Control-Allow-Origin, jonka arvo on *
  • tämä varmistaa, että kaikki Action-asiakkaat voivat läpäistä CORS-tarkistukset turvallisesti, jotta ne voivat tehdä kaikki vaaditut pyynnöt
• Access-Control-Allow-Methods, jonka arvo on GET,POST,PUT,OPTIONS
  • varmistaa, että kaikki vaaditut HTTP-pyyntömetodit ovat tuettuja Actions-toiminnoille
• Access-Control-Allow-Headers, jonka vähimmäisarvo on Content-Type, Authorization, Content-Encoding, Accept-Encoding

Yksinkertaisuuden vuoksi kehittäjien kannattaa harkita saman vastauksen ja otsakkeiden palauttamista OPTIONS-pyyntöihin kuin heidän GET-vastauksessaan.

GET-pyyntö

Action-asiakkaan (esim. lompakko, selainlaajennus jne.) tulisi tehdä HTTP GET JSON -pyyntö Actionin URL-päätepisteeseen.

• Pyynnön ei tulisi tunnistaa lompakkoa tai käyttäjää.
• Asiakkaan tulisi tehdä pyyntö Accept-Encoding-otsakkeella.
• Asiakkaan tulisi näyttää URL:n verkkotunnus pyynnön tekemisen aikana.

GET-vastaus

Actionin URL-päätepisteen (esim. sovellus tai palvelimen taustajärjestelmä) tulisi vastata HTTP OK JSON -vastauksella (jonka rungossa on kelvollinen hyötykuorma) tai asianmukaisella HTTP-virheellä.

• Asiakkaan on käsiteltävä HTTP:n asiakasvirheet, palvelinvirheet ja uudelleenohjausvastaukset.

• Päätepisteen tulisi vastata Content-Encoding-otsakkeella HTTP-pakkausta varten.

• Päätepisteen tulisi vastata Content-Type-otsakkeella, jonka arvo on application/json.

• Asiakkaan ei tulisi välimuistittaa vastausta muutoin kuin HTTP-välimuistituksen vastausotsakkeiden ohjeiden mukaisesti.

• Asiakkaan tulisi näyttää title ja renderöidä icon-kuva käyttäjälle.

Virhevastauksien (eli HTTP 4xx- ja 5xx-tilakoodien) tulisi palauttaa JSON- vastausrunko ActionError-määrityksen mukaisesti, jotta käyttäjille voidaan esittää hyödyllinen virheilmoitus. Katso Action-virheet.

GET-vastauksen runko

HTTP OK JSON -vastauksella annetun GET-vastauksen tulisi sisältää rungon hyötykuorma, joka noudattaa rajapintamääritystä:

export type ActionType = "action" | "completed";

export type ActionGetResponse = Action<"action">;

export interface Action<T extends ActionType> {
  /** type of Action to present to the user */
  type: T;
  /** image url that represents the source of the action request */
  icon: string;
  /** describes the source of the action request */
  title: string;
  /** brief summary of the action to be performed */
  description: string;
  /** button text rendered to the user */
  label: string;
  /** UI state for the button being rendered to the user */
  disabled?: boolean;
  links?: {
    /** list of related Actions a user could perform */
    actions: LinkedAction[];
  };
  /** non-fatal error message to be displayed to the user */
  error?: ActionError;
}

• type – Käyttäjälle annettavan toiminnon tyyppi. Oletusarvo on action. Alkuperäisellä ActionGetResponse-vastauksella on oltava tyyppi action.

  • action – Vakiotoiminto, jonka avulla käyttäjä voi olla vuorovaikutuksessa minkä tahansa LinkedActions-toiminnon kanssa
  • completed – Käytetään ilmoittamaan ”completed”-tila toimintojen ketjutuksessa.

• icon – Arvon on oltava kuvakkeen kuvan absoluuttinen HTTP- tai HTTPS-URL. Tiedoston on oltava SVG-, PNG- tai WebP-kuva, tai asiakkaan/lompakon on hylättävä se virheellisesti muodostettuna.

• title – Arvon on oltava UTF-8-merkkijono, joka edustaa toimintopyynnön lähdettä. Tämä voi olla esimerkiksi pyynnön tekevän brändin, kaupan, sovelluksen tai henkilön nimi.

• description – Arvon on oltava UTF-8-merkkijono, joka antaa tietoja toiminnosta. Kuvaus tulisi näyttää käyttäjälle.

• label – Arvon on oltava UTF-8-merkkijono, joka renderöidään painikkeeseen, jota käyttäjä napsauttaa. Kaikkien tunnisteiden tulisi olla enintään 5 sanan pituisia ilmauksia ja alkaa verbillä, jotta haluttu käyttäjän toiminto vahvistuu. Esimerkiksi ”Minttaa NFT”, ”Äänestä kyllä” tai ”Steikkaa 1 SOL”.

• disabled – Arvon on oltava totuusarvo, joka edustaa renderöidyn painikkeen poistettua käytöstä -tilaa (painike näyttää label-merkkijonon). Jos arvoa ei anneta, disabled-arvon tulisi oletusarvoisesti olla false (eli oletuksena käytössä). Jos esimerkiksi toimintopäätepiste koskee hallintoäänestystä, joka on päättynyt, aseta disabled=true, ja label voisi olla ”Äänestys suljettu”.

• error – Valinnainen virhemerkintä ei-kriittisille virheille. Jos se on olemassa, asiakkaan tulisi näyttää se käyttäjälle. Jos se on asetettu, sen ei tulisi estää asiakasta tulkitsemasta toimintoa tai näyttämästä sitä käyttäjälle (katso Action-virheet). Virhettä voidaan esimerkiksi käyttää yhdessä disabled-arvon kanssa syyn näyttämiseen, kuten liiketoimintarajoitteet, valtuutus, tila tai ulkoisen resurssin virhe.

• links.actions – Valinnainen taulukko päätepisteeseen liittyvistä toiminnoista. Käyttäjille tulisi näyttää käyttöliittymä kullekin luetellulle toiminnolle, ja heidän odotetaan suorittavan niistä vain yksi. Esimerkiksi hallintoäänestyksen toimintopäätepiste voi palauttaa käyttäjälle kolme vaihtoehtoa: ”Äänestä kyllä”, ”Äänestä ei” ja ”Pidättäydy äänestämästä”.

  • Jos links.actions-arvoa ei anneta, asiakkaan tulisi renderöidä yksi painike käyttäen juuritason label-merkkijonoa ja tehdä POST-pyyntö samaan toiminnon URL-päätepisteeseen kuin alkuperäinen GET-pyyntö.

  • Jos links.actions-arvoja annetaan, asiakkaan tulisi renderöidä vain painikkeet ja syötekentät links.actions-kentässä lueteltujen kohteiden perusteella. Asiakkaan ei tulisi renderöidä painiketta juuritason label-sisällölle.

export interface LinkedAction {
  /** Type of action to be performed by user */
  type: LinkedActionType;
  /** URL endpoint for an action */
  href: string;
  /** button text rendered to the user */
  label: string;
  /**
   * Parameters to accept user input within an action
   * @see {ActionParameter}
   * @see {ActionParameterSelectable}
   */
  parameters?: Array<TypedActionParameter>;
}

ActionParameter mahdollistaa sen ilmoittamisen, mitä syötettä Action API pyytää käyttäjältä:

/**
 * Parameter to accept user input within an action
 * note: for ease of reading, this is a simplified type of the actual
 */
export interface ActionParameter {
  /** input field type */
  type?: ActionParameterType;
  /** parameter name in url */
  name: string;
  /** placeholder text for the user input field */
  label?: string;
  /** declare if this field is required (defaults to `false`) */
  required?: boolean;
  /** regular expression pattern to validate user input client side */
  pattern?: string;
  /** human-readable description of the `type` and/or `pattern`, represents a caption and error, if value doesn't match */
  patternDescription?: string;
  /** the minimum value allowed based on the `type` */
  min?: string | number;
  /** the maximum value allowed based on the `type` */
  max?: string | number;
}

pattern-arvon tulisi olla kelvollista säännöllistä lauseketta vastaava merkkijono. Blink-asiakkaiden tulisi käyttää tätä säännöllisen lausekkeen mallia käyttäjän syötteen validointiin ennen POST-pyynnön tekemistä. Jos pattern ei ole kelvollinen säännöllinen lauseke, asiakkaiden tulisi ohittaa se.

patternDescription on ihmisen luettava kuvaus käyttäjältä odotetusta syötteestä. Jos pattern annetaan, myös patternDescription on annettava.

min- ja max-arvot mahdollistavat syötteelle käyttäjältä pyydetyn syötteen ala- ja/tai ylärajat (eli minimi-/maksimiluku ja/tai minimi-/maksimimerkkimäärä), ja niitä tulisi käyttää asiakaspuolen validointiin. Syötteen type-arvoille date tai datetime-local näiden arvojen tulisi olla päivämäärämerkkijonoja. Muille merkkijonopohjaisille syötteen type-arvoille arvojen tulisi olla numeroita, jotka kuvaavat niiden minimi-/maksimimerkkimäärää.

Jos käyttäjän syötearvoa ei pidetä kelvollisena pattern-arvon perusteella, käyttäjän pitäisi saada asiakaspuolen virheilmoitus, joka ilmaisee, että syötekenttä ei ole kelvollinen, ja patternDescription-merkkijono tulisi näyttää.

type-kentän avulla Action API voi ilmoittaa tarkempia käyttäjän syötekenttiä, tarjota parempaa asiakaspuolen validointia ja parantaa käyttäjäkokemusta. Monissa tapauksissa tämä tyyppi muistuttaa standardia HTML-syöte-elementtiä.

ActionParameterType voidaan yksinkertaistaa seuraavaksi tyypiksi:

/**
 * Input field type to present to the user
 * @default `text`
 */
export type ActionParameterType =
  | "text"
  | "email"
  | "url"
  | "number"
  | "date"
  | "datetime-local"
  | "checkbox"
  | "radio"
  | "textarea"
  | "select";

Jokaisen type-arvon tulisi normaalisti johtaa käyttäjän syötekenttään, joka muistuttaa vastaavan type-arvon standardia HTML input -elementtiä (eli <input type="email" />), jotta voidaan tarjota parempaa asiakaspuolen validointia ja käyttäjäkokemusta:

• text – vastaa HTML:n “text”-syöte- elementtiä
• email – vastaa HTML:n “email”-syöte- elementtiä
• url – vastaa HTML:n “url”-syöte- elementtiä
• number – vastaa HTML:n “number”-syöte- elementtiä
• date – vastaa HTML:n “date”-syöte- elementtiä
• datetime-local – vastaa HTML:n “datetime-local”-syöte- elementtiä
• checkbox – vastaa standardien HTML “checkbox”-syöte- elementtien ryhmää. Action API:n tulisi palauttaa options alla kuvatulla tavalla. Käyttäjän tulisi voida valita useita annetuista valintaruutuvaihtoehdoista.
• radio – vastaa standardien HTML “radio”-syöte- elementtien ryhmää. Action API:n tulisi palauttaa options alla kuvatulla tavalla. Käyttäjän tulisi voida valita vain yksi annetuista radiopainikevaihtoehdoista.
• Muita HTML-syöttötyyppejä vastaavia elementtejä, joita ei ole mainittu edellä (hidden, button, submit, file jne.), ei tällä hetkellä tueta.

Yllä mainittujen HTML-syöttötyyppejä muistuttavien elementtien lisäksi seuraavat käyttäjän syöteelementit ovat myös tuettuja:

• textarea – vastaa HTML:n textarea-elementtiä. Mahdollistaa käyttäjän monirivisyötteen.
• select – vastaa HTML:n select-elementtiä, joka tarjoaa käyttäjälle "pudotusvalikko"-tyylisen kentän. Action API:n tulisi palauttaa options alla kuvatulla tavalla.

Kun type-arvoksi on asetettu select, checkbox tai radio, Action API:n tulee sisällyttää options-taulukko, jonka jokainen alkio sisältää vähintään label- ja value-arvot. Jokaisella vaihtoehdolla voi myös olla selected-arvo, joka kertoo blink-asiakkaalle, mikä vaihtoehdoista tulisi olla oletuksena valittuna käyttäjälle (katso checkbox ja radio erojen osalta).

Tämä ActionParameterSelectable voidaan yksinkertaistaa seuraavaan tyyppimäärittelyyn:

/**
 * note: for ease of reading, this is a simplified type of the actual
 */
interface ActionParameterSelectable extends ActionParameter {
  options: Array<{
    /** displayed UI label of this selectable option */
    label: string;
    /** value of this selectable option */
    value: string;
    /** whether or not this option should be selected by default */
    selected?: boolean;
  }>;
}

Jos type-arvoa ei ole asetettu tai se on tuntematon/ei-tuettu, blink-asiakkaiden tulee oletuksena käyttää text-tyyppiä ja renderöidä yksinkertainen tekstikenttä.

Action API on edelleen vastuussa kaikkien käyttäjän syöttöparametreista peräisin olevien tietojen validoinnista ja sanitoinnista sekä tarvittavien "pakollisten" syöttökenttien pakottamisesta.

Muilla kuin HTML/web-pohjaisilla alustoilla (kuten natiiville mobiilille) tulisi käyttää vastaavaa natiiveja käyttäjän syötekomponenttia, jotta saavutetaan vastaava käyttökokemus ja asiakaspuolen validointi kuin yllä kuvatuilla HTML/web-syötetyypeillä.

Esimerkki GET-vastauksesta

Seuraava esimerkkivastaus tarjoaa yksittäisen "juuri"-toiminnon, jonka odotetaan esitettävän käyttäjälle yksittäisenä painikkeena, jonka otsikko on "Claim Access Token":

{
  "title": "HackerHouse Events",
  "icon": "<url-to-image>",
  "description": "Claim your Hackerhouse access token.",
  "label": "Claim Access Token" // button text
}

Seuraava esimerkkivastaus tarjoaa 3 toisiinsa liittyvää toimintolinkkiä, joiden avulla käyttäjä voi äänestää DAO-ehdotusta klikkaamalla yhtä kolmesta painikkeesta:

{
  "title": "Realms DAO Platform",
  "icon": "<url-to-image>",
  "description": "Vote on DAO governance proposals #1234.",
  "label": "Vote",
  "links": {
    "actions": [
      {
        "label": "Vote Yes", // button text
        "href": "/api/proposal/1234/vote?choice=yes"
      },
      {
        "label": "Vote No", // button text
        "href": "/api/proposal/1234/vote?choice=no"
      },
      {
        "label": "Abstain from Vote", // button text
        "href": "/api/proposal/1234/vote?choice=abstain"
      }
    ]
  }
}

Esimerkki GET-vastauksesta parametreilla

Seuraavat esimerkkivastaukset havainnollistavat, kuinka tekstisyötettä voidaan hyväksyä käyttäjältä (parameters-kentän kautta) ja sisällyttää se lopulliseen POST-pyyntöön päätepisteeseeen (LinkedAction-kohteen href-kentän kautta):

Seuraava esimerkkivastaus tarjoaa käyttäjälle 3 linkitettyä toimintoa SOL:n panostamiseen: painike "Stake 1 SOL", toinen painike "Stake 5 SOL" ja tekstisyöttökenttä, johon käyttäjä voi syöttää haluamansa "amount"-arvon, joka lähetetään Action API:lle:

{
  "title": "Stake-o-matic",
  "icon": "<url-to-image>",
  "description": "Stake SOL to help secure the Solana network.",
  "label": "Stake SOL", // not displayed since `links.actions` are provided
  "links": {
    "actions": [
      {
        "label": "Stake 1 SOL", // button text
        "href": "/api/stake?amount=1"
        // no `parameters` therefore not a text input field
      },
      {
        "label": "Stake 5 SOL", // button text
        "href": "/api/stake?amount=5"
        // no `parameters` therefore not a text input field
      },
      {
        "label": "Stake", // button text
        "href": "/api/stake?amount={amount}",
        "parameters": [
          {
            "name": "amount", // field name
            "label": "SOL amount" // text input placeholder
          }
        ]
      }
    ]
  }
}

Seuraava esimerkkivastaus tarjoaa yhden syöttökentän, johon käyttäjä voi syöttää amount-arvon, joka lähetetään POST-pyynnön mukana (joko kyselyparametrina tai alipolussa):

{
  "icon": "<url-to-image>",
  "label": "Donate SOL",
  "title": "Donate to GoodCause Charity",
  "description": "Help support this charity by donating SOL.",
  "links": {
    "actions": [
      {
        "label": "Donate", // button text
        "href": "/api/donate/{amount}", // or /api/donate?amount={amount}
        "parameters": [
          // {amount} input field
          {
            "name": "amount", // input field name
            "label": "SOL amount" // text input placeholder
          }
        ]
      }
    ]
  }
}

POST-pyyntö

Asiakkaan on tehtävä HTTP POST JSON -pyyntö toiminnon URL-osoitteeseen seuraavalla pyyntörungolla:

{
  "account": "<account>"
}

• account – Arvon on oltava base58-koodattu julkinen avain tililtä, joka voi allekirjoittaa tapahtuman.

Asiakkaan tulisi tehdä pyyntö Accept-Encoding-otsikon kera, ja sovellus voi vastata Content-Encoding-otsikolla HTTP-pakkausta varten.

Asiakkaan tulisi näyttää toiminnon URL-osoitteen verkkotunnus pyynnön aikana. Jos GET-pyyntö on tehty, asiakkaan tulisi myös näyttää title ja renderöidä icon-kuva kyseisestä GET-vastauksesta.

POST-vastaus

Toiminnon POST-päätepiste tulisi vastata HTTP OK JSON -vastauksella (jossa on kelvollinen hyötykuorma rungossa) tai asianmukaisella HTTP-virheellä.

• Asiakkaan on käsiteltävä HTTP asiakasvirheet, palvelinvirheet ja uudelleenohjausvastaukset.
• Päätepisteen tulisi vastata Content-Type-otsikolla arvolla application/json.

Virhevastausten (eli HTTP 4xx- ja 5xx-tilakoodeilla) tulisi palauttaa JSON-vastausrunko ActionError-rakenteen mukaisesti, jotta käyttäjälle voidaan esittää hyödyllinen virheilmoitus. Katso Toimintovirheet.

POST-vastauksen runko

HTTP OK JSON -vastauksella varustetun POST-vastauksen tulisi sisältää runko seuraavalla hyötykuormalla:

/**
 * Response body payload returned from the Action POST Request
 */
export interface ActionPostResponse<T extends ActionType = ActionType> {
  /** base64 encoded serialized transaction */
  transaction: string;
  /** describes the nature of the transaction */
  message?: string;
  links?: {
    /**
     * The next action in a successive chain of actions to be obtained after
     * the previous was successful.
     */
    next: NextActionLink;
  };
}

• transaction – Arvon on oltava base64-koodattu serialisoitu tapahtuma. Asiakkaan on base64-dekoodattava tapahtuma ja deserialisoitava se.

• message – Arvon on oltava UTF-8-merkkijono, joka kuvaa vastauksessa mukana olevan tapahtuman luonnetta. Asiakkaan tulisi näyttää tämä arvo käyttäjälle. Tämä voi olla esimerkiksi ostettavan tuotteen nimi, ostokseen sovellettava alennus tai kiitosviesti.

• links.next – Valinnainen arvo, jota käytetään useiden toimintojen "ketjuttamiseen" peräkkäin. Sen jälkeen kun mukana oleva transaction on vahvistettu ketjussa, asiakas voi hakea ja renderöidä seuraavan toiminnon. Katso lisätietoja kohdasta Toimintojen ketjutus.

• Asiakkaan ja sovelluksen tulee sallia lisäkentät pyyntörungossa ja vastausrungossa, sillä niitä voidaan lisätä tulevissa määrittelypäivityksissä.

Sovellus voi vastata osittain tai kokonaan allekirjoitetulla tapahtumalla. Asiakkaan ja lompakon on validoitava tapahtuma epäluotettavana.

POST-vastaus – Tapahtuma

Jos tapahtuman signatures ovat tyhjiä tai tapahtumaa ei ole osittain allekirjoitettu:

• Asiakkaan on jätettävä huomiotta tapahtuman feePayer ja asetettava feePayer pyynnön account-arvoksi.
• Asiakkaan on jätettävä huomiotta tapahtuman recentBlockhash ja asetettava recentBlockhash uusimmaksi lohkotiivisteeksi.
• Asiakkaan on serialisoitava ja deserialisoitava tapahtuma ennen sen allekirjoittamista. Tämä varmistaa tilitunnisteiden johdonmukaisen järjestyksen tämän ongelman kiertämiseksi.

Jos tapahtuma on osittain allekirjoitettu:

• Asiakkaan EI SAA muuttaa feePayer- tai recentBlockhash-arvoja, sillä se mitätöisi olemassa olevat allekirjoitukset.
• Asiakkaan on tarkistettava olemassa olevat allekirjoitukset, ja jos jokin niistä on virheellinen, asiakkaan on hylättävä tapahtuma väärennettyä sisältävänä.

Asiakkaan on allekirjoitettava tapahtuma ainoastaan pyynnön account-arvolla ja tehtävä niin vain, jos pyynnön account-arvon allekirjoitusta odotetaan.

Jos jokin muu allekirjoitus kuin pyynnön account-arvon allekirjoitus on odotettu, asiakkaan on hylättävä tapahtuma haitallisena.

Toimintovirheet

Toiminto-API:iden tulisi palauttaa virheet käyttämällä ActionError-rakennetta, jotta käyttäjälle voidaan esittää hyödyllisiä virheilmoituksia. Kontekstista riippuen tämä virhe voi olla kohtalokas tai ei-kohtalokas.

export interface ActionError {
  /** simple error message to be displayed to the user */
  message: string;
}

Kun Toiminto-API vastaa HTTP-virhestatuskoodilla (eli 4xx tai 5xx), vastausrungon tulisi olla ActionError-rakenteen mukainen JSON-hyötykuorma. Virhe katsotaan kohtalokkaaksi ja mukana oleva message tulisi esittää käyttäjälle.

Sellaisten API-vastausten osalta, jotka tukevat valinnaista error-attribuuttia (kuten ActionGetResponse), virhe katsotaan ei-kohtalokkaaksi ja mukana oleva message tulisi esittää käyttäjälle.

Toimintojen ketjutus

Solana-toimintoja voidaan "ketjuttaa" peräkkäiseen sarjaan. Kun toiminnon tapahtuma on vahvistettu ketjussa, seuraava toiminto voidaan hakea ja esittää käyttäjälle.

Toimintojen ketjutuksen avulla kehittäjät voivat rakentaa monimutkaisempia ja dynaamisia kokemuksia blinkeissä, mukaan lukien:

• useiden tapahtumien (ja viime kädessä allekirjoitusviestin) tarjoaminen käyttäjälle
• toiminnan metatietojen mukauttaminen käyttäjän lompakkoosoitteen perusteella
• blink-metatietojen päivittäminen onnistuneen tapahtuman jälkeen
• API-takaisinkutsun vastaanottaminen tapahtuman allekirjoituksella lisävalidointia ja logiikkaa varten Toiminto-API-palvelimella
• mukautetut "onnistumis"-viestit päivittämällä näytettävät metatiedot (esim. uusi kuva ja kuvaus)

Ketjuttaaksesi useita toimintoja yhteen, sisällytä mihin tahansa ActionPostResponse-vastaukseen links.next-arvo, joka on jokin seuraavista:

• PostNextActionLink – POST-pyyntölinkki, jonka takaisinkutsu-URL on samasta alkuperästä ja joka vastaanottaa signature- ja käyttäjän account-arvot rungossa. Tämän takaisinkutsu-URL:n tulisi vastata NextAction-rakenteella.
• InlineNextActionLink – Seuraavan toiminnon upotettuja metatietoja, jotka esitetään käyttäjälle heti tapahtuman vahvistuttua. Takaisinkutsua ei tehdä.

export type NextActionLink = PostNextActionLink | InlineNextActionLink;

/** @see {NextActionPostRequest} */
export interface PostNextActionLink {
  /** Indicates the type of the link. */
  type: "post";
  /** Relative or same origin URL to which the POST request should be made. */
  href: string;
}

/**
 * Represents an inline next action embedded within the current context.
 */
export interface InlineNextActionLink {
  /** Indicates the type of the link. */
  type: "inline";
  /** The next action to be performed */
  action: NextAction;
}

NextAction

Sen jälkeen kun käyttäjä on allekirjoittanut ActionPostResponse-vastauksessa mukana olevan transaction-arvon ja se on vahvistettu ketjussa, blink-asiakkaan tulisi joko:

• suorittaa takaisinkutsupyyntö NextAction-arvon hakemiseksi ja näyttämiseksi, tai
• jos NextAction on jo annettu links.next-kentän kautta, blink-asiakkaan tulisi päivittää näytettävät metatiedot eikä tehdä takaisinkutsupyyntöä

Jos takaisinkutsu-URL ei ole samasta alkuperästä kuin alkuperäinen POST-pyyntö, takaisinkutsupyyntöä ei tule tehdä. Blink-asiakkaiden tulisi näyttää virheilmoitus käyttäjälle.

/** The next action to be performed */
export type NextAction = Action<"action"> | CompletedAction;

/** The completed action, used to declare the "completed" state within action chaining. */
export type CompletedAction = Omit<Action<"completed">, "links">;

Tyypistä (type) riippuen seuraava toiminto tulisi esittää käyttäjälle blink-asiakkaiden kautta yhdellä seuraavista tavoista:

• action – (oletus) Vakiotoiminto, joka antaa käyttäjälle mahdollisuuden nähdä mukana olevat toiminnan metatiedot, käyttää tarjottuja LinkedAction-linkkejä ja jatkaa seuraavien toimintojen ketjuttamista.

• completed – Toimintoketjun pääteterminalitila, joka voi päivittää blink-käyttöliittymän mukana olevilla toiminnan metatiedoilla, mutta ei salli käyttäjän suorittaa lisätoimintoja.

Jos links.next-arvoa ei ole annettu, blink-asiakkaiden tulisi olettaa, että nykyinen toiminto on ketjun viimeinen toiminto, ja näyttää "valmis"-käyttöliittymätila tapahtuman vahvistuttua.

actions.json

actions.json-tiedoston tarkoituksena on mahdollistaa sovelluksen ohjata asiakkaita sen suhteen, mitkä verkkosivuston URL-osoitteet tukevat Solana-toimintoja, ja tarjota kartoitus, jota voidaan käyttää GET-pyyntöjen tekemiseen Toiminto-API-palvelimelle.

actions.json-tiedosto tulisi tallentaa ja sen tulisi olla yleisesti saatavilla verkkotunnuksen juuressa.

Jos esimerkiksi verkkosovelluksesi on otettu käyttöön osoitteessa my-site.com, niin actions.json-tiedoston tulisi olla saatavilla osoitteessa https://my-site.com/actions.json. Tämän tiedoston tulisi myös olla ristikkäisalkuperäisesti saatavilla minkä tahansa selaimen kautta asettamalla Access-Control-Allow-Origin-otsikon arvoksi *.

Säännöt

rules-kenttä mahdollistaa sovelluksen kartoittaa verkkosivuston suhteelliset reittimääritykset toisiin polkuihin.

Tyyppi: ActionRuleObject-alkioiden Array.

interface ActionRuleObject {
  /** relative (preferred) or absolute path to perform the rule mapping from */
  pathPattern: string;
  /** relative (preferred) or absolute path that supports Action requests */
  apiPath: string;
}

• pathPattern - Kuvio, joka vastaa jokaista saapuvaa polkunimeä.

• apiPath - Kohdesijainti, joka on määritelty absoluuttisena polkunimenä tai ulkoisena URL-osoitteena.

Säännöt - pathPattern

Kuvio, joka vastaa jokaista saapuvaa polkunimeä. Se voi olla absoluuttinen tai suhteellinen polku ja tukee seuraavia muotoja:

• Tarkka vastaavuus: Vastaa täsmälleen URL-polkua.

  • Esimerkki: /exact-path
  • Esimerkki: https://website.com/exact-path

• Jokerimerkkivastaavuus: Käyttää jokerimerkkejä vastaamaan mitä tahansa merkkijonoa URL-polussa. Tämä voi vastata yksittäisiä (käyttäen *) tai useita segmenttejä (käyttäen **). (katso Polun vastaavuus alla).

  • Esimerkki: /trade/* vastaa polkuja /trade/123 ja /trade/abc, poimien vain ensimmäisen segmentin /trade/-osan jälkeen.
  • Esimerkki: /category/*/item/** vastaa polkuja /category/123/item/456 ja /category/abc/item/def.
  • Esimerkki: /api/actions/trade/*/confirm vastaa polkua /api/actions/trade/123/confirm.

Säännöt - apiPath

Toimintopyynnön kohdereitti. Se voidaan määritellä absoluuttisena polkunimenä tai ulkoisena URL-osoitteena.

• Esimerkki: /api/exact-path
• Esimerkki: https://api.example.com/v1/donate/*
• Esimerkki: /api/category/*/item/*
• Esimerkki: /api/swap/**

Säännöt - Kyselyparametrit

Alkuperäisen URL-osoitteen kyselyparametrit säilytetään aina ja liitetään yhdistettyyn URL-osoitteeseen.

Säännöt - Polun vastaavuus

Seuraava taulukko kuvaa polunvastaavuuskuvioiden syntaksin:

Sääntöesimerkkejä

Seuraava esimerkki havainnollistaa tarkkaa vastaavuussääntöä, joka yhdistää /buy-pyynnöt sivustosi juuresta täsmälliseen polkuun /api/buy sivustosi juuren suhteen:

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

Seuraava esimerkki käyttää jokerimerkkipolun vastaavuutta yhdistämään pyynnöt mihin tahansa polkuun (lukuun ottamatta alihakemistoja) /actions/-polun alla sivustosi juuresta vastaavaan polkuun /api/actions/-polun alla sivustosi juuren suhteen:

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

Seuraava esimerkki käyttää jokerimerkkipolun vastaavuutta yhdistämään pyynnöt mihin tahansa polkuun (lukuun ottamatta alihakemistoja) /donate/-polun alla sivustosi juuresta absoluuttiseen polkuun https://api.dialect.com/api/v1/donate/ ulkoisella sivustolla:

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

Seuraava esimerkki käyttää jokerimerkkipolun vastaavuutta idempotenttisäännölle, joka yhdistää pyynnöt mihin tahansa polkuun (mukaan lukien alihakemistot) /api/actions/-polun alla sivustosi juuresta itseensä:

Idempotenttisäännöt mahdollistavat blink-asiakkaiden helpomman määrityksen, tukeeko tietty polku Action API -pyyntöjä ilman, että se täytyy prefiksoida solana-action:-URI:lla tai suorittaa lisävastaustestejä.

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

Toimintoidentiteetti

Toimintopisteet voivat sisällyttää Toimintoidentiteetin transaktioihin, jotka palautetaan niiden POST-vastauksessa käyttäjän allekirjoitettavaksi. Tämä mahdollistaa indeksoijien ja analytiikka-alustojen helposti ja todennettavasti liittää onchain-toiminnan tiettyyn toimintotarjoajaan (ts. palveluun) todennettavalla tavalla.

Toimintoidentiteetti on keypair, jota käytetään allekirjoittamaan erityisesti muotoiltu viesti, joka sisällytetään transaktioon Memo-ohjeen avulla. Tämä Tunnistusviesti voidaan todennettavasti liittää tiettyyn toimintoidentiteettiin, ja siten liittää transaktiot tiettyyn toimintotarjoajaan.

keypair ei ole pakollinen allekirjoittamaan itse transaktiota. Tämä mahdollistaa lompakoiden ja sovellusten parantaa transaktion toimitettavuutta, kun käyttäjälle palautetussa transaktiossa ei ole muita allekirjoituksia (katso POST-vastauksen transaktio).

Jos toimintotarjoajan käyttötapaus vaatii, että heidän taustapalvelunsa allekirjoittavat transaktion ennen käyttäjää, heidän tulisi käyttää tätä keypair-avainta toimintoidentiteettinään. Tämä mahdollistaa yhden tilin vähemmän sisällytettäväksi transaktioon, pienentäen kokonaistransaktion kokoa 32 tavulla.

Toimintoidentiteettiviesti

Toimintoidentiteettiviesti on kaksoispisteellä eroteltu UTF-8-merkkijono, joka sisällytetään transaktioon yhdellä SPL Memo -ohjeella.

protocol:identity:reference:signature

• protocol - Käytettävän protokollan arvo (asetettu arvoon solana-action per URL-rakenne yllä)
• identity - Arvon on oltava toimintoidentiteetin keypair-avaimen julkisen avaimen osoite base58-koodattuna
• reference - Arvon on oltava base58-koodattu 32-tavuinen taulukko. Se voi tai ei voi olla julkisia avaimia, käyrällä tai sen ulkopuolella, ja se voi tai ei voi vastata Solanan tilejä.
• signature - base58-koodattu allekirjoitus, joka on luotu toimintoidentiteetin keypair-avaimella allekirjoittaen vain reference-arvo.

reference-arvoa tulee käyttää vain kerran ja yhdessä transaktiossa. Transaktioiden yhdistämiseksi toimintotarjoajaan, vain reference-arvon ensimmäistä käyttöä pidetään pätevänä.

Transaktioilla voi olla useita Memo-ohjeita. Suoritettaessa getSignaturesForAddress-kutsua, tuloksen memo-kenttä palauttaa jokaisen memo-ohjeen viestin yksittäisenä merkkijonona, jossa jokainen on erotettu puolipisteellä.

Tunnistusviestin Memo-ohjeeseen ei tule sisällyttää muita tietoja.

identity ja reference tulee sisällyttää vain luku-, ei-allekirjoittaja- avaimina transaktiossa ohjeessa, joka EI ole tunnistusviestin Memo-ohje.

Tunnistusviestin Memo-ohjeelle on annettava nolla tiliä. Jos tilejä annetaan, Memo-ohjelma vaatii näiden tilien olevan kelvollisia allekirjoittajia. Toimintojen tunnistamisen kannalta tämä rajoittaa joustavuutta ja voi heikentää käyttökokemusta. Siksi sitä pidetään hyvän käytännön vastaisena ja se on vältettävä.

Toimintoidentiteetin varmennus

Mikä tahansa transaktio, joka sisältää identity-tilin, voidaan todennettavasti yhdistää toimintotarjoajaan monivaiheisessa prosessissa:

1. Hae kaikki tietyn identity-tilin transaktiot.
2. Jäsennä ja varista jokaisen transaktion memo-merkkijono varmistaen, että signature on pätevä tallennetulle reference-arvolle.
3. Varmista, että kyseinen transaktio on reference-arvon ensimmäinen onchain-esiintymä:
   • Jos tämä transaktio on ensimmäinen esiintymä, transaktio katsotaan varmennetuksi ja se voidaan turvallisesti liittää toimintotarjoajaan.
   • Jos tämä transaktio EI ole ensimmäinen esiintymä, se katsotaan pätemättömäksi eikä sitä siten liitetä toimintotarjoajaan.

Koska Solana-validator indeksoi transaktiot tiliavainten perusteella, getSignaturesForAddress-RPC-metodia voidaan käyttää löytämään kaikki transaktiot, jotka sisältävät identity-tilin.

Tämän RPC-metodin vastaus sisältää kaikki Memo-tiedot memo-kentässä. Jos transaktiossa käytettiin useita Memo-ohjeita, jokainen memo-viesti sisällytetään tähän memo-kenttään ja varmentajan on jäsennettävä se vastaavasti Identiteettivarmennosviestin saamiseksi.

Nämä transaktiot tulisi aluksi katsoa VARMENTAMATTOMIKSI. Tämä johtuu siitä, että identity ei ole velvollinen allekirjoittamaan transaktiota, mikä mahdollistaa minkä tahansa transaktion sisällyttää tämän tilin ei-allekirjoittajana. Tämä voi potentiaalisesti keinotekoisesti kasvattaa liittämislaskureita ja käyttömääriä.

Identiteettivarmennosviesti tulisi tarkistaa varmistaakseen, että signature on luotu identity-tilin allekirjoittaessa reference-arvo. Jos tämä allekirjoituksen varmennus epäonnistuu, transaktio on pätemätön eikä sitä tulisi liittää toimintotarjoajaan.

Jos allekirjoituksen varmennus onnistuu, varmentajan tulisi varmistaa, että tämä transaktio on reference-arvon ensimmäinen onchain-esiintymä. Jos se ei ole, transaktio katsotaan pätemättömäksi.