Liking cljdoc? Tell your friends :D

district-ui-web3-tx

Build Status

Clojurescript re-mount module, that helps managing web3 smart-contract transactions in following ways:

  • Serves as central place to fire re-frame events after all transaction related events. Other modules can then easily hook into those events and provide additional features on top of it. Example of such module is district-ui-web3-tx-log-core.
  • It stores transaction data in browser's localstorage, so they're persisted between sessions.
  • It loads and uses recommended gas prices from ETH Gas Station.

Installation

Add [district0x/district-ui-web3-tx "1.0.10"] into your project.clj
Include [district.ui.web3-tx] in your CLJS file, where you use mount/start

API Overview

Warning: district0x modules are still in early stages, therefore API can change in a future.

district.ui.web3-tx

This namespace contains web3-tx mount module.

You can pass following args to initiate this module:

  • :disable-using-localstorage? Pass true if you don't want to store transaction data in a browser's localstorage
  • :disable-loading-recommended-gas-prices? Pass true if you don't want to load recommended gas prices
  • :recommended-gas-prices-load-interval Interval at which recommended gas prices should be loaded. Default 30000 (30 seconds)
  • :recommended-gas-price-option Option which should be used from recommended gas prices. Possible options: :fastest, :fast, :average, :safe-low. Default: :average
  (ns my-district.core
    (:require [mount.core :as mount]
              [district.ui.web3-tx]))
              
  (-> (mount/with-args
        {:web3 {:url "https://mainnet.infura.io/"}
         :web3-tx {:disable-using-localstorage? true
                   :recommended-gas-price-option :safe-low}})
    (mount/start))

district.ui.web3-tx.subs

re-frame subscriptions provided by this module:

txs [filter-opts]

Returns map of all transactions. Optionally, you can provide filter opts if you want to filter only transactions with a specific property in tx data. For example it can be :status, :from, :to.
There are 3 possible transaction statuses:

  • :tx.status/success
  • :tx.status/pending
  • :tx.status/error
(ns my-district.core
    (:require [mount.core :as mount]
              [district.ui.web3-tx :as subs]))
  
  (defn home-page []
    (let [pending-txs (subscribe [::subs/txs {:status :tx.status/pending}])]  
      (fn []
        [:div "Your pending transactions: "]
        (for [[tx-hash tx] @pending-txs]
          [:div 
            {:key tx-hash}
            "Transaction hash: " tx-hash]))))

tx [tx-hash]

Returns transaction with transaction hash tx-hash

recommended-gas-prices

Returns recommended has prices loaded from ETH Gas Station.

@(subscribe [::subs/recommended-gas-prices])
;; => {
;; :fast 9000000000
;; :fastest 20000000000
;; :speed 0.9819364005608542
;; :safe-low 1000000000
;; :avg-wait 1.5
;; :fastest-wait 0.4 
;; :safe-low-wait 14 
;; :block-num 7820908 
;; :average 3000000000 
;; :fast-wait 0.5
;; :block-time 12.660377358490566}

recommended-gas-price

Returns recommended has price at key `recommended-gas-price-option``.

@(subscribe [::subs/recommended-gas-price])
;; => 3000000000

recommended-gas-price-option

Returns option which will be used for gas prices.

@(subscribe [::subs/recommended-gas-price-option])
;; => :fastest

district.ui.web3-tx.events

re-frame events provided by this module:

send-tx [opts]

Sends Ethereum transaction. Pass same arguments as you'd pass to web3/call for state changing contract function.

(dispatch [::events/send-tx {:instance MintableToken
                             :fn :mint
                             :args [(first accounts) (web3/to-wei 1 :ether)]
                             :tx-opts {:from (first accounts) :gas 4500000}
                             :on-tx-hash [::tx-hash]
                             :on-tx-hash-n [[::tx-hash]]
                             :on-tx-hash-error [::tx-hash-error]
                             :on-tx-hash-error-n [[::tx-hash-error]]
                             :on-tx-success [::tx-success]
                             :on-tx-success-n [[::tx-success]]
                             :on-tx-error [::tx-error]
                             :on-tx-error-n [[::tx-error]]}])

watch-pending-txs

Starts watching currently pending transactions. This event is fired at mount start.

tx-hash

Event fired when a transaction was sent and transaction hash was obtained. Use this event to hook into event flow.

tx-hash-error

Event fired when there was an error sending transaction. Use this event to hook into event flow.

tx-success

Event fired when transaction was successfully processed. Use this event to hook into event flow.

(ns my-district.events
    (:require [district.ui.web3-tx.events :as tx-events]
              [re-frame.core :refer [reg-event-fx]]
              [day8.re-frame.forward-events-fx]))
              
(reg-event-fx
  ::my-event
  (fn []
    {:register :my-forwarder
     :events #{::tx-events/tx-success}
     :dispatch-to [::do-something-after-tx-success]}))

tx-error

Event fired when there was an error processing a tx. Use this event to hook into event flow.

tx-receipt

Event fired when receipt for a tx was loaded. No matter if tx succeeded or failed. Use this event to hook into event flow.

tx-loaded

After tx-receipt is fired, this module will also load a transaction (web3.eth.getTransaction). This event is fired when a transaction is loaded. Use this event to hook into event flow.

add-tx [tx-hash]

Adds new transaction hash into db, sets it as :tx.status/pending.

set-tx [tx-hash tx-data]

Updates a transaction.

remove-tx [tx-hash]

Removes transaction.

clear-localstorage

Clears transactions from localstorage.

watch-recommended-gas-prices

Will start loading recommended gas prices at configured interval.

load-recommended-gas-prices

Loads recommended gas prices from ETH Gas Station and sets results into re-frame db.

set-recommended-gas-prices

Sets results from load-recommended-gas-prices into re-frame db.

set-recommended-gas-price-option

Sets option from recommended gas prices, that will be used for transaction gas price.

stop-watching-recommended-gas-prices

Stops loading interval for recommended gas prices.

district.ui.web3-tx.queries

DB queries provided by this module:
You should use them in your events, instead of trying to get this module's data directly with get-in into re-frame db.

txs [db]

Works the same way as sub ::txs

tx [db tx-hash]

Works the same way as sub ::tx

localstorage-disabled? [db]

Returns true is using localstorage is disabled.

merge-tx-data [db tx-hash tx-data]

Merges tx data into a transaction with hash tx-hash and returns new re-frame db.

remove-tx [db tx-hash]

Removes transaction and returns new re-frame db.

merge-txs [db txs]

Merges transactions and returns new re-frame db.

merge-recommended-gas-prices [db recommended-gas-prices]

Merges recommended gas prices and returns new re-frame db.

recommended-gas-prices [db]

Works the same way as sub ::recommended-gas-prices.

assoc-recommended-gas-price-option [db option]

Associates gas price option that will be used for transaction gas price.

recommended-gas-price-option [db]

Works the same way as sub ::recommended-gas-price-option.

recommended-gas-price [db]

Works the same way as sub ::recommended-gas-price.

assoc-opt [db key value]

Associates an opt into this module state. For internal purposes mainly.

Dependency on other district UI modules

Development

lein deps
# Start ganache blockchain with 1s block time
ganache-cli -p 8549 -b 1 --noVMErrorsOnRPCResponse
# To run tests and rerun on changes
lein doo chrome tests

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close