x402-integraatio Koran kanssa

Kora voi tarjota Solana-allekirjoitus-, transaktio-käytäntö- ja maksujen sponsorointikerroksen x402 V2 -fasilitaattorin taustalle. Fasilitaattori toteuttaa x402 HTTP -rajapinnan; Kora validoi, allekirjoittaa ja lähettää hyväksymänsä maksutransaktiot.

Tämä opas käynnistää Koran viiteimplementaatiofasilitaattorin Solana Devnetissä. Kyseessä on kehitysympäristö integraation testaamiseen, ei tuotantokäyttöönotto.

Arkkitehtuuri

x402 with Kora

Neljä sovellusroolia pysyvät erillään:

Asiakas valitsee maksuvaateen ja allekirjoittaa maksuvaltuutuksen.
Resurssipalvelin hinnoittelee reitin ja täyttää sen vasta onnistuneen vahvistuksen ja selvityksen jälkeen.
Fasilitaattori julkaisee x402:n /supported-, /verify- ja /settle-päätepisteet.
Kora allekirjoittaa vain käytäntönsä sallimat transaktiot ja voi sponsoroida niiden Solana-verkkomaksut.

Kora ei korvaa x402-protokollaa. Se on tämän fasilitaattoritoteutuksen käyttämä allekirjoitus- ja käytäntöraja.

Käynnistä viiteimplementaatiofasilitaattori

Tarvitset Gitin ja Dockerin Composen kanssa. Kloonaa uusin vakaa Kora-julkaisu ja siirry x402-demohakemistoon:

git clone --branch v2.0.5 --depth 1 https://github.com/solana-foundation/kora.git
cd kora/examples/x402/demo
cp .env.example .env

Aseta KORA_PRIVATE_KEY .env-tiedostossa kertakäyttöiseen Devnet-keypair-arvoon. Demon allekirjoittajakonfiguraatio hyväksyy base58-salaisuuden, tavu-taulukkomuotoisen keypair-arvon tai polun JSON-keypair-tiedostoon. Rahoita julkinen osoite Devnet SOL:lla, jotta se voi sponsoroida transaktiomaksuja.

Käytä kertakäyttöistä Devnet-allekirjoittajaa

Docker-demo lataa Kora-allekirjoittajan ympäristömuuttujasta. Älä laita tuotannon allekirjoitusavainta tähän demoon äläkä tallenna .env-tiedostoa versionhallintaan.

Käynnistä Kora ja fasilitaattori:

docker compose up --build

Ensimmäinen koontivaihe voi kestää useita minuutteja. Kun molemmat terveystarkistukset läpäistään, tarkista fasilitaattorin mainostamat ominaisuudet toisesta terminaalista:

curl http://127.0.0.1:3000/supported

Vastauksen pitäisi mainostaa x402 versiota 2, exact-skeemaa sekä Devnet CAIP-2 -verkkotunnistetta:

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "extra": {
        "feePayer": "<KORA_SIGNER_ADDRESS>"
      }
    }
  ]
}

Kora kuuntelee oletuksena osoitteessa 127.0.0.1:8080 ja fasilitaattori osoitteessa 127.0.0.1:3000. Pysäytä demo painamalla Ctrl+C.

Yhdistä resurssipalvelin

Määritä x402-resurssipalvelin käyttämään paikallista fasilitaattoria ja Kora-allekirjoittajan julkista osoitetta vastaanottajana:

FACILITATOR_URL=http://127.0.0.1:3000
SOLANA_PAY_TO=<KORA_SIGNER_ADDRESS>

Seuraa sitten x402 Solanassa -ohjetta lisätäksesi x402 V2 -väliohjelmiston Express-reittiin. Maksamaton pyyntö saa vastauksen PAYMENT-REQUIRED, uudelleenyritys sisältää PAYMENT-SIGNATURE-otsikon ja onnistunut vastaus sisältää PAYMENT-RESPONSE-otsikon.

Älä kopioi esimerkkejä, jotka käyttävät X-PAYMENT-, X-PAYMENT-RESPONSE- tai solana-devnet-verkkonimiä. Nämä kentät kuuluvat x402 V1:een.

Kora-repositorio sisältää myös suojatun rajapinnan ja maksutietoisen asiakkaan samassa examples/x402/demo-hakemistossa. Käytä näitä sovelluksia, kun haluat testata täydellisen paikallisen työnkulun.

Kora-käytännön määritys

Viiteimplementaation kora/kora.toml on tarkoituksellisesti rajattu. Sen validointikäytäntö hallitsee:

mitkä Solana-ohjelmat allekirjoittaja sallii;
mitkä SPL-tokenimintit ovat käytettävissä;
sponsoroitujen lamport-yksiköiden ja allekirjoitusten enimmäismäärää;
mitkä maksajan toiminnot on kielletty; ja
mitkä Token-2022-laajennukset hylätään.

Demo ottaa käyttöön vain ne Kora RPC -menetelmät, joita sen fasilitaattori tarvitsee: signTransaction, signAndSendTransaction, getBlockhash, getPayerSigner, getConfig ja getVersion.

Pidä käytäntöä maksajan avaimen turvallisuusrajana. Tuotantopalvelua varten:

Salli vain ne ohjelmat, tokenimintat ja transaktiomuodot, joita x402-skeemasi tuottaa.
Estä siirrot, valtuusmuutokset, tilin sulkeminen ja muut ohjeet, jotka voivat siirtää arvoa Kora-allekirjoittajalta.
Aseta transaktio- ja käyttörajoitukset, jotka rajaavat menetykset vaarantuneesta fasilitaattoripalvelutunnuksesta.
Käytä hallittua allekirjoittajataustajärjestelmää ympäristömuuttujassa säilytettävän yksityisen avaimen sijaan.

Suojaa fasilitaattorin ja Koran välinen yhteys

Demo ottaa käyttöön Kora API-avainautentikoinnin. Fasilitaattori lähettää KORA_API_KEY-muuttujan arvon, jonka on vastattava kora.toml-tiedoston [kora.auth].api_key-arvoa.

Tuotantokäyttöä varten tee lisäksi seuraavat toimet:

pidä Kora yksityisessä verkossa ja päätä TLS luotetussa rajassa;
tallenna API-tunnukset salaisuudenhallintajärjestelmään ja kierrätä ne säännöllisesti;
harkitse Koran HMAC-pyyntöautentikointia muokkaus- ja uudelleenlähetyssuojaukseen;
erota maksajan ja maksun vastaanottajan avaimet toisistaan, jos kirjanpitomallisi niin vaatii; ja
aseta hälytykset käytäntöhylkäyksistä, selvitysvirheistä, maksukulutuksesta ja allekirjoittajan saldosta.

Vahvista maksujen selvitys

Kora validoi Solana-transaktion, mutta fasilitaattori ja resurssipalvelin vastaavat edelleen x402-protokollan oikeellisuudesta. Ennen resurssin toimittamista varmista:

valittu x402-versio, skeema, verkko, omaisuuserä, summa ja vastaanottaja;
valtuutuksen elinaika ja tarkka Solana-ohjeen rakenne;
atominen uudelleenlähetyssuojaus ja idempotentti selvitys;
vahvistus tuotteen edellyttämällä sitoutumistasolla; ja
kestävä yhdistäminen oston, selvitystuloksen ja toimituksen välillä.

Älä palauta maksettua sisältöä pelkästään siksi, että Kora hyväksyi transaktion allekirjoitettavaksi. Täytä pyyntö vasta, kun fasilitaattori palauttaa onnistuneen selvitystuloksen.