Adding a useTransactions hook

[nickbytes]

Hi there! We've been using wagmi to build RainbowKit (to be released soon!) at Rainbow. One proposal we'd like to make is for the addition of a useTransactions hook. We'd love feedback from the community on how this might be useful for others besides ourselves and how people think this hook may fit into wagmi.

Motivation

In order to provide the best experience for users, developers need to be able to easily show pending transactions and basic transaction history within their dapps.

Prior Art and API inspiration

useDapp

useDapp has an implementation of useTransactions: https://usedapp-docs.netlify.app/docs/core#usetransactions

useDapps' interface for transactions is the following:

import { TransactionReceipt, TransactionResponse } from '@ethersproject/providers'


export interface StoredTransaction {
  transaction: TransactionResponse
  submittedAt: number
  receipt?: TransactionReceipt
  lastCheckedBlockNumber?: number
  transactionName?: string
  originalTransaction?: TransactionResponse
}

// more things

export type StoredTransactions = {
  [chainID: number]: StoredTransaction[]
}

I think there are some nice advantages to this approach. First, it utilizes Ethers types for TransactionResponse and TransactionReceipt. Ethers is already a dependency of wagmi, so that's great. Secondly, it provides a (minimal) way for dapps to describe transactions through the transactionName property.

Uniswap's interface

uniswap-interface – Uniswap's interface is a better-in-class example of how transactions should be handled by dapps and something we should strive to democratize for the community. Code reference here.

Uniswap uses the following as types for their transactions:

export interface TransactionDetails {
  hash: string
  receipt?: SerializableTransactionReceipt
  lastCheckedBlockNumber?: number
  addedTime: number
  confirmedTime?: number
  from: string
  info: TransactionInfo // Uniswap-specific transaction info
}

export interface TransactionState {
  [chainId: number]: {
    [txHash: string]: TransactionDetails
  }
}

// more

export interface SerializableTransactionReceipt {
  to: string
  from: string
  contractAddress: string
  transactionIndex: number
  blockHash: string
  transactionHash: string
  blockNumber: number
  status?: number
}

Subtle differences between Uniswap and useDapp, but I like that Uniswap's interface allows their developers to customize transactions for their application (TransactionInfo) and I also like the TransactionState data structure where txHash's are used as the key.

If you have any other open source examples, please share.

---

Basic Example

import { useTransactions } from 'wagmi'

const App = () => {
  const [{ data, error, isLoading }, addTransaction] = useTransactions()

  return (
    <div>
      {data && <div>
        {data.transactions.map((transaction) => (
	  <div>
	    {transaction.transactionName}
	  </div>
	  ))
	</div>
        }
      {error && <div>Failed to retrieve transactions</div>}
    </div>
  )
}

Details

• Transactions would be persisted to localstorage
• Transactions would be organized by chain ID
• Developers would be able name or label transactions in a human-readable way
• Developers would have the ability to clear transaction history (i.e. clearTransactions)
• Transactions would not include all historical transactions for a user (i.e. by default, we are not pulling from a full node or remote provider)
• Within wagmi, the useContract hook would need an option (default behavior?) to call addTransaction from the useTransaction hook.

Feedback

What are your thoughts on this? What are good examples of libraries/dapps using transaction history? What else would you like to see?

We're happy to contribute more at Rainbow.

[nickbytes]

Wondering if a mix of the two above interfaces might be best for wagmi:

export interface TransactionState {
  [chainId: number]: {
    [txHash: string]: TransactionDetails
  }
}

export interface TransactionDetails {
  transaction: TransactionResponse
  submittedAt: number
  receipt?: TransactionReceipt
  lastCheckedBlockNumber?: number
  transactionName?: string
  originalTransaction?: TransactionResponse
}

Advantages of this to me are:

• transactions separated by chains
• individual transactions accessible by txHash.
• TransactionDetails stays fairly simple/slim

Thoughts?

Being able to pass a value that would be used as transactionName in useContractWrite feels like it could be interesting. This would be similar to how transactionName is an option for useContractFunction in useDapp. This way, wagmi would not have to worry about decoding transaction types from an infinite amount of contract functionalities.

Here's an example of how this might work within useContractWrite if added to the configuration:

import { useContractWrite } from 'wagmi'

function App() {
  const { data, isError, isLoading, write } = useContractWrite(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'feed',
    {
      args: [],
      transactionName: 'Feeds wagmigotchi!'
    },
  )
}

[jxom]

Yo @nickbytes – this sounds amazing! I think this would really lift up wagmi's game. 💪

Feels like this will slot in easily into wagmi 0.3 too as this is pretty reliant on local storage & key-specific caching.

My 2c on the deets

Transactions would be persisted to localstorage

Yes, sounds great! This will be built into wagmi 0.3 & that version also has an advantage that the consumer can also choose which storage mechanism they want to use.

My only concern from a UX perspective is that a user may get confused as to why their transactions are not persisting across browsers/devices. Maybe we will need to communicate this in the docs (maybe the interface needs to state that it is transactions performed on the current browser? idk).

I wonder if we should provide a way for a consumer to have the ability to persist to a remote DB or something, in case they want the ability to persist transaction history across browsers/devices for a user. I think this is a separate discussion though, and should come after an initial cut of this hook.

Transactions would be organized by chain ID

Makes sense to me, this will be trivial in 0.3 too as we cache most hooks on chainId 😀

Developers would be able name or label transactions in a human-readable way

Yessss 😍🥰

Developers would have the ability to clear transaction history (i.e. clearTransactions)

Makes sense!

Within wagmi, the useContract hook would need an option (default behavior?) to call addTransaction from the useTransaction hook.

Yeah absolutely.

Transactions would not include all historical transactions for a user (i.e. by default, we are not pulling from a full node or remote provider)

For some use-cases such as: RainbowKit, Uniswap & dapps that want to scope and humanize transactions – this absolutely makes sense. But I also think that the case to display historical transactions would also make sense. In fact, I think that the implementation of historical txn's would be a bit different (defining human names for txns is obvs non-trivial) to the functionality we want to achieve here, so maybe there should be a separation between "local transactions" (this proposal) & "remote transactions" (full txn history). I feel like the terminology "local transactions" may feel a bit better, as the transactions are scoped to the app (and persisted in localstorage).

I wonder if this hook should be named useLocalTransactions for this matter, as I think consumers would get confused as to why it's not showing the full transaction history for a given address. Maybe down the line we could add a useTransactions (or useRemoteTransactions) hook for the use-case of full transaction history.

---

Everything else looks pretty sweet though! 🤝

[nickbytes]

I like the delineation between useLocalTransactions and useRemoteTransactions – that's definitely more clear!

[tmm]

Update: Sounds like y'all are adding into RainbowKit for now.

[quagliero]

With the release of rainbowkit it looks like they have their own internal transaction context which you can add to by using the useAddRecentTransaction hook to display within their account pop-out. While useful, they don't export the transactions context and therefore doesn't cover the use-case of a useTransactions hook that the UI can access so we can render notifications etc

Just wondering if there's any plan for a useLocalTransactions to be released soon? Or any plans for rainbow to hook into this automatically? It's probably my favourite part of useDapp and feels like the only core feature that wagmi is really missing.

[quagliero]

Realised I didn't tag @tmm for visibility of that reply. Whoops.

[tmm]

Thanks for the tag. There are few other streams of work that are currently prioritized over this one. We can revisit at some point in the future.

In the meantime, I recommend checking out RainbowKits transactionStore implementation.