npm package: @roninnetwork/walletgo
Description: Walletgo is the simplest way to integrate Ronin into your web application by connecting a user's wallet to your DApp.
Latest version: 0.5.13
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Ronin Walletgo

Walletgo is the simplest way to integrate Ronin into your web application by connecting a user's wallet to your DApp.

## Features

- 💡 Any Wallet — Connect any wallet (Ronin, Ronin Mobile, Metamask, Gnosis, ...) to your app.
- 🌱 Simple, seamless UI/UX — simple UX with attractive UI.
- 🎨 Theme — Predesigned theme or full customization.

## Before you start

Before you install the SDK, make sure you have the following:

- [Node.js](https://nodejs.org/en) version 16.17.0 or later.
- [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/) for package installation.
- A JavaScript project. To create a new project, you can use [create-react-app](https://create-react-app.dev/docs/getting-started/) or [create-next-app](https://nextjs.org/docs/pages/api-reference/create-next-app). This guide uses a Next.js application.

## Install

From you project directory, install the SDK using yarn or npm:

```sh
$ npm install @roninnetwork/walletgo
```

```sh
$ yarn add @roninnetwork/walletgo
```

## API Key

Ronin Wallet uses WalletConnect's SDK for connecting wallets.
Head over [WalletConnect Cloud](https://cloud.walletconnect.com.) to obtain your `projectID`.

## Basic usage

1. Wrap your App with `WalletgoProvider`.

```jsx
// App.jsx
import { WalletgoProvider } from "@roninnetwork/walletgo"
import App, { AppContext, AppProps } from "next/app"

const App = (props: AppProps) => {
  const { Component, pageProps } = props

  return (
    <WalletgoProvider defaultChainId={2020}>
      <Component {...pageProps} />
    </WalletgoProvider>
  )
}
```

2. Create needed wallet connectors - Ronin, Ronin Mobile, Metamask, Gnosis.

```js
// connectors.js
import { createDefaultWallets } from "@roninnetwork/walletgo"
const WC_PROJECT_ID = "YOUR_WALLETCONNECT_PROJECT_ID"

const connectors = createDefaultWallets({
  projectId: WC_PROJECT_ID,
  clientMeta: {
    name: "App Name",
    description: "App description",
    icons: ["https://cdn.skymavis.com/explorer-cdn/asset/favicon/apple-touch-icon.png"],
    url: "https://app.roninchain.com",
  },
})
```

3. Include Connect Wallet dialog in your App

```jsx
// MyComponent.tsx
import { createDefaultWallets, WalletWidget } from "@roninnetwork/walletgo"

const WC_PROJECT_ID = "YOUR_WALLETCONNECT_PROJECT_ID"

const connectors = createDefaultWallets({
  projectId: WC_PROJECT_ID,
  clientMeta: {
    name: "App Name",
    description: "App description",
    icons: ["https://cdn.skymavis.com/explorer-cdn/asset/favicon/apple-touch-icon.png"],
    url: "https://app.roninchain.com",
  },
})

export const MyComponent = () => {
  const [showWidget, setShowWidget] = useState(false)

  return (
    <div>
      <WalletWidget
        isOpen={showWidget}
        handleClose={() => setShowWidget(false)}
        wallets={connectors}
      />
      <button onClick={() => setShowWidget(true)}>Open Widget</button>
    </div>
  )
}
```

4. Get wallet infomation in your App

```jsx
// Address.tsx
import { useWalletgo } from "@roninnetwork/walletgo"

export const Address = () => {
  const { account, walletChainId, walletProvider, deactivate } = useWalletgo()

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

And that's it — just simple as that! Now, you have your app ready to connect to Ronin!

## Example

Source: [github.com/8ailurus/walletgo-demo-nextjs](https://github.com/8ailurus/walletgo-demo-nextjs)
Live demo : [walletgo-demo-nextjs.vercel.app](https://walletgo-demo-nextjs.vercel.app/)

## Customization

### Theme

Walletgo exposes a few basic CSS variables to help quickly restyle the default UI.

| variable                       | description                            | default                   |
| ------------------------------ | -------------------------------------- | ------------------------- |
| --wg-wallet-btn-font-size      | Connect button font size               | 16px                      |
| --wg-wallet-btn-radius         | Connect button border radius           | 12px                      |
| --wg-wallet-btn-color          | Connect button text color              | #e2e4e9                   |
| --wg-wallet-btn-bg             | Connect button background              | rgba(147, 176, 236, 0.1)  |
| --wg-wallet-btn-sd             | Connect button box shadow              | none                      |
| --wg-wallet-btn-hover-color    | Connect button text color on hover     | #e2e4e9                   |
| --wg-wallet-btn-hover-bg       | Connect button background on hover     | #93b0ec0d                 |
| --wg-wallet-btn-hover-sd       | Connect button box shadow on hover     | 0px 0px 1px #2b2f3b       |
| --wg-btn-radius                | Common button border radius            | 8px                       |
| --wg-primary-btn-color         | Primary button text color              | #fff                      |
| --wg-primary-btn-bg            | Primary button background              | #2662d9                   |
| --wg-primary-btn-sd            | Primary button box shadow              | none                      |
| --wg-primary-btn-hover-color   | Primary button text color on hover     | #fff                      |
| --wg-primary-btn-hover-bg      | Primary button background on hover     | #173b82                   |
| --wg-primary-btn-hover-sd      | Primary button box shadow on hover     | none                      |
| --wg-secondary-btn-color       | Secondary button text color            | #c4c8d4                   |
| --wg-secondary-btn-bg          | Secondary button background            | rgba(147, 176, 236, 0.1)  |
| --wg-secondary-btn-sd          | Secondary button box shadow            | none                      |
| --wg-secondary-btn-hover-color | Secondary button font color on hover   | #c4c8d4                   |
| --wg-secondary-btn-hover-bg    | Secondary button background on hover   | rgba(147, 176, 236, 0.05) |
| --wg-secondary-btn-hover-sd    | Secondary button box shadow on hover   | none                      |
| --wg-overlay-bg                | Dialog overlay color                   | rgba(12, 12, 13, 0.8)     |
| --wg-overlay-backdrop-filter   | Backdrop filter for the Dialog overlay | unset                     |
| --wg-z-overlay                 | z-index of Dialog overlay              | unset                     |
| --wg-dialog-bg                 | Dialog background color                | #1a1c23                   |
| --wg-dialog-sd                 | Dialog box shadow                      | 0px 0px 1px #2b2f3b       |
| --wg-dialog-radius             | Dialog border radius                   | 20px                      |
| --wg-z-dialog                  | z-index of Dialog                      | unset                     |
| --wg-body-font-size            | Body text font size                    | 16px                      |
| --wg-sheading-font-size        | Subheading text font size              | 18px                      |
| --wg-heading-font-size         | Dialog title text font size            | 20px                      |
| --wg-font-family               | Text font                              | unset                     |
| --wg-color                     | Text color                             | #fff                      |
| --wg-color-dim                 | Dim text color                         | #6c7693                   |
| --wg-color-dim-hover           | Dim text color on hover                | #c4c8d4                   |
| --wg-color-critical            | Critical text color                    | #ff401a                   |
| --wg-color-success             | Success text color                     | #11d473                   |
| --wg-qr-dot-color              | Color of dots in QR                    | #111417                   |
| --wg-qr-sd                     | QR box shadow                          | unset                     |
| --wg-qr-radius                 | QR border radius                       | 20px                      |
| --wg-qr-bg                     | QR background color                    | #fff                      |
| --wg-focus-sd                  | Focused element box shadow             | 0px 0px 1px #2662d9       |
| --wg-spinner-color             | Spinner color                          | #e2e4e9                   |

### UI

Comming soon!

### Connectors

Comming soon!

### Multi Context

Comming soon!

## Props Table & Type

### WalletgoProvider

| prop name      | type                                   | required | default                  | description                                                                                                                      |
| -------------- | -------------------------------------- | -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| children       | `React.ReactNode`                      | optional | `undefined`              | Your application component                                                                                                       |
| defaultChainId | `number`                               | required |                          | Default chainId is used for `etherjs` provider                                                                                   |
| config         | `Record<number, IChainInfo>`           | optional | `DEFAULT_CHAINS_CONFIG`  | Chains configuration                                                                                                             |
| walletOriented | `boolean`                              | optional | `false`                  | Determine walletgo to create `readProvider` base on walletChainId. By default, `readProvider` is always respect `defaultChainId` |
| context        | `React.Context<IWalletgoContextValue>` | optional | `DefaultWalletgoContext` | Custom React.Context for Provider to get                                                                                         |

```ts
interface IChainInfo {
  chainId: number
  blockExplorerUrl?: string
  chainName?: string
  iconUrl?: string
  nativeCurrency?: {
    name: string
    symbol: string
    decimals: number
  }
  rpcUrl?: string
}

const DEFAULT_CHAINS_CONFIG: IChainsConfig = {
  [SupportedChainIds.RoninMainet]: {
    chainId: SupportedChainIds.RoninMainet,
    blockExplorerUrl: "https://app.roninchain.com",
    chainName: "Ronin Mainnet",
    iconUrl: "https://cdn.skymavis.com/explorer-cdn/asset/favicon/apple-touch-icon.png",
    nativeCurrency: {
      name: "Ronin",
      symbol: "RON",
      decimals: 18,
    },
    rpcUrl: DEFAULT_RPC_CONFIG[SupportedChainIds.RoninMainet],
  },
  [SupportedChainIds.RoninTestnet]: {
    chainId: SupportedChainIds.RoninTestnet,
    blockExplorerUrl: "https://saigon-app.roninchain.com",
    chainName: "Saigon Testnet",
    iconUrl: "https://cdn.skymavis.com/explorer-cdn/asset/favicon/apple-touch-icon.png",
    nativeCurrency: {
      name: "tRonin",
      symbol: "tRON",
      decimals: 18,
    },
    rpcUrl: DEFAULT_RPC_CONFIG[SupportedChainIds.RoninTestnet],
  },
  [SupportedChainIds.Ethereum]: {
    chainId: SupportedChainIds.Ethereum,
    blockExplorerUrl: "https://etherscan.io",
    chainName: "Ethereum",
    nativeCurrency: {
      name: "Ethereum",
      symbol: "ETH",
      decimals: 18,
    },
  },
  [SupportedChainIds.Goerli]: {
    chainId: SupportedChainIds.Goerli,
    blockExplorerUrl: "https://goerli.etherscan.io/",
    chainName: "Goerli",
    nativeCurrency: {
      name: "GoerliETH",
      symbol: "GTH",
      decimals: 18,
    },
  },
}
```

### WalletWidget

| prop name     | type                                   | required | default                                                            | description                                                                                                    |
| ------------- | -------------------------------------- | -------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| wallets       | `IConnector[]`                         | required |                                                                    | List of wallet connectors is show on Widget                                                                    |
| isOpen        | `boolean`                              | required |                                                                    | Whether the Connect Wallet dialog is visible or not                                                            |
| onClose       | `() => void`                           | optional | `noop`                                                             | Specify a function that will be called when a user clicks mask, close button on top right or disconnect button |
| onOpen        | `() => void`                           | optional | `noop`                                                             | Specify a function that will be called when a Dialog open                                                      |
| dialogProps   | `IDialogCustomProps`                   | optional | `{   mask: true,   maskClosable: true,   destroyOnClose: false, }` | Custom Dialog props `rc-dialog`                                                                                |
| customContext | `React.Context<IWalletgoContextValue>` | optional | `DefaultWalletgoContext`                                           | Custom React.Context for Widget to get state                                                                   |

### useWalletgo

| name              | type                                                            | undefinable | default                 | description                                                                               |
| ----------------- | --------------------------------------------------------------- | ----------- | ----------------------- | ----------------------------------------------------------------------------------------- |
| activate          | `(connector: IConnector, isAuto?: boolean) => Promise<boolean>` | false       | `noop`                  | Use to establish connection to wallet                                                     |
| autoActivate      | `(connectors: IConnector[]) => Promise<boolean>`                | false       | `noop`                  | Use to establish connection to many wallets - for reconnect when reload page              |
| deactivate        | `() => void`                                                    | false       | `noop`                  | Use to disconnect from current wallet                                                     |
| unsafeSwitchChain | `(chainId: number) => Promise<boolean>`                         | false       | `noop`                  | Use to switch chainId on connected wallet                                                 |
| error             | `ConnectorError`                                                | true        | `undefined`             |                                                                                           |
| activating        | `boolean`                                                       | false       | `false`                 | Custom React.Context for Widget to get state                                              |
| account           | `string`                                                        | true        | `undefined`             | Connected address                                                                         |
| connected         | `boolean`                                                       | false       | `false`                 | Whether connected to wallet or not                                                        |
|                   |                                                                 |             |                         |                                                                                           |
| connector         | `IConnector`                                                    | true        | `undefined`             | Current wallet connector                                                                  |
| readProvider      | `StaticJsonRpcProvider`                                         | true        | `undefined`             | `static rpc` provider - direct call to RPC                                                |
| walletProvider    | `Web3Provider`                                                  | true        | `undefined`             | `etherjs` providers - direct call to injected provider - should use when sign tx, message |
| walletChainId     | `number`                                                        | true        | `undefined`             | Current wallet chainId, `undefined` if wallet is not connected                            |
|                   |                                                                 |             |                         |                                                                                           |
| chainConfig       | `Record<number, IChainInfo>`                                    | false       | `DEFAULT_CHAINS_CONFIG` | Users config                                                                              |
| defaultChainId    | `number`                                                        | false       | `2020`                  | Users config                                                                              |
| walletOriented    | `boolean`                                                       | false       | `false`                 | Users config                                                                              |

### Connector

```ts
interface IConnector<ProviderType = ExternalProvider> {
  readonly id: string
  readonly switchable: boolean
  readonly scannable: boolean

  readonly provider?: ProviderType
  readonly events: IConnectorEventEmitter

  readonly autoPriority: number
  shouldAutoConnect(): Promise<boolean>

  connect(chainId: number): Promise<IConnectResult<ProviderType>>
  disconnect(): Promise<boolean>

  switchChain(chain: IAddEthereumChainParameter): Promise<boolean>

  // NOTE: only use for UI Widget
  readonly name: ReactNode
  readonly logo: ReactNode
  readonly downloadUrls: { [key: string]: string }
  readonly hidden: boolean
}
```