JSPM – @wpdas/naxios@1.1.0

Package Exports

@wpdas/naxios
@wpdas/naxios/dist/cjs/index.js
@wpdas/naxios/dist/esm/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@wpdas/naxios) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Promise based NEAR Contract and NEAR Wallet client for browser. This was designed to facilitate the React integration with NEAR Blockchain and avoid the huge boilerplate of setting up a wallet and contract.

Documentation

Features
Installing
How to Use
React Hooks
Contributing

Features

Simplified Wallet and Contract integration
Supports the Promise API
Easy to create a Contract Interface
Wallet connection modal to be easily used
Automatic transforms for JSON data
Client side events to tell when the api is ready
Helpful react hooks

Installing

Using npm:

npm install @wpdas/naxios @near-wallet-selector/modal-ui@8.9.1

Using yarn:

yarn add @wpdas/naxios @near-wallet-selector/modal-ui@8.9.1

How to Use

Preparing it

Import the NEAR Wallet Selector styles. The app needs it to render the Wallet Selector correctly.

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

Using It

It's super easy to get a Wallet and/or Contract API in place all at once. Take a look:

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

const naxiosApi = new naxios({
  contractId: CONTRACT_ID,
  network: 'testnet', // or mainnet, localnet
})

// (optional)
const onContractInitHandler = () => {
  console.log('Contract is ready!')
}
const onWalletInitHandler = () => {
  console.log('Wallet is ready!')
}

/**
 * NEAR Contract API
 */
export const contractApi = naxiosInstance.contractApi(onContractInitHandler)

/**
 * NEAR Wallet API
 */
export const walletApi = naxiosInstance.walletApi(onWalletInitHandler)

Or you can invoke them anytime:

// Invoking a Contract API
import { getContractApi } from '@wpdas/naxios'

// New contract instance
const contract = await getContractApi({
  contractId: ANOTHER_CONTRACT_ID,
  network: 'testnet',
})

const response = await contract.view('get_users', {
  args: { limit: 5 },
})

// Invoking a Wallet API
import { getWalletApi } from '@wpdas/naxios'

// New wallet instance
const walletApi = await getWalletApi({
  contractId: ANOTHER_CONTRACT_ID,
  network: 'testnet',
})

// Open up the Signin Wallet Modal
walletApi.signInModal()

Contract API Reference

view: Make a read-only call to retrieve information from the network.
call: Call a method that changes the contract's state. This is payable.

Wallet API Reference

accounts: Signed-in Accounts.
contractId: Contract ID.
initNear: (This is called automatically. You don't need to call it!) Initializes a connection to the NEAR blockchain.
network: Current network (testnet, mainnet or localnet).
signInModal: Open up the Signin Wallet Modal.
wallet: Wallet instance.
walletSelector: WalletSelector instance.

Contract View

Using a view method is free.

import { contractApi } from './web3Api'

contractApi.view('get_greeting').then((response) => console.log(response))
// Hi

Contract Call

You need to pay for every request you make for a call method. This is going to change data and store it within the blockchain.

import { contractApi } from './web3Api'

// [payable]
contractApi.call('set_greeting', { greeting: 'Hello my dear!' }).then(() => console.log('Done!'))

Contract Interface

It's a good practice to create a Contract Interface while building your app, so that, everyone knows what to input and what to get at the end.

// contract-interface.ts
import { contractApi } from './web3Api'

// Get greeting request
type EmptyInput = {}
type GetGreetingResponse = string
export const get_greeting = () => contractApi.view<EmptyInput, GetGreetingResponse>('get_greeting')

// [payable]
// Set greeting request
type SetGreetingInput = { greeting: string }
type SetGreetingResponse = string // current greeting
export const set_greeting = (args: SetGreetingInput) =>
  contractApi.call<typeof args, SetGreetingResponse>('set_greeting', { args })

Then, you can just call it over your app like:

import { useState, useEffect, useCallback } from 'react'
import { get_greeting, set_greeting } from './contract-interface'

const App = () => {
  const [greeting, setGreeting] = useState('')

  // Loads the last stored greeting
  useEffect(() => {
    ;(async () => {
      const storedGreeting = await get_greeting()
      setGreeting(storedGreeting)
    })()
  }, [])

  // Persist a new greeting message
  const persistNewGreetingHandler = useCallback(async () => {
    await set_greeting({ greeting: 'Hello my dear!!!' })
    console.log('Done!')
  }, [])

  return (
    <>
      <button onClick={persistNewGreetingHandler}>Save new greeting</button>
    </>
  )
}

You can open up the NEAR Wallet Selector modal by calling signInModal():

import { walletApi } from './web3Api'

walletApi.signInModal()

Customizing the Wallets Options for NEAR Wallet Selector

By default, naxios only uses @near-wallet-selector/my-near-wallet as a means of connecting the wallet. However, you can add other wallet selectors as follows:

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

Then, you can start naxius as follows:

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

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

Find out all the NEAR wallet selectors here: NEAR Wallet Selector

React Hooks

`useContract`

The useContract hook initializes a connection to the NEAR Blockchain and provides access to the contractApi instance.

const contract = useContract({ contractId: CONTRACT_ID, network: 'testnet' })

useEffect(() => {
  if (contract.ready) {
    contract.view('get_greeting').then((response) => console.log(response)) // Hi
  }
}, [contract])

API

ready: boolean indicating whether the contract API is ready.
view: Make a read-only call to retrieve information from the network.
call: Call a method that changes the contract's state. This is payable.

`useWallet`

The useWallet hook initializes a connection to the NEAR Blockchain and provides access to the walletApi instance.

const wallet = useWallet({ contractId: CONTRACT_ID, network: 'testnet' })

useEffect(() => {
  if (wallet.ready) {
    console.log(wallet.walletApi?.accounts)
    // [{accountId: 'user.testnet', publicKey: 'ed25519:aaaaaaaa'}, {...}]
  }
}, [wallet])

API

ready: boolean indicating whether the wallet API is ready.
walletApi: Wallet API. See its API Reference here.

Contributing

Feel free to open issues or pull requests. For major changes, please open an issue first to discuss what you would like to change.

@wpdas/naxios