API changes

Issues with the current API

1. In a normal scenario, app authors have to try / catch the activate() and store the error in the state so that users can be presented a connection error message. This is verbose and takes us farther from the goal of keeping the boilerplate code as minimal as possible useWallet().
2. Passing both the connector identifier and the state, using activating, activated and connected, requires consumers of the library to test several variables to know the current state and the connector identifier.
3. Using a mix of the term “activated” and the term “connected” is confusing. “activated” is coming from EIP 1102, which both defines and deprecates it. Most Ethereum providers use the term “connect” for this (see image below).

Proposed changes

The goal of these changes is generally to:

• Make it possible to use the library by only importing the default export, useWallet().
• Remove the confusion between “connected” and “activated” by only using the term “connect”.
• Keep the boilerplate to a minimum for simple cases.

connect() and disconnect()

connect(id) and disconnect() would replace activate(id) and deactivate(). This is to remove any reference to the term “activation” and increase consistency.

function App() {
  const { account, connect, disconnect } = useWallet()
  return (
    <button onClick={account ? disconnect : connect}>
      {account ? 'Connect' : 'Disconnect'}
    </button>
  )
}

status

status would be a new exported value that would contain the current status of the wallet connection. It would have take one of these values at any given time:

• "disconnected": no wallet connected (default state).
• "connecting": trying to connect to the wallet.
• "connected": connected to the wallet (i.e. the account is available).
• "error": a connection error happened.

These are strings and not symbols so that users don’t have to import many symbols.

These values would get deprecated: activated, activating and connected.

Having a status connected guarantees that account is not null.

function App() {
  const { account, connect, status } = useWallet()

  if (status === 'connecting') {
    return <p>Connecting…</p>
  }

  if (status === 'connected') {
    return <p>Connected as {account}</p>
  }

  // status === 'disconnected' or status === 'error'
  return <button onClick={() => connect('injected')}>Connect</button>
}

error and reset()

error is a new value that contains the error object that comes with an "error" status.

There are different types of errors exported by module:

• UnsupportedChainError
• UnsupportedConnectorError
• RejectedActivationError
• ConnectorConfigError

error would be null when the status is not error, otherwise it would get populated by the corresponding error instance.

Users would have the possibility to import the error constructors and use instanceof, or to use the name property.

The message property can also be used to display the current error.

Calling reset() will make status go back to disconnected, and error back to null. Calling connect() would also clear the error state before initiating the new connection.

function App() {
  const { account, connect, error, reset, status } = useWallet()

  if (status === 'connecting') {
    return <p>Connecting…</p>
  }

  if (status === 'connected') {
    return <p>Connected as {account}</p>
  }

  if (status === 'error') {
    return (
      <div>
        <p>Error: {error.message}.</p>
        <button onClick={() => reset()}>OK</button>
      </div>
    )
  }

  // status === 'disconnected'
  return <button onClick={() => connect('injected')}>Connect</button>
}

@Evalir @sohkai Let me know what you guys think!

[sohkai]

Really nice changes, and agree this will make the API much smoother to use! With reset() available, you can probably drive an entire account connection / disconnection flow via just the exposed state from useWallet() ❤️!

---

So I think we could go for reset() and deprecate disconnect(). What do you think?

I agree with this; I presume this would also clear any localstorage cache about the last connected wallet / etc (which is also what we would want to do on disconnect anyway).

There are different types of errors exported by module:

A bit of bikeshedding on the error naming (assuming we get to choose these names):

UnsupportedChainError => ChainUnsupportedError
UnsupportedConnectorError => ConnectorUnsupportedError
RejectedActivationError => ConnectionRejectedError
ConnectorConfigError => ConnectorConfigError

[Evalir]

Haha! It’s not that I changed my mind much, it’s just that maybe we can make those two functions coexist, but we may need a better name for reset (naming is hard!).

Regarding disconnect(), I actually didn’t feel so weird about clearing errors; for me when you disconnect, it feels like the library doesn’t know about your “wallet” anymore; it just doesn’t have a reason to hold onto information. However, using disconnect() for just clearing errors is not something ideal 😅, in that case, I really think reset(), properly explained and renamed, makes sense.