naxios

Promesse basée sur le contrat, près du portefeuille et près du client RPC pour le navigateur. Ceci a été conçu pour faciliter l'intégration de la réaction avec la proximité de la blockchain et éviter l'énorme passe-partout de la mise en place d'un portefeuille et d'un contrat.

Documentation

Table des matières

• Caractéristiques
• Installation
• Comment utiliser
• Utils
• Contributif

Caractéristiques

• Intégration de portefeuille et de contrat simplifiés
• Soutient l'API Promise
• Facile à créer une interface de contrat
• Connexion du portefeuille modal à utiliser facilement
• Transformes automatiques pour les données JSON
• Événements côté client pour dire quand l'API est prête
• Crochets de réaction utiles
• Système de cache pour view du contrat

Installation

Utilisation de NPM:

 # You can use any wallet selector version you want
npm install @wpdas/naxios @near-wallet-selector/[email protected]

Utilisation du fil:

 # You can use any wallet selector version you want
yarn add @wpdas/naxios @near-wallet-selector/[email protected]

Comment utiliser

Le préparer

Importez les styles de sélecteur de portefeuille près. L'application en a besoin pour rendre correctement le sélecteur de portefeuille.

 import '@near-wallet-selector/modal-ui/styles.css'

L'utiliser

Il est super facile d'obtenir une API de portefeuille et / ou de contrat en une seule fois. Jetez un œil:

 // web3Api.ts
import naxios from '@wpdas/naxios'

const naxiosInstance = new naxios ( {
  rpcNodeUrl : 'https://free.rpc.fastnear.com' , // optional
  contractId : CONTRACT_ID ,
  network : 'testnet' ,
} )

/**
 * NEAR Wallet API (Must be a single instance)
 */
export const walletApi = naxiosInstance . walletApi ( )

// Examples of contract API instance usage

/**
 * Contract API
 * This is going to use default contractId (CONTRACT_ID)
 */
export const contractApi = naxiosInstance . contractApi ( )

/**
 * Another Contract API
 */
export const socialDBcontractApi = naxiosInstance . contractApi ( { contractId : 'v1.social08.testnet' } )

/**
 * Greeting Contract API
 */
export const greetingContractApi = naxiosInstance . contractApi ( {
  contractId : 'dev-1692221685438-15421910364142' ,
} )

/**
 * NEAR RPC API
 */
export const rpcApi = naxiosInstance . rpcApi ( ) 

Ouverture du sélecteur de portefeuille de connexion modal

Vous pouvez ouvrir le modal du sélecteur de portefeuille proche en appelant signInModal() :

 import { walletApi } from './web3Api'

walletApi . signInModal ( ) 

Personnalisation des options de portefeuilles pour le sélecteur de portefeuille proche

Par défaut, Naxios utilise uniquement @ Wallet-Selector / My-Near-Wallet comme moyen de connecter le portefeuille. Cependant, vous pouvez ajouter d'autres sélecteurs de portefeuille comme suit:

npm install @near-wallet-selector/ledger @near-wallet-selector/my-near-wallet

Ensuite, vous pouvez démarrer Naxius comme suit:

 import naxios from '@wpdas/naxios'
import { setupMyNearWallet } from '@near-wallet-selector/my-near-wallet'
import { setupLedger } from '@near-wallet-selector/ledger'

const naxiosInstance = new naxios ( {
  contractId : CONTRACT_ID ,
  network : 'testnet' , // or mainnet, localnet
  walletSelectorModules : [ setupMyNearWallet ( ) , setupLedger ( ) ] ,
} )

/**
 * NEAR Wallet API (Must be a single instance)
 */
export const walletApi = naxiosInstance . walletApi ( )

Découvrez tous les sélecteurs de portefeuille près ici: Selecteur de portefeuille près

Référence de l'API contractuelle

• view : effectuez un appel en lecture seule pour récupérer des informations du réseau. Il a les paramètres suivants:
  • method : Nom de la méthode du contrat.
  • props? : un paramètre facultatif avec args pour la méthode du contrat.
  • config? : Actuellement, cela n'a que le useCache . Lorsque UseCache est vraie, cela va utiliser des données mises en cache non expirées au lieu d'appeler la méthode du contrat.
• call : appelez une méthode qui modifie l'état du contrat. Ceci est payable. Il a les paramètres suivants:
  • method : Nom de la méthode du contrat
  • props? : Un paramètre facultatif avec args pour la méthode du contrat, gas , deposit à attacher et callbackUrl si vous souhaitez amener l'utilisateur à une page spécifique après qu'une transaction réussit.
• callMultiple : appelez plusieurs méthodes qui modifient l'état du contrat. Ceci est payable et a les paramètres suivants:
  • transactionsList : une liste d'accessoires de transaction. Vous pouvez utiliser buildTransaction(...) pour vous aider
  • callbackUrl? : Une page pour emmener l'utilisateur après que toutes les transactions réussissent.

Référence de l'API du portefeuille

• accounts : Comptes connectés.
• accountId : ID de compte principal / concouvert de premier dans la liste des comptes.
• contractId : Contrat Id.
• initNear : initialise une connexion à la blockchain proche. C'est ce qu'on appelle automatiquement lorsqu'il y a une interaction contractuelle.
• network : réseau actuel ( testnet , mainnet ou localnet ).
• recentlySignedInWallets : Returns ID-S de 5 récemment signé dans des portefeuilles.
• selectedWalletId : ID de portefeuille sélectionné
• signInModal : Ouvrez le portefeuille Signin Modal.
• wallet : instance de portefeuille.
• walletSelector : WalletSelector Instance.

Vue de contrat

L'utilisation d'une méthode view est gratuite.

 import { greetingContractApi } from './web3Api'

// [free]
greetingContractApi . view < string > ( 'get_greeting' ) . then ( ( response ) => console . log ( response ) )

Appel de contrat

Vous devez payer pour chaque demande que vous faites pour une méthode call . Cela va changer de données et les stocker dans la blockchain.

 import { greetingContractApi } from './web3Api'

// Set greeting [payable]
const args : { message : 'Hi there!!!' }
greetingContractApi . call < string | undefined > ( 'set_greeting' , args ) . then ( ( response ) => console . log ( response || 'done!' ) )

Contracter plusieurs appels à la fois

En plus de l' call , vous devrez payer pour chaque demande que vous faites. Cela va changer de données et les stocker dans la blockchain.

 import { buildTransaction } from '@wpdas/naxios'
import { contractApi } from './web3Api'

// Using the default instance's contract
const transactionA = buildTransaction ( 'set_greeting' , { args : { greeting : 'Hello my dear!' } } )
const transactionB = buildTransaction ( 'set_age' , { args : { age : 22 } } )
// Using diff contract
const transactionC = buildTransaction ( 'update_state' , {
  receiverId : 'my-state-contract.testnet' ,
  args : { allowed : true } ,
} )

// Optional
const callbackUrl = 'https://my-page.com/callback-success'

// [payable]
contractApi . callMultiple ( [ transactionA , transactionB , transactionC ] , callbackUrl ) . then ( ( ) => console . log ( 'Done!' ) )

Système de cache

Il existe deux types de systèmes de cache à utiliser. Ce sont Memory Cache et Storage Cache .

Memory Cache : sera effacée lorsque l'application actualisera, car ses données ne vivent qu'en mémoire.
Storage Cache : les données resteront même lorsque l'onglet du navigateur est actualisé. Les données sont persistées à l'aide du stockage local.

Lorsque vous instanciez un cache, vous devez fournir le expirationTime (en secondes). Ceci est utilisé pour savoir quand le cache doit être retourné au lieu de passer un véritable appel de contrat. Lorsque le cache expire, un véritable appel au contrat est effectué. La méthode de chaque contrat a son propre temps d'expiration.

 // web3Api.ts
import naxios , { StorageCache } from '@wpdas/naxios'

// ...

/**
 * Cached - Greeting Contract API
 */
export const cachedGreetingContractApi = naxiosInstance . contractApi ( {
  contractId : 'dev-1692221685438-15421910364142' ,
  cache : new StorageCache ( { expirationTime : 5 * 60 } ) , // 5 minutes
} )

Ensuite, pour utiliser view mise en cache, vous pouvez simplement passer l'objet de configuration en disant que vous souhaitez utiliser des données mises en cache.

 import { cachedGreetingContractApi } from './web3Api'

// Fetch Greetings [free]
const args : { }
const config : { useCache : true }
cachedGreetingContractApi . view < string > ( 'get_greeting' , args , config ) . then ( ( response ) => console . log ( response ) )

API près de RPC

Naxios donne également accès à l'API proche RPC, afin que vous puissiez interroger toutes les données que vous souhaitez. Visitez près des documents API RPC pour apprendre à l'utiliser.

 import { rpcApi } from './web3Api'

// Viewing account using Near RPC API
rpcApi
  . query ( {
    request_type : 'view_account' ,
    finality : 'final' ,
    account_id : 'wendersonpires.near' ,
  } )
  . then ( ( data ) => console . log ( 'Account Data:' , data ) ) 

Utils

buildTransaction

La méthode buildTransaction est utile lorsque vous devez créer un corps de transaction d'un contrat, principalement lorsque vous souhaitez passer plusieurs appels de contrat .

Voir référence ici.

validateNearAddress

Ceci est utilisé pour vérifier si une adresse est une adresse proche valide.

 import { validateNearAddress } from '@wpdas/naxios'

console . log ( validateNearAddress ( 'fake.near' ) ) // true
console . log ( validateNearAddress ( 'fake.nears' ) ) // false
console . log ( validateNearAddress ( 'fake.testnet' ) ) // true
console . log ( validateNearAddress ( 'fake' ) ) // false 

calculateDepositByDataSize

Calculer le dépôt requis pour les données stockées. (~ 0,00001N par octet) avec un peu plus pour le tampon

 import { calculateDepositByDataSize } from '@wpdas/naxios'

const myData = { age : 22 , name : 'user name' }
console . log ( calculateDepositByDataSize ( myData ) ) // 0.00087 Near (not yocto NEAR) 

isClient

Vérificateur simple pour dire si cela s'exécute sur le serveur ou le client.

 import { isClient } from '@wpdas/naxios'

if ( isClient ( ) ) {
  console . log ( 'Hi from client' )
} else {
  console . log ( 'Hi from server' )
} 

Contributif

N'hésitez pas à ouvrir des problèmes ou à extraire les demandes. Pour les changements majeurs, veuillez d'abord ouvrir un problème pour discuter de ce que vous souhaitez changer.