naxios

Promesa basada en el contrato, cerca de la billetera y un cliente RPC para el navegador. Esto fue diseñado para facilitar la integración React con una cadena de bloques cercana y evitar la enorme caldera de establecer una billetera y contrato.

Documentación

Tabla de contenido

• Características
• Instalación
• Cómo usar
• Tensiones
• Que contribuye

Características

• Integración de billetera e contrato simplificada
• Apoya la API de la promesa
• Fácil de crear una interfaz de contrato
• Modal de conexión de billetera
• Transformaciones automáticas para datos JSON
• Eventos del lado del cliente para saber cuándo la API está lista
• Hooks react útiles
• Sistema de caché para view de contrato

Instalación

Usando NPM:

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

Usando hilo:

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

Cómo usar

Preparándolo

Importar los estilos de selección de billetera cercana. La aplicación lo necesita para representar el selector de billetera correctamente.

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

Usándolo

Es muy fácil obtener una billetera y/o una API de contrato en su lugar a la vez. Echa un vistazo:

 // 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 ( ) 

Abrir el selector de billetera de inicio de sesión modal

Puede abrir el modal del selector de billetera cercano llamando signInModal() :

 import { walletApi } from './web3Api'

walletApi . signInModal ( ) 

Personalización de las opciones de billeteras para el selector de billeteras cercanas

Por defecto, Naxios solo usa @Near Wallet-Selector/My-Near Wallet como un medio para conectar la billetera. Sin embargo, puede agregar otros selectores de billetera de la siguiente manera:

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

Entonces, puede comenzar a Naxius de la siguiente manera:

 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 ( )

Descubra todos los selectores de billetera cercano aquí: Selector de billetera cercano

Referencia de API de contrato

• view : haga una llamada de solo lectura para recuperar información de la red. Tiene los siguientes parámetros:
  • method : nombre del método del contrato.
  • props? : Un parámetro opcional con args para el método del contrato.
  • config? : Actualmente, esto solo tiene el accesorio useCache . Cuando useCache es cierto, esto usará datos en caché no expulsados ​​en lugar de llamar al método del contrato.
• call : Llame a un método que cambie el estado del contrato. Esto se paga. Tiene los siguientes parámetros:
  • method : nombre del método del contrato
  • props? : Un parámetro opcional con args para el método del contrato, gas , deposit que se adjuntará y callbackUrl si desea llevar al usuario a una página específica después de que una transacción tenga éxito.
• callMultiple : llame a múltiples métodos que cambien el estado del contrato. Esto se paga y tiene los siguientes parámetros:
  • transactionsList : una lista de accesorios de transacciones. Puedes usar buildTransaction(...) para ayudarte
  • callbackUrl? : Una página para llevar al usuario a después de todas las transacciones triunfan.

Referencia de la API de billetera

• accounts : Cuentas firmadas.
• accountId : ID de cuenta principal/Primera firmada en la lista de cuentas.
• contractId : ID de contrato.
• initNear : inicializa una conexión con la cadena de bloques cercana. Esto se llama automáticamente cuando hay alguna interacción por contrato.
• network : Red actual ( testnet , mainnet o localnet ).
• recentlySignedInWallets : devuelve ID-S de 5 recientemente firmado en billeteras.
• selectedWalletId : ID de billetera seleccionada
• signInModal : Abra el modal de la billetera Signin.
• wallet : instancia de billetera.
• walletSelector : instancia de WalletSelector.

Vista de contrato

Usar un método view es gratuito.

 import { greetingContractApi } from './web3Api'

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

Llamada de contrato

Debe pagar cada solicitud que realice un método call . Esto cambiará los datos y los almacenará dentro de la cadena de bloques.

 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!' ) )

Contrata a múltiples llamadas a la vez

Además de la call , deberá pagar cada solicitud que realice. Esto cambiará los datos y los almacenará dentro de la cadena de bloques.

 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!' ) )

Sistema de caché

Hay dos tipos de sistemas de caché para utilizar. Son Memory Cache y Storage Cache .

Memory Cache : se borrará cuando la aplicación se actualice, ya que sus datos viven solo en la memoria.
Storage Cache : los datos permanecerán incluso cuando se actualice la pestaña del navegador. Los datos se persisten utilizando el almacenamiento local.

Al instancias de un caché, debe proporcionar el expirationTime (en segundos). Esto se usa para saber cuándo se debe devolver el caché en lugar de hacer una llamada de contrato real. Cuando el caché expira, se realiza una llamada real al contrato. El método de cada contrato tiene su propio tiempo de vencimiento.

 // 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
} )

Luego, para usar view en caché, puede pasar el objeto de configuración diciendo que desea usar datos en caché.

 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 ) )

Cerca de la API RPC

Naxios también proporciona acceso a la API RPC cercana, para que pueda consultar cualquier dato que desee. Visite cerca de RPC API Docs para aprender a usarlo.

 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 ) ) 

Tensiones

buildTransaction

El método buildTransaction es útil cuando necesita construir el cuerpo de transacciones de un contrato, principalmente cuando desea realizar múltiples llamadas de contrato .

Ver referencia aquí.

validateNearAddress

Esto se utiliza para verificar si una dirección es una dirección cercana válida.

 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

Calcule el depósito requerido para los datos que se almacenan. (~ 0.00001n por byte) con un poco más para buffer

 import { calculateDepositByDataSize } from '@wpdas/naxios'

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

isClient

Verificador simple para decir si esto se ejecuta en el servidor o el cliente.

 import { isClient } from '@wpdas/naxios'

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

Que contribuye

No dude en abrir problemas o extraer solicitudes. Para cambios importantes, abra primero un problema para discutir lo que le gustaría cambiar.