Liking cljdoc? Tell your friends :D

district-ui-web3-tx

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

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
district.ui.web3-tx.subs
district.ui.web3-tx.events
district.ui.web3-tx.queries

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:

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

district-ui-web3

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? These fine people already did:
madvas, Filip Bielejec & filipEdit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts

`Ctrl`+`k`	Jump to recent docs
`←`	Move to previous article
`→`	Move to next article
`Ctrl`+`/`	Jump to the search field

Raise an issue Browse cljdoc source Chat on Slack

× close