Walletverbinding

Commerce Kit wordt niet meer onderhouden

Commerce Kit-pakketten ontvangen geen updates of fixes meer. Gebruik voor nieuwe betalingsintegraties Solana Pay.

Het pakket @solana-commerce/connector biedt headless walletverbinding, gebouwd op de Wallet Standard. Het beheert walletdetectie, verbindingsstatus, accountbeheer en automatisch opnieuw verbinden. Het pakket is framework-agnostisch ontworpen en bevat React-bindings. Het is toegesneden op naadloos gebruik in Solana Commerce Kit en is compatibel met @solana/kit.

WalletverbindingWalletverbinding

Installatie

pnpm add @solana-commerce/connector

Providerconfiguratie

ConnectorProvider

De component ConnectorProvider omhult je applicatie en levert de walletverbindingsstatus aan alle onderliggende componenten. Hij beheert één enkele ConnectorClient-instantie (singleton) die behouden blijft over mount-/unmount-cycli van componenten heen.

Props

Alle configuratie wordt doorgegeven via de prop config:

  • config (ConnectorConfig, optioneel) - Configuratieobject voor de connector. Alle velden zijn optioneel.

ConnectorConfig

Configuratieobject voor het gedrag van de walletverbinding.

Optionele velden
  • autoConnect (boolean) - Indien true, wordt bij mount automatisch opnieuw verbonden met de laatst gebruikte wallet. De walletvoorkeur wordt opgeslagen in de geconfigureerde opslag (standaard localStorage). Standaard: false.

  • debug (boolean) - Schakelt uitgebreide consolelogging in om verbindingsflows, accountwijzigingen en fouten te debuggen. Logs bevatten prefixen zoals [Connector] en [ConnectorProvider]. Standaard: false.

  • accountPollingIntervalMs (number) - Pollinginterval in milliseconden voor het controleren op accountwijzigingen wanneer de wallet de functie standard:events niet ondersteunt. De meeste moderne wallets ondersteunen events, dus polling is een terugvaloptie. Standaard: 1500 (1,5 seconden).

  • storage (Storage) - Aangepaste opslagadapter voor het bewaren van walletvoorkeuren. Moet het volgende implementeren:

    • getItem(key: string): string | null
    • setItem(key: string, value: string): void
    • removeItem(key: string): void

    Standaard: window.localStorage indien beschikbaar (alleen in de browser). Gebruik dit voor React Native (AsyncStorage) of aangepaste SSR-veilige opslag.

Providerarchitectuur

De provider gebruikt een singleton-patroon met referentietelling:

  • Meerdere ConnectorProvider-instanties delen dezelfde ConnectorClient
  • De client wordt bij de eerste mount aangemaakt en blijft behouden na unmounts
  • Wanneer alle providers worden ge-unmount, wordt de opschoning 5 seconden uitgesteld om snelle remounts op te vangen
  • Tijdens de opschoning wordt de wallet losgekoppeld en worden alle event listeners verwijderd

Dit ontwerp voorkomt dat de wallet wordt losgekoppeld bij routewijzigingen of componentupdates.


Hooks

useConnector()

De primaire hook voor toegang tot de walletverbindingsstatus en -acties. Moet worden gebruikt binnen een ConnectorProvider.

Retourneert een ConnectorSnapshot-object met:

Statuseigenschappen

  • wallets (WalletInfo[]) - Array van alle gedetecteerde Wallet Standard-compatibele wallets. Wordt automatisch bijgewerkt wanneer wallets worden geïnstalleerd of verwijderd. Elke wallet bevat metadata zoals naam, icoon en mogelijkheden. Zie WalletInfo.

  • selectedWallet (Wallet | null) - Het momenteel verbonden Wallet Standard-walletobject. null wanneer de verbinding is verbroken. Dit is de ruwe walletinstantie uit de Wallet Standard API.

  • connected (boolean) - Verbindingsstatus. true wanneer een wallet is verbonden en accounts beschikbaar zijn. Gebruik dit voor conditionele UI-weergave.

  • connecting (boolean) - Laadstatus tijdens het verbinden van de wallet. true tussen het aanroepen van select() en het ontvangen van het verbindingsresultaat. Gebruik dit om laadindicatoren te tonen of knoppen uit te schakelen.

  • accounts (AccountInfo[]) - Array van accounts van de verbonden wallet. De meeste wallets bieden één account, maar sommige ondersteunen er meerdere. Wordt automatisch bijgewerkt via walletevents of polling. Zie AccountInfo.

  • selectedAccount (string | null) - Het adres van het momenteel geselecteerde account (base58-gecodeerde publieke sleutel). Wanneer een wallet verbinding maakt met een nieuw account, wordt dat account automatisch geselecteerd. Anders blijft het eerder geselecteerde account behouden.

Actiemethoden

  • select ((walletName: string) => Promise<void>) - Maakt verbinding met een wallet op naam (bijv. "Phantom", "Solflare"). De walletnaam moet exact overeenkomen met het veld name van een gedetecteerde wallet.

    Proces:

    1. Zet connecting: true
    2. Roept de functie standard:connect van de wallet aan
    3. Haalt accounts op uit de wallet
    4. Abonneert zich op walletevents (of start polling als events niet beschikbaar zijn)
    5. Slaat de walletvoorkeur op in de geconfigureerde opslag
    6. Werkt de status bij met accounts en het geselecteerde account

    Gooit: Fout als de wallet niet wordt gevonden, de wallet connect niet ondersteunt of de verbinding door de gebruiker is geweigerd.

  • disconnect (() => Promise<void>) - Verbreekt de verbinding met de huidige wallet en ruimt de volledige status op.

    Proces:

    1. Zegt het abonnement op walletevents op
    2. Stopt accountpolling
    3. Roept de functie standard:disconnect van de wallet aan indien beschikbaar
    4. Wist de geselecteerde wallet, accounts en het geselecteerde account
    5. Verwijdert de walletvoorkeur uit de opslag

    Gooit nooit een fout (fouten worden gelogd als debug is ingeschakeld).

  • selectAccount ((address: string) => Promise<void>) - Schakelt het geselecteerde account om naar een ander adres van de verbonden wallet. Als het adres niet in de huidige accounts-array staat, wordt opnieuw verbonden om bijgewerkte accounts op te halen.

    Gooit: Fout als er geen wallet is verbonden of het gevraagde account na het opnieuw verbinden niet wordt gevonden.

useConnectorClient()

Biedt directe toegang tot de onderliggende ConnectorClient-instantie voor geavanceerde use cases.

Retourneert: ConnectorClient | null - De singleton-clientinstantie, of null wanneer gebruikt buiten ConnectorProvider.

Use cases:

  • Directe toegang tot getConnectorState() voor imperatieve statuslezingen
  • Handmatig abonneren met subscribe(listener) voor aangepaste statuslisteners
  • destroy() aanroepen voor geforceerde opschoning (niet aanbevolen bij normaal gebruik)

Voorbeeld:

const client = useConnectorClient();
// Get current state without triggering re-render
const state = client?.getConnectorState();
// Subscribe to state changes manually
useEffect(() => {
if (!client) return;
const unsubscribe = client.subscribe((state) => {
console.log("Wallet state changed:", state);
});
return unsubscribe;
}, [client]);

Typedefinities

WalletInfo

Metadata over een gedetecteerde wallet.

interface WalletInfo {
wallet: Wallet; // Raw Wallet Standard wallet object
name: string; // Display name (e.g., "Phantom", "Solflare")
icon?: string; // Data URL for wallet icon (base64 encoded)
installed: boolean; // Always true (only installed wallets are discovered)
connectable?: boolean; // Whether wallet supports required features
}

Vereisten voor connectable: Een wallet is verbindbaar wanneer deze ondersteunt:

  • de functie standard:connect
  • de functie standard:disconnect
  • Solana-chains (gedetecteerd doordat wallet.chains "solana" bevat)

Niet-verbindbare wallets verschijnen in de wallets-array, maar kunnen niet worden geselecteerd.

AccountInfo

Informatie over een walletaccount.

interface AccountInfo {
address: string; // Base58-encoded public key
icon?: string; // Account-specific icon (data URL)
raw: WalletAccount; // Raw WalletAccount object from Wallet Standard
}

Het veld raw biedt toegang tot aanvullende accounteigenschappen:

  • address: string - Base58-gecodeerde publieke sleutel
  • publicKey: Uint8Array - Ruwe bytes van de publieke sleutel
  • label?: string - Accountlabel (indien door de wallet geleverd)
  • icon?: string - Accountspecifiek icoon (data-URL)
  • chains: string[] - Ondersteunde chains voor dit account
  • features: string[] - Ondersteunde functies voor dit account

ConnectorSnapshot

Het retourtype van useConnector(), dat status en acties combineert.

type ConnectorSnapshot = ConnectorState & {
select: (walletName: string) => Promise<void>;
disconnect: () => Promise<void>;
selectAccount: (address: string) => Promise<void>;
};
interface ConnectorState {
wallets: WalletInfo[];
selectedWallet: Wallet | null;
connected: boolean;
connecting: boolean;
accounts: AccountInfo[];
selectedAccount: string | null;
}

Detectie van accountwijzigingen

De connector detecteert automatisch wanneer walletaccounts veranderen (de gebruiker voegt accounts toe of verwijdert ze, of schakelt tussen accounts in de wallet). Hierbij worden twee strategieën gebruikt:

Eventgebaseerd (voorkeur)

Wanneer de wallet standard:events ondersteunt, abonneert de connector zich op change-events:

  • Ontvangt realtime meldingen wanneer accounts veranderen
  • Efficiënter (geen polling)
  • Voegt accounts uit zowel het event als wallet.accounts samen om wallets op te vangen die alleen het geselecteerde account in events opnemen

Polling als terugvaloptie

Wanneer events niet worden ondersteund, pollt de connector wallet.accounts:

  • Controleert elke accountPollingIntervalMs (standaard: 1500 ms)
  • Vergelijkt accountadressen om wijzigingen te detecteren
  • Veroorzaakt alleen een re-render wanneer accounts daadwerkelijk veranderen

Logica voor accountselectie:

  • Wanneer accounts veranderen, blijft het geselecteerde account behouden als het nog bestaat
  • Als het geselecteerde account is verwijderd, wordt het eerste beschikbare account geselecteerd
  • Bij het verbinden met een nieuw account (dat niet in de vorige accounts zat), krijgt het nieuwe account de voorkeur

Opslag en automatisch verbinden

Persistente opslag

De connector slaat één sleutel op in de geconfigureerde opslag:

  • Sleutel: arc-connector:lastWallet
  • Waarde: Walletnaam (bijv. "Phantom")

Opslagoperaties zijn omgeven door try-catch om het volgende op te vangen:

  • Sandboxed iframes waar localStorage een fout gooit
  • SSR-omgevingen waar window niet is gedefinieerd
  • React Native, waar localStorage niet bestaat

Als de opslag mislukt, gaat de connector verder zonder persistentie (er worden geen fouten gegooid).

Gedrag van automatisch verbinden

Wanneer autoConnect: true:

  1. Leest bij mount de laatste walletnaam uit de opslag
  2. Wacht 100 ms (zodat wallets zich kunnen registreren)
  3. Roept select(walletName) aan als de wallet is gedetecteerd
  4. Als automatisch verbinden mislukt, wordt de ongeldige voorkeur uit de opslag verwijderd

Beveiligingsopmerking: De opgeslagen voorkeur is slechts een walletnaam (string) en geen gevoelige data. De wallet handelt authenticatie/autorisatie af via zijn eigen UI.


Gebruiksvoorbeelden

Eenvoudige walletknop

import { ConnectorProvider, useConnector } from "@solana-commerce/connector";
function App() {
return (
<ConnectorProvider config={{ autoConnect: true }}>
<WalletButton />
</ConnectorProvider>
);
}
function WalletButton() {
const { wallets, select, disconnect, connected, accounts, connecting } =
useConnector();
if (!connected) {
return (
<div>
<h3>Connect Wallet</h3>
{wallets.map((wallet) => (
<button
key={wallet.name}
onClick={() => select(wallet.name)}
disabled={!wallet.connectable || connecting}
>
{wallet.icon && (
<img src={wallet.icon} alt={wallet.name} width={24} />
)}
{wallet.name}
{!wallet.connectable && " (Unsupported)"}
</button>
))}
</div>
);
}
return (
<div>
<p>Connected: {accounts[0]?.address.slice(0, 8)}...</p>
<button onClick={disconnect}>Disconnect</button>
</div>
);
}

Accountkiezer voor meerdere accounts

function AccountSelector() {
const { accounts, selectedAccount, selectAccount } = useConnector();
if (accounts.length <= 1) return null;
return (
<select
value={selectedAccount || ""}
onChange={(e) => selectAccount(e.target.value)}
>
{accounts.map((account) => (
<option key={account.address} value={account.address}>
{account.raw.label || `${account.address.slice(0, 8)}...`}
</option>
))}
</select>
);
}

Verbindingsmonitoring

function ConnectionMonitor() {
const { connected, selectedWallet, accounts } = useConnector();
useEffect(() => {
if (connected) {
console.log("Wallet connected:", selectedWallet?.name);
console.log(
"Accounts:",
accounts.map((a) => a.address)
);
}
}, [connected, selectedWallet, accounts]);
return null;
}

Ondersteunde wallets

De connector ondersteunt alle wallets die de Wallet Standard implementeren, waaronder:

  • Phantom
  • Solflare
  • Backpack
  • Glow
  • Brave Wallet
  • Coinbase Wallet
  • Elke andere Wallet Standard-compatibele wallet

Wallets worden automatisch gedetecteerd wanneer ze zich registreren bij de Wallet Standard API (geen configuratie nodig).


Headless gebruik (zonder React)

Gebruik voor niet-React-applicaties of server-side gebruik ConnectorClient rechtstreeks:

import { ConnectorClient } from "@solana-commerce/connector";
const connector = new ConnectorClient({
autoConnect: true,
debug: true
});
// Get current state
const state = connector.getConnectorState();
console.log("Available wallets:", state.wallets);
// Connect to a wallet
await connector.select("Phantom");
// Subscribe to state changes
const unsubscribe = connector.subscribe((state) => {
console.log("Connected:", state.connected);
console.log("Accounts:", state.accounts);
});
// Switch account
await connector.selectAccount("account-address-here");
// Disconnect
await connector.disconnect();
// Cleanup (removes all listeners and timers)
connector.destroy();

Opmerking: ConnectorClient beheert zijn eigen status en veroorzaakt nooit React-re-renders. Je moet handmatig abonneren op statuswijzigingen.

Is this page helpful?

© 2026 Solana Foundation. Alle rechten voorbehouden.