Zum Inhalt

dApp Rezepte

Wallet

Wallet mit der dApp verbinden

Das @alephium/web3-react bietet leistungsstarke React-Komponenten und Hooks, um eine Wallet mit Ihrer dApp zu verbinden.

Wallet mit der dApp verbinden
TypeScript
// Alephium Kontext Provider
<AlephiumWalletProvider theme='retro' network='devnet'>
  <YourComponent />
</AlephiumWalletProvider>

// Verbinden-Button
<AlephiumConnectButton />

// Wallet Hook
const { connectionStatus, signer, account } = useWallet()

// Kontostand-Hook
const { balance } = useBalance()

// Verbindungshook, der vom `<AlephiumConnectButton />` unter der Haube verwendet wird
const { connect, disconnect } = useConnect()

Web3 SDK Wallets

Das SDK stellt einige grundlegende Wallets für Entwickler bereit.

HD Wallet/Private Key Wallet
TypeScript
// HD Wallet
const mnemonic = bip39.generateMnemonic(128)
const hdWallet = new HDWallet({ mnemonic })

// Private key Wallet
const wallet0 = new PrivateKeyWallet({ privateKey })
const wallet1 = PrivateKeyWallet.Random()
const wallet2 = PrivateKeyWallet.FromMnemonic({ mnemonic })

Wallet testen

Die Bibliothek @alephium/web3-test bietet bequeme Wallets für Testzwecke.

Wallet Test
TypeScript
// Testnet-Testwallet, das standardmäßig 1 Million ALPH enthält
const wallet = testNodeWallet()

// Generiere zufällige Signatur-Wallet für Testzwecke.
const signer = getSigner()

// Generiere eine Liste von zufälligen Wallets für Testzwecke.
const signers = getSigners()

Token

Hole Metadaten für fungible Token ab.

TypeScript
nodeProvider.fetchFungibleTokenMetaData(tokenId)

Hole die im Umlauf befindliche Gesamtmenge/gesamte Menge eines Tokens.

Der folgende Code ruft die von dem Token-Entwickler programmierte Gesamtmenge ab. Beachten Sie, dass zur Vertrauenswürdigkeit eine tatsächliche Verifizierung des Vertrags erforderlich ist.

TypeScript
(await nodeProvider.fetchFungibleTokenMetaData(tokenId)).totalSupply

Es gibt keine direkte Funktion für die im Umlauf befindliche Gesamtmenge gemäß dem ERC20-Standard.

TODO: Abfrage der Token-Ausgabemenge im Explorer-Backend, um vertrauenswürdigere Informationen bereitzustellen.

Hole NFT Metadaten

TypeScript
nodeProvider.fetchNFTMetaData(nftTokenId)

Hole Metadaten der Sammlung.

TypeScript
nodeProvider.fetchNFTCollectionMetaData(nftCollectionId)

Contract (Vertrag)

Zustand des Smart Contracts abrufen

Wenn Sie den Befehl npx @alephium/cli compile verwenden, um einen Smart Contract zu kompilieren, wird TypeScript-Code basierend auf dem Smart Contract generiert. Nehmen wir den Token Faucet-Smart Contract als Beispiel, hier ist der generierte TypeScript-Code. Wir können den generierten TypeScript-Code verwenden, um den Zustand des Smart Contracts abzurufen:

Token Faucet/Zustand des Smart Contracts abrufen
TypeScript
import { TokenFaucet } from 'artifacts/ts' // Beachten Sie, dass Sie den Importpfad entsprechend der Verzeichnisstruktur Ihres Projekts ändern müssen.
import { web3, NodeProvider } from '@alephium/web3'

const nodeUrl = 'http://127.0.0.1:12973'
const nodeProvider = new NodeProvider(nodeUrl)
web3.setCurrentNodeProvider(nodeProvider)

const tokenFaucetAddress = 'y1btMZHTvMvHEqLTdx1JHvEXq3tmVfqsY2rwM669upiT'
const tokenFaucet = TokenFaucet.at(tokenFaucetAddress)
const contractState = await tokenFaucet.fetchState()

// The names in `contractState.fields` are the same as the field names in the TokeFaucet contract
const { symbol, name, decimals, supply, balance  } = contractState.fields

// You can also get the assets owned by the contract
const { alphAmount, tokens } = contractState.asset

Methode des Smart Contracts aufrufen

Sie können den generierten TypeScript-Code verwenden, um die Methoden des Smart Contracts aufzurufen. Dies ähnelt dem eth_call in Ethereum:

Token Faucet/Methode des Smart Contracts aufrufen
TypeScript
import { TokenFaucet } from 'artifacts/ts'
import { web3, NodeProvider } from '@alephium/web3'

const nodeUrl = 'http://127.0.0.1:12973'
const nodeProvider = new NodeProvider(nodeUrl)
web3.setCurrentNodeProvider(nodeProvider)

const tokenFaucetAddress = 'y1btMZHTvMvHEqLTdx1JHvEXq3tmVfqsY2rwM669upiT'
const tokenFaucet = TokenFaucet.at(tokenFaucetAddress)
const totalSupply = await tokenFaucet.methods.getTotalSupply()

Ereignisse des Smart Contract abonnieren

Im Token Faucet-Smart Contract haben wir ein Withdraw-Ereignis definiert. Jedes Mal, wenn die Withdraw-Funktion aufgerufen wird, gibt der Smart Contract ein Withdraw-Ereignis aus. Wir können die Abhebungsereignisse mit dem folgenden Ansatz abonnieren:

Token Faucet/Ereignisse des Smart Contract abonnieren
TypeScript
import { TokenFaucet, TokenFaucetTypes } from 'artifacts/ts'
import { EventSubscribeOptions } from '@alephium/web3'

// `TokenFaucetTypes.WithdrawEvent` ist ein generierter TypeScript-Typ
const options: EventSubscribeOptions<TokenFaucetTypes.WithdrawEvent> = {
  // Wir geben das Abfrageintervall als 4 Sekunden an, wodurch der Vertrag alle 4 Sekunden auf neue Ereignisse abgefragt wird.
  pollingInterval: 4000,
  // Der `messageCallback` wird jedes Mal aufgerufen, wenn ein neues Ereignis empfangen wird.
  messageCallback: (event: TokenFaucetTypes.WithdrawEvent): Promise<void> => {
    console.log(`Withdraw(${event.fields.to}, ${event.fields.amount})`)
    return Promise.resolve()
  },
  // Der `errorCallback` wird aufgerufen, wenn ein Fehler auftritt. Hier kündigen wir das Abonnement und protokollieren den Fehler.
  errorCallback: (error, subscription): Promise<void> => {
    console.error(error)
    subscription.unsubscribe()
    return Promise.resolve()
  },
  // Der onEventCountChanged-Rückruf ist ein optionales Parameter, der aufgerufen wird, wenn sich der Vertragsereigniszähler ändert.
  onEventCountChanged: (eventCount): Promise<void> => {
  },
}

// Wir abonnieren Vertragsereignisse ab Ereigniszähler 0.
// Wir können auch den aktuellen Ereigniszähler im onEventCountChanged-Rückruf persistieren,
// was es uns ermöglicht, beim nächsten Abonnement ab dem letzten Ereigniszähler zu abonnieren.
const fromEventCount = 0
const subscription = tokenFaucet.subscribeWithdrawEvent(options, fromEventCount)

// Das Abonnement kündigen
subscription.unsubscribe()

Testfunktionen mit simulierter Blockzeit

Es ist möglich, Funktionen in Unit-Tests mit simulierter Blockzeit zu testen. Für Integrationstests, die auf Testnetz oder Devnet basieren, gibt es jedoch keine Möglichkeit, die Blockzeit zu ändern.

Hier ist ein einfaches Beispiel:

Token Faucet/Testfunktion mit simulierter Blockzeit
TypeScript
import { TokenFaucet } from 'artifacts/ts'

const result = await TokenFaucet.tests.withdraw({
  blockTimeStamp: 1706284941000, // Die Einheit ist Millisekunde
  address: ...,
  initialFields: ...,
  ...
})

Debug-Nachrichten protokollieren

Ralph unterstützt Debug-Nachrichten durch das Auslösen des integrierten Ereignisses Debug. Beachten Sie, dass solche Ereignisse im Mainnet ignoriert werden.

Simple Ralph contract
TypeScript
// Einfacher Ralph-Vertrag
Contract Debug() {
    pub fn debug() -> () {
        emit Debug(`Hello, ${nullContractAddress!()}!`)
    }
}

// Unittest in TypeScript
const result = await Debug.tests.debug()

// Die folgende Zeile wird in der Konsolenausgabe und den Protokollen des Vollknotens erscheinen:
//   Debug - tgx7VNFoP9DJiFMFgXXtafQZkUvyEdDHT9ryamHJYrjq - Hello, tgx7VNFoP9DJiFMFgXXtafQZkUvyEdDHT9ryamHJYrjq!

// Alle Debug-Nachrichten abrufen
console.log(result.debugMessages)

Transaktion

Transaktionsstatus abfragen

Sie können den Transaktionsstatus wie folgt abfragen:

Transaktionsstatus abfragen
TypeScript
import { NodeProvider } from '@alephium/web3'

const nodeUrl = 'http://127.0.0.1:12973'
const nodeProvider = new NodeProvider(nodeUrl)

const txId = '919d4e4b1080d74beb56a1f78ea7c0569a358e3ea3988058987cc1addf4b93cc'
const txStatus = await nodeProvider.transactions.getTransactionsStatus({ txId })

Sie können den Transaktionsstatus anhand von txStatus.type unterscheiden:

  1. MemPooled: Dies bedeutet, dass die Transaktion im Mempool ist
  2. Confirmed: Die Transaktion wurde bestätigt, und Sie können die Bestätigungen mit txStatus.chainConfirmations abrufen
  3. TxNotFound: Die Transaktion existiert nicht

Hooks

Das Paket @alephium/web3-react stellt mehrere Hooks zur Verfügung, um die Entwicklung von Frontend-Benutzeroberflächen zu erleichtern.

useWalletConfig

useWalletConfig

```typescript import { useWalletConfig } from '@alephium/web3-react'

export function Component() { const { network, setNetwork, addressGroup, setAddressGroup } = useWalletConfig()

return

}

Das useWalletConfig-Hook gibt die Konfigurationen des Verbindungsbuttons und Hilfsfunktionen zurück, um diese Konfigurationen zu aktualisieren.

useWallet

useWallet
TypeScript
import { useWallet, Wallet } from '@alephium/web3-react'

function Component() {
  const { account, connectionStatus } = useWallet()

  if (connectionStatus === 'connecting') return <div>Connecting</div>
  if (connectionStatus === 'disconnected') return <div>Disconnected</div>

  // verbunden
  return <div>{account}</div>
}

Wenn der Rückgabewert undefined ist, deutet dies darauf hin, dass die Wallet nicht verbunden ist. Die zurückgegebene Wallet hat die folgenden Felder:

  • wallet.signer: Sie können den Signer verwenden, um Transaktionen zu signieren.
  • wallet.account: Dies ist das aktuell verbundene Konto.
  • wallet.nodeProvider: Sie können den Node-Provider verwenden, um mit dem Full Node zu kommunizieren. Beachten Sie, dass dieser Wert undefined sein kann.

useBalance

useBalance
TypeScript
import { useBalance } from '@alephium/web3-react'

const { balance, updateBalanceForTx } = useBalance()

Das useBalance-Hook gibt zwei Werte zurück:

  1. balance: Das aktuelle Guthaben des verbundenen Kontos.
  2. updateBalanceForTx: Dies wird verwendet, um das Guthaben zu aktualisieren, wenn der Benutzer eine Transaktion durchführt. Es nimmt eine Transaktions-ID als Parameter entgegen und aktualisiert das Guthaben, sobald diese Transaktion bestätigt wurde.

useTxStatus

useTxStatus
TypeScript
import { useState } from 'react'
import { useTxStatus } from '@alephium/web3-react'

const { txStatus } = useTxStatus(txId)
const confirmed = useMemo(() => {
  return txStatus?.type === 'Confirmed'
}, [txStatus])

Das useTxStatus-Hook akzeptiert auch einen optionalen Rückrufparameter vom Typ (txStatus: node.TxStatus) => Promise<any>. Dieser wird nach jeder Abfrage des Transaktionsstatus aufgerufen.

Hilfsprogramme

Begrenzungslimit

Der NodeProvider wird verwendet, um beim Entwickeln einer DApp mit dem Full Node zu kommunizieren, und Sie können die von Alephium öffentlich bereitgestellten API services verwenden. Aber alle APIs unterliegen einer Ratenbegrenzung, um Spam zu verhindern. Wenn der Client also in einer bestimmten Zeitspanne zu viele Anfragen sendet, erhält er den HTTP-429-Fehler.

Sie können fetch-retry verwenden, um dieses Problem zu lösen:

fetchRetry
TypeScript
import * as fetchRetry from 'fetch-retry'

//Wir geben bis zu 10 Wiederholungsversuche an, mit einer Verzögerung von 1 Sekunde zwischen den Wiederholungen.
const retryFetch = fetchRetry.default(fetch, {
  retries: 10,
  retryDelay: 1000
})
const nodeProvider = new NodeProvider('node-url', undefined, retryFetch)

Benutzerdefinierter Wallet-Verbindungsbutton

@alephium/web3-react bietet die AlephiumConnectButton-Komponente zur Erleichterung der Entwicklung von Benutzeroberflächen an. Sie können auch AlephiumConnectButton.Custom verwenden, um den Stil des Verbindungsbuttons anzupassen:

Alephium Wallet Verbindungsbutton
TypeScript
import { AlephiumConnectButton } from '@alephium/web3'

function CustomWalletConnectButton = () => {
  return (
    <AlephiumConnectButton.Custom>
      {({ isConnected, disconnect, show, account }) => {
        return isConnected ? (
          <button onClick={disconnect}>
            Disconnect
          </button>
        ) : (
          <button onClick={show}>
            Connect
          </button>
        )
      }}
    </AlephiumConnectButton.Custom>
  )
}