Transfer Hook -integraatio-opas

Tausta

Transfer Hook -laajennus antaa Token-2022-mintille mahdollisuuden vaatia Cross Program Invocation (CPI) -kutsun mukautettuun ohjelmaan jokaisessa tokenin siirrossa. Mintti tallentaa hook-ohjelman osoitteen, ja jokaisen lompakon, dapin tai säilytyspalvelun, joka lähettää kyseistä tokenia, täytyy sisällyttää hook-ohjelman tarvitsemat tilit, jotta CPI voi suorittua.

Tämä opas on tarkoitettu tiimeille, jotka integroivat transfer hookia käyttäviä tokeneita (lompakot, dapit, säilytyspalvelut, pörssit, selaimet), ei tiimeille, jotka kirjoittavat hook-ohjelmaa. Jos rakennat hook-ohjelmaa, aloita Transfer Hook Interface -dokumentaatiosta ja Transfer Hook -laajennusoppaasta; tässä oppaassa keskitytään siihen, mitä asiakkaan täytyy tehdä lähettääkseen, vastaanottaakseen ja simuloidakseen hook-aktivoidun tokenin siirtoja oikein.

Toisin kuin useimmat muut Token-2022-laajennukset, transfer hook ei ole valinnainen tilitasolla. Jos mintillä on määritetty transfer hook, jokainen kyseisen tokenin siirto vaatii hookin lisätilit, riippumatta siitä, tekeekö tuotteesi mitään hookin logiikalla. Asiakasohjelma, joka ei selvitä näitä tilejä, ei voi lähettää tokenia lainkaan; siirto-ohje epäonnistuu onchain-tasolla eikä ohita hookia hiljaa. Valmiit funktiot, jotka voit lisätä omaan lähetyspolkuusi, löytyvät alta kohdasta Transfer hook -tokenin lähettäminen Kitille, web3.js v3:lle ja legacy web3.js:lle.

Resurssit

• Transfer Hook Interface -viite
• Laajennuksen Rust-koodi
• @solana-program/token-2022 JS client Kit-pohjainen asiakaskirjasto, jota suositellaan uusiin integraatioihin ja jota myös web3.js v3 -koodi käyttää. Natiivi transfer hookin selvitys funktiolla getTransferCheckedWithTransferHookInstructionAsync sekä alemman tason apufunktiot resolveExtraAccountMetasForExecute / findExtraAccountMetaListPda.
• @solana/spl-token JS client legacy-asiakaskirjasto @solana/web3.js v1:lle. Kattaa saman alueen (laajennusten tunnistus, lisätilien selvitys, korkean tason apufunktio createTransferCheckedWithTransferHookInstruction) legacy web3.js:ää käyttäville tiimeille.
• Transfer Hook -laajennusopas (hook-ohjelman kirjoittaminen, kontekstiksi siitä, mitä liikkeeseenlaskijat määrittävät)

TL;DR

• Transfer hook -mintti tallentaa hook-ohjelman osoitteen. Jokainen siirto tekee CPI-kutsun kyseiseen ohjelmaan, ja CPI tarvitsee lisätilejä tavallisten siirtotilien lisäksi.
• Hookin tarvitsemat lisätilit on listattu ketjussa olevassa ExtraAccountMetaList-tilissä, joka on hook-ohjelmasta ja mintistä johdettu PDA. Asiakkaat lukevat tätä tiliä selvittääkseen, mitkä tilit liitetään siirto-instruktioon.
• Ratkaisu ei ole valinnainen. Jos lisätilit puuttuvat tai ovat vanhentuneita, siirto-instruktio epäonnistuu ketjussa. Ei ole varatoimintoa, joka lähettäisi tokenin hiljaisesti ilman hookia.
• Kit, web3.js v3 ja legacy web3.js pystyvät kaikki lähettämään hook-siirron päästä päähän – katso valmiit funktiot kohdasta Transfer hook -tokenin lähettäminen. Jokainen selvittää ExtraAccountMetaList-listan natiivisti: Kit ja web3.js v3 funktiolla @solana-program/token-2022:n getTransferCheckedWithTransferHookInstructionAsync, legacy web3.js funktiolla @solana/spl-token:n createTransferCheckedWithTransferHookInstruction.
• Simuloi aina ennen lähettämistä. Hook-ohjelma voi hylätä siirron mistä tahansa määrittelemästään syystä (sallittujen lista, pysäytetty tila, puuttuva delegointi), ja lisätilien joukko voi muuttua, jos liikkeeseenlaskija päivittää hookin. Simulointi paljastaa molemmat ongelmat ennen kuin käyttäjä allekirjoittaa.
• Hookin suorittaminen lisää laskentayksiköitä ja — hookeille, jotka vaativat etukäteen rahoitettuja tai etukäteen hyväksyttyjä sivutilejä (delegoitu maksutilit, laskuri-PDA, jota käyttäjä ei ole vielä alustanut) — voi vaatia asennustransaktioita ennen kuin ensimmäinen siirto onnistuu.

Termit

• Hook-ohjelma: ohjelma, jolle mintti delegoi siirtoajan logiikan, asetetaan Transfer Hook -laajennuksen kautta mintissä.
• ExtraAccountMetaList: PDA, jonka omistaa hook-ohjelma ja joka tallentaa listan lisätileistä, joita hookin Execute-instruktio tarvitsee. Johdettu siemenistä "extra-account-metas" ja mintin osoitteesta.
• ExtraAccountMeta: yksi merkintä kyseisessä listassa. Se voi viitata kiinteään osoitteeseen, hook-ohjelmasta johdettuun PDA:han, eri ohjelmasta johdettuun PDA:han tai PDA:han, jonka siemenet on luettu siirron omien tilien datasta.
• TransferHookAccount-laajennus: token account -tiliin tallennettu tila, joka sisältää transferring-lipun; asetettu arvoon true vain silloin, kun token-ohjelma on kesken CPI-kutsua hookiin. Hook-ohjelmat käyttävät sitä hylätäkseen kutsut, jotka eivät peräisin todellisesta siirrosta.
• Execute: instruktio, jonka token-ohjelma CPI-kutsuu jokaisessa siirrossa. Asiakkaat eivät kutsu sitä suoraan; se käynnistetään osana TransferChecked-kutsua.

Transfer-hook-tokenin lähettäminen

Jokaisen hook-siirron on tehtävä neljä asiaa: tunnistettava, että mintillä on transfer hook, selvitettävä hookin CPI-kutsun tarvitsemat lisätilit, simuloitava ja vasta sitten lähetettävä. Jokainen alla oleva funktio tekee kaikki neljä, ja ne voi lisätä siihen kohtaan, jossa sovelluksesi nykyisin rakentaa Token-2022-siirron.

Kit

@solana-program/token-2022-asiakas ratkaisee kaiken natiivisti getTransferCheckedWithTransferHookInstructionAsync-funktion kautta: se hakee mintin, tunnistaa onko transfer hook määritetty, ratkaisee ExtraAccountMetaList-tiedot ja liittää hookin lisätilit. Kun mintillä ei ole hookia, se palauttaa tavallisen transferChecked-kutsun, joten sama kutsu kattaa molemmat tapaukset ilman siltausta legacy-asiakkaaseen.

import {
  appendTransactionMessageInstructions,
  assertIsTransactionWithBlockhashLifetime,
  compileTransaction,
  createTransactionMessage,
  getBase64EncodedWireTransaction,
  pipe,
  sendAndConfirmTransactionFactory,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  signTransactionMessageWithSigners,
  type Address,
  type Rpc,
  type RpcSubscriptions,
  type SolanaRpcApi,
  type SolanaRpcSubscriptionsApi,
  type TransactionSigner
} from "@solana/kit";
import { getTransferCheckedWithTransferHookInstructionAsync } from "@solana-program/token-2022";

/**
 * Builds, simulates, and sends a Token-2022 transfer, resolving transfer
 * hook extra accounts when the mint requires them. Drop this in wherever
 * your app currently builds a Token-2022 transfer instruction with Kit.
 */
export async function sendTokenTransfer({
  rpc,
  rpcSubscriptions,
  source,
  mint,
  destination,
  owner,
  feePayer,
  amount,
  decimals
}: {
  rpc: Rpc<SolanaRpcApi>;
  rpcSubscriptions: RpcSubscriptions<SolanaRpcSubscriptionsApi>;
  source: Address;
  mint: Address;
  destination: Address;
  owner: TransactionSigner; // Authority over the source token account.
  feePayer: TransactionSigner;
  amount: bigint;
  decimals: number;
}) {
  // 1. Build the transfer instruction. When the mint has a transfer hook this
  // fetches it, resolves the ExtraAccountMetaList, and appends the accounts the
  // hook's CPI needs; when it doesn't, you get a plain transferChecked. Because
  // it re-fetches the mint on every call, don't cache the result across sends
  // -- the hook program and its extra accounts can both change.
  const instruction = await getTransferCheckedWithTransferHookInstructionAsync(
    { rpc },
    {
      source,
      mint,
      destination,
      authority: owner,
      amount,
      decimals
    }
  );

  const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
  const message = pipe(
    createTransactionMessage({ version: 0 }),
    (tx) => setTransactionMessageFeePayerSigner(feePayer, tx),
    (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx),
    (tx) => appendTransactionMessageInstructions([instruction], tx)
  );

  // 2. Simulate before signing, so the user is never prompted to authorize a
  // transfer the hook would reject. Compiling the message (rather than signing
  // it) is enough to simulate, and sigVerify: false lets the network run it
  // without signatures. This catches a hook rejecting the transfer (an
  // allowlist check, a paused mint, ...) or a stale ExtraAccountMetaList before
  // anyone signs or pays a fee.
  const simulation = await rpc
    .simulateTransaction(
      getBase64EncodedWireTransaction(compileTransaction(message)),
      { encoding: "base64", sigVerify: false, replaceRecentBlockhash: true }
    )
    .send();
  if (simulation.value.err) {
    throw new Error(
      `Transfer simulation failed: ${JSON.stringify(simulation.value.err)}\n` +
        simulation.value.logs?.join("\n")
    );
  }

  // 3. Sign only after a successful simulation, then send.
  const signedMessage = await signTransactionMessageWithSigners(message);
  assertIsTransactionWithBlockhashLifetime(signedMessage);
  await sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions })(
    signedMessage,
    { commitment: "confirmed" }
  );
}

Web3.js

Molemmat web3.js-sukupolvet selvittävät kaiken natiivisti. Versiossa v3 käytä edelleen Connection-oliota rakentamiseen ja lähettämiseen ja välitä Kit RPC (oletuksena connection.rpcEndpoint-osoitteesta rakennettu) funktiolle @solana-program/token-2022:n getTransferCheckedWithTransferHookInstructionAsync, joka palauttaa ohjeen, jonka v3-Transaction hyväksyy suoraan. Legacy web3.js:ssä @solana/spl-token:n createTransferCheckedWithTransferHookInstruction kattaa saman alueen.

import {
  Connection,
  Keypair,
  PublicKey,
  Transaction,
  sendAndConfirmTransaction
} from "@solana/web3.js";
import { createSolanaRpc, type GetAccountInfoApi, type Rpc } from "@solana/kit";
import { getTransferCheckedWithTransferHookInstructionAsync } from "@solana-program/token-2022";

/**
 * Builds, simulates, and sends a Token-2022 transfer, resolving transfer
 * hook extra accounts when the mint requires them. Drop this in wherever
 * your app currently builds a Token-2022 transfer instruction directly.
 */
export async function sendTokenTransfer({
  connection,
  rpc = createSolanaRpc(connection.rpcEndpoint),
  payer,
  source,
  mint,
  destination,
  owner,
  amount,
  decimals
}: {
  connection: Connection;
  // Kit RPC used to resolve the transfer hook's extra accounts. Defaults to one
  // for `connection.rpcEndpoint`; pass your own if `connection` relies on custom
  // headers, `fetch`, or `fetchMiddleware`, since those aren't carried over.
  rpc?: Rpc<GetAccountInfoApi>;
  payer: Keypair; // Fee payer; can be the same signer as `owner`.
  source: PublicKey;
  mint: PublicKey;
  destination: PublicKey;
  owner: Keypair; // Authority over the source token account.
  amount: bigint;
  decimals: number;
}) {
  // 1. Build the transfer instruction. When the mint has a transfer hook this
  // fetches it, resolves the ExtraAccountMetaList, and appends the accounts the
  // hook's CPI needs; when it doesn't, you get a plain transferChecked. Because
  // it re-fetches the mint on every call, don't cache the result across sends
  // -- the hook program and its extra accounts can both change.
  const instruction = await getTransferCheckedWithTransferHookInstructionAsync(
    { rpc },
    {
      source: source.toBase58(),
      mint: mint.toBase58(),
      destination: destination.toBase58(),
      authority: owner,
      amount,
      decimals
    }
  );

  const { blockhash, lastValidBlockHeight } =
    await connection.getLatestBlockhash();
  const transaction = new Transaction({
    feePayer: payer.publicKey,
    blockhash,
    lastValidBlockHeight
  }).add(instruction);

  // 2. Simulate before signing, so the user is never prompted to authorize a
  // transfer the hook would reject. Simulating without signers runs the
  // transaction unsigned, which catches a hook rejecting the transfer (an
  // allowlist check, a paused mint, ...) or a stale ExtraAccountMetaList before
  // anyone signs or pays a fee.
  const simulation = await connection.simulateTransaction(transaction);
  if (simulation.value.err) {
    throw new Error(
      `Transfer simulation failed: ${JSON.stringify(simulation.value.err)}\n` +
        simulation.value.logs?.join("\n")
    );
  }

  // 3. Sign and send only after a successful simulation.
  return sendAndConfirmTransaction(connection, transaction, [payer, owner]);
}

Laajennuksen tunnistaminen

Kaikki kolme yllä olevaa funktiota hakevat mintin uudelleen ja tarkistavat hookin jokaisen lähetyksen yhteydessä: legacy web3.js erikseen funktiolla getMint, Kit ja web3.js v3 funktion getTransferCheckedWithTransferHookInstructionAsync sisällä, joka hakee mintin ennen kuin se selvittää mitään.

Parillinen TransferHookAccount-laajennus sijaitsee token account -tileillä, ei mintissä. Integraattorien ei yleensä tarvitse lukea sitä suoraan. Se on olemassa, jotta hook-ohjelma itse voi vahvistaa, että kutsu tapahtui todellisen siirron sisällä, ei koska asiakas kutsui Execute-funktiota suoraan.

Lisätilien ratkaiseminen

Jokainen hook-aktivoitu siirto tarvitsee neljä vakiosiirtotiliä (lähde, mintti, kohde, omistaja/auktoriteetti) sekä kaiken sen, mitä kyseisen mintin ExtraAccountMetaList- tili määrittää. Lista on PDA, joka on johdettu hook-ohjelmasta:

// Kit and web3.js v3 with @solana-program/token-2022
import { findExtraAccountMetaListPda } from "@solana-program/token-2022";

const [extraAccountMetaListPda] = await findExtraAccountMetaListPda(
  { mint: mintAddress },
  { programAddress: transferHook.programId }
);

// Web3.js (legacy) with @solana/spl-token
import { getExtraAccountMetaAddress } from "@solana/spl-token";

const extraAccountMetaListPda = getExtraAccountMetaAddress(
  mintAddress,
  transferHook.programId
);

Jokainen kyseisen tilin merkintä ratkeaa konkreettiseksi AccountMeta-arvoksi neljällä tavalla: kiinteä pubkey, hook-ohjelmasta johdettu PDA, aiemmin tililistassa mainitusta eri ohjelmasta johdettu PDA, tai PDA, jonka siemenet on luettu tavuina yhdestä siirron omista tileistä (esimerkiksi lähde-token accountin omistaja). Data-siemenistetyn tapauksen ratkaiseminen vaatii tilidatan hakemisen RPC:n kautta, minkä vuoksi ratkaisu on asynkroninen ja voi vaatia useamman kuin yhden edestakaisin matkan.

Tilien kokoaminen manuaalisesti

Jos kokoat instruktiota itse sen sijaan, että käyttäisit yllä olevia funktioita, molemmilla asiakkailla on alemman tason osat, joista nämä funktiot on rakennettu.

Kit ja web3.js v3 kirjastolla @solana-program/token-2022

• findExtraAccountMetaListPda({ mint }, { programAddress }): johtaa ExtraAccountMetaList-validointitili PDA:n.
• getExtraAccountMetasDecoder().decode(accountData): jäsentää raakavalidointitili- datan listaksi ExtraAccountMeta-merkintöjä.
• resolveExtraAccountMeta(meta, previousAddresses, instructionData, hookProgramAddress, rpc): ratkaisee yhden merkinnän AccountMeta-arvoksi, annettuaan tähän mennessä ratkaistut osoitteet (myöhemmät merkinnät voivat viitata aiempiin).
• resolveExtraAccountMetasForExecute({ rpc, transferHookProgramAddress, source, mint, destination, owner, amount }): ratkaisee jokaisen merkinnän ja palauttaa metat liitettäväksi — lisätilit, hook-ohjelma ja validointitili. Kit-instruktiot ovat muuttumattomia, joten se palauttaa metat, jotka levitetään instruktioon sen sijaan, että mutatoitaisiin sitä paikan päällä.

Web3.js (legacy) kirjastolla @solana/spl-token

• getExtraAccountMetas(account): dekoodaa raaka-ExtraAccountMetaList- tilidatan listaksi ExtraAccountMeta-merkintöjä.
• resolveExtraAccountMeta(connection, meta, previousMetas, instructionData, hookProgramId): ratkaisee yhden merkinnän AccountMeta-arvoksi, annettuaan tähän mennessä ratkaistut tilit (myöhemmät merkinnät voivat viitata aiempiin).
• addExtraAccountMetasForExecute(connection, instruction, hookProgramId, source, mint, destination, owner, amount): ratkaisee ja liittää jokaisen merkinnän olemassa olevaan instruktioon yhdellä kutsulla.

Simulointi ennen lähettämistä

Yllä olevien funktioiden simulointivaihe on tärkeä, koska kaksi asiaa voi mennä pieleen siten, että ne paljastuvat vasta suoritusvaiheessa.

• Hook hylkää siirron. Hook-ohjelma voi koodata mielivaltaisia ehtoja (sallittujen lista, pysäytetty mintti, siirtokohtainen raja) ja epäonnistuttaa koko instruktion, lähde ja kohde mukaan lukien, jos ehto ei täyty. Osittaisen onnistumisen tapauksia ei ole: hylätty hook-kutsu hylkää siirron.
• Lisätilit ovat vanhentuneita. Jos liikkeeseenlaskija muutti hook-ohjelmaa tai päivitti ExtraAccountMetaList-tiedot sen jälkeen, kun asiakkaasi viimeksi välimuistitti jotain, ja käyttäjä lähettää, vanhojen tietojen perusteella ratkaiseminen tuottaa väärät tilit ja siirto epäonnistuu tilivalidointivirheellä, ei hook-logiikkavirheellä.

Simuloimalla ensin ja lähettämällä transaktio vasta onnistuneen simulaation jälkeen voidaan molemmat tapaukset havaita ennen kuin käyttäjä maksaa maksun epäonnistuneesta transaktiosta. Tämä mahdollistaa myös selkeän virheilmoituksen näyttämisen käyttäjälle (miksi siirto ei voi onnistua) raakatransaktiovirheen sijaan.

Laskentaresurssit ja käyttöönoton vaikutukset

Hook-ohjelman CPI suoritetaan siirron laskentabudjetin puitteissa. Hook, joka tekee merkittävää työtä (lukee useita tilejä, suorittaa omia tarkistuksiaan), lisää todellisia laskentakustannuksia perussiirron päälle. Siksi riittävän suuren laskentayksikkörajan pyytäminen hook-pohjaisille siirroille vähentää tarpeettomia epäonnistumisia.

Jotkin hookit vaativat myös, että tietyt tilit ovat olemassa ennen ensimmäisen siirron onnistumista – ei pelkästään ratkaistavissa: esimerkiksi delegoitu maksu-token account, jonka lähettäjän täytyy rahoittaa ja hyväksyä (kuten wSOL-maksu-hookissa), tai laskuri- tai sallittujen listauksen merkintä, jonka liikkeeseenlaskijan ohjelma edellyttää jo alustettuna kyseiselle omistajalle. Asiakastoteutukset, jotka ainoastaan ratkaisevat tilit eivätkä koskaan ilmoita käyttäjälle "tämä token vaatii kertaluonteisen käyttöönoton ennen lähettämistä", kohtaavat lähetysvirheitä syistä, joilla ei ole mitään tekemistä saldon tai verkon tilan kanssa.

Tilit ovat vain luettavissa hook-CPI:n aikana

Kun token program suorittaa CPI:n hook-ohjelmaan, se välittää kaikki alkuperäisen siirron tilit – mukaan lukien lähettäjän oman tilin – vain luettavina, eikä lähettäjän allekirjoittajaoikeudet siirry hookiin. Hook-ohjelma ei siis voi siirtää tokeneita lähettäjän tileiltä omalla valtuudellaan CPI:n aikana. Hook, jonka täytyy siirtää sivumaksu – esimerkiksi maksu toisessa tokenissa – tekee sen delegaatin kautta, jonka lähettäjä on etukäteen hyväksynyt; tämä on sama kertaluonteinen käyttöönotto kuin edellä kuvattu.

Taaksepäin yhteensopivuus

Siirtohookit käyttäytyvät eri tavalla kuin useimmat muut Token-2022-laajennukset tukemattomien asiakkaiden osalta:

• Lompakko tai dapp, joka ei ratkaise siirtohook-tilejä, ei voi lähettää hook-pohjaista tokenia. Transaktio epäonnistuu token program -tasolla, eikä se palaa hiljaisesti tavalliseksi siirroksi.
• Hook-pohjaisen tokenin vastaanottaminen ei vaadi erityistä käsittelyä. Hook käynnistyy vain lähettäjän siirto-instruktiosta; lompakko tarvitsee siirtohook-tuen vasta, kun sen käyttäjä haluaa lähettää kyseisen tokenin eteenpäin.
• Koska hook-ohjelman voi päivittää mintin siirtohook-auktoriteetti, kohtele siirtohook-minttiä asiana, joka tarkistetaan uudelleen jokaisen siirron yhteydessä – ei kerran opittuna ja määräämättömäksi ajaksi välimuistiin tallennettuna tietona.

Suositellut integraatioprioriteetit

Lompakot ja dapit

Säilytyspalvelut ja pörssit

Selaimet ja indeksoijat