naxios

Promessa baseada em contrato, perto da carteira, e perto do cliente do RPC para navegador. Isso foi projetado para facilitar a integração do React com o blockchain próximo e evitar o enorme caldeira de montar uma carteira e contrato.

Documentação

Índice

• Características
• Instalação
• Como usar
• UTILS
• Contribuindo

Características

• Carteira simplificada e integração contratada
• Suporta a API da promessa
• Fácil de criar uma interface de contrato
• Conexão da carteira modal a ser facilmente usado
• Transformações automáticas para dados JSON
• Eventos do lado do cliente para saber quando a API está pronta
• Ganchos reativos úteis
• Sistema de cache para view de contrato

Instalação

Usando NPM:

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

Usando o fio:

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

Como usar

Preparando isso

Importe os estilos de seletor de carteira próxima. O aplicativo precisa renderizar o seletor de carteira corretamente.

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

Usando isso

É super fácil obter uma carteira e/ou contrato de API no lugar de uma só vez. Dê uma olhada:

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

Abrindo o modal de seletor de carteira de assinatura

Você pode abrir o modal do seletor de carteira próximo chamando signInModal() :

 import { walletApi } from './web3Api'

walletApi . signInModal ( ) 

Personalizando as opções de carteiras para seletor de carteira próximo

Por padrão, o Naxios usa apenas @paralel-seletor/mecânia como um meio de conectar a carteira. No entanto, você pode adicionar outros seletores de carteira da seguinte forma:

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

Então, você pode iniciar o Naxius da seguinte maneira:

 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 os seletores próximos da carteira aqui: seletor de carteira próximo

Referência da API do contrato

• view : faça uma chamada somente leitura para recuperar informações da rede. Tem os seguintes parâmetros:
  • method : nome do método do contrato.
  • props? : Um parâmetro opcional com args para o método do contrato.
  • config? : Atualmente, isso possui apenas o suporte useCache . Quando o USECACHACH é verdadeiro, isso usará dados em cache não expirados, em vez de chamar o método do contrato.
• call : ligue para um método que altere o estado do contrato. Isso é pago. Tem os seguintes parâmetros:
  • method : nome do método do contrato
  • props? : Um parâmetro opcional com args para o método, gas , deposit do contrato a ser anexado e callbackUrl se você deseja levar o usuário a uma página específica após o sucesso de uma transação.
• callMultiple : Chame vários métodos que alteram o estado do contrato. Isso é pago e tem os seguintes parâmetros:
  • transactionsList : uma lista de adereços de transação. Você pode usar buildTransaction(...) para ajudá -lo
  • callbackUrl? : Uma página para levar o usuário para depois que todas as transações são bem -sucedidas.

Referência da API da carteira

• accounts : Contas assinadas.
• accountId : ID da conta principal/primeiro assinada na lista de contas.
• contractId : ID do contrato.
• initNear : inicializa uma conexão com o blockchain próximo. Isso é chamado automaticamente quando há uma interação contratada.
• network : Rede atual ( testnet , mainnet ou localnet ).
• recentlySignedInWallets : Retorna ID-S de 5 assinadas recentemente em carteiras.
• selectedWalletId : ID da carteira selecionada
• signInModal : Abra o Modal da carteira de assinatura.
• wallet : instância da carteira.
• walletSelector : Instância do WalletSelector.

Visão do contrato

Usar um método view é gratuito.

 import { greetingContractApi } from './web3Api'

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

Chamada de contrato

Você precisa pagar por todas as solicitações que você faz para um método call . Isso vai alterar dados e armazená -los dentro da 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!' ) )

Contratar várias chamadas de uma só vez

Além da call , você precisará pagar por todas as solicitações que fizer. Isso vai alterar dados e armazená -los dentro da 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!' ) )

Sistema de cache

Existem dois tipos de sistemas de cache a serem usados. Eles são Memory Cache e Storage Cache .

Memory Cache : será limpo quando o aplicativo atualizar, pois seus dados vivem apenas na memória.
Storage Cache : os dados permanecerão mesmo quando a guia do navegador estiver atualizada. Os dados são persistidos usando o armazenamento local.

Ao instantar um cache, você precisa fornecer o expirationTime (em segundos). Isso é usado para saber quando o cache deve ser devolvido em vez de fazer uma chamada de contrato real. Quando o cache expira, uma chamada real para o contrato é feita. O método de cada contrato tem seu próprio tempo de expiração.

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

Em seguida, para usar view em cache, você pode simplesmente passar no objeto de configuração dizendo que deseja usar dados em 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 ) )

Perto da API RPC

O NAXIOS também fornece acesso à API RPC próxima, para que você possa consultar os dados desejados. Visite os documentos da API perto da RPC para aprender a usá -lo.

 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

O método buildTransaction é útil quando você precisa criar o órgão de transação de um contrato, principalmente quando você deseja fazer várias chamadas de contrato .

Veja referência aqui.

validateNearAddress

Isso é usado para verificar se um endereço é um endereço próximo válido.

 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 o depósito necessário para os dados que estão sendo armazenados. (~ 0,00001n por byte) com um pouco extra de 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 simples para dizer se isso estiver sendo executado no servidor ou cliente.

 import { isClient } from '@wpdas/naxios'

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

Contribuindo

Sinta -se à vontade para abrir problemas ou puxar solicitações. Para grandes mudanças, abra um problema primeiro para discutir o que você gostaria de mudar.