@darkforest_eth/network

This package contains functions and classes useful for communicating with the blockchain.

Installation

You can install this package using npm or yarn by running:

npm install --save @darkforest_eth/network

yarn add @darkforest_eth/network

When using this in a plugin, you might want to load it with skypack

import * as network from 'http://cdn.skypack.dev/@darkforest_eth/network';

Table of contents

Classes

• ContractCaller
• EthConnection
• ThrottledConcurrentQueue
• TxExecutor

Interfaces

• PendingTransaction
• Queue
• QueuedTransaction

Type aliases

• AfterTransaction
• BeforeTransaction
• ContractLoader
• GasPriceSettingProvider
• RetryErrorHandler

Functions

• aggregateBulkGetter
• assertProperlySigned
• callWithRetry
• createContract
• createEthConnection
• ethToWei
• getAutoGasPrices
• getGasSettingGwei
• getResult
• gweiToWei
• isPurchase
• makeProvider
• neverResolves
• verifySignature
• waitForTransaction
• weiToEth
• weiToGwei

Type aliases

AfterTransaction

Ƭ AfterTransaction: (transactionRequest: QueuedTransaction, performanceMetrics: unknown) => Promise<void>

Type declaration

▸ (transactionRequest, performanceMetrics): Promise<void>

TxExecutor calls this after executing a transaction.

Parameters

Name	Type
transactionRequest	QueuedTransaction
performanceMetrics	unknown

Returns

Promise<void>

---

BeforeTransaction

Ƭ BeforeTransaction: (transactionRequest: QueuedTransaction) => Promise<void>

Type declaration

▸ (transactionRequest): Promise<void>

TxExecutor calls this before executing a function to determine whether or not that function should execute. If this function throws, the transaction is cancelled.

Parameters

Name	Type
transactionRequest	QueuedTransaction

Returns

Promise<void>

---

ContractLoader

Ƭ ContractLoader<T>: (address: string, provider: providers.JsonRpcProvider, signer?: Wallet) => Promise<T>

Type parameters

Name	Type
T	extends Contract

Type declaration

▸ (address, provider, signer?): Promise<T>

Parameters

Name	Type
address	string
provider	providers.JsonRpcProvider
signer?	Wallet

Returns

Promise<T>

---

GasPriceSettingProvider

Ƭ GasPriceSettingProvider: () => AutoGasSetting | string

Type declaration

▸ (): AutoGasSetting | string

Returns either a string that represents the gas price we should use by default for transactions, or a string that represents the fact that we should be using one of the automatic gas prices.

Returns

AutoGasSetting | string

---

RetryErrorHandler

Ƭ RetryErrorHandler: (i: number, e: Error) => void

Type declaration

▸ (i, e): void

Parameters

Name	Type
i	number
e	Error

Returns

void

Functions

aggregateBulkGetter

▸ Const aggregateBulkGetter<T>(total, querySize, getterFn, onProgress?): Promise<T[]>

A useful utility function that breaks up the proverbial number line (defined by {@code total} and {@code querySize}), and calls {@code getterFn} for each of the sections on the number line.

Type parameters

Name
T

Parameters

Name	Type	Description
total	number	the total amount of of items to get
querySize	number	the chunk size
getterFn	(startIdx: number, endIdx: number) => Promise<T[]>	a function that fetches something, given a start index and end index
onProgress?	(fractionCompleted: number) => void	whenever a chunk is loaded, this function is called with the fraction of individual items that have been loaded so far.

Returns

Promise<T[]>

a list of each of the individual items that were loaded.

---

assertProperlySigned

▸ assertProperlySigned(message): void

Ensures that the given message was properly signed.

Parameters

Name	Type
message	SignedMessage<unknown>

Returns

void

---

callWithRetry

▸ Const callWithRetry<T>(fn, args?, onError?, maxRetries?, retryInterval?): Promise<T>

Calls the given function, retrying it if there is an error.

todo Get rid of this, and make use of ContractCaller.

Type parameters

Name
T

Parameters

Name	Type	Default value
fn	(...args: any[]) => Promise<T>	undefined
args	any[]	[]
onError?	RetryErrorHandler	undefined
maxRetries	12	undefined
retryInterval	number	1000

Returns

Promise<T>

---

createContract

▸ createContract<C>(contractAddress, contractABI, provider, signer?): C

Type parameters

Name	Type
C	extends Contract<C>

Parameters

Name	Type	Description
contractAddress	string	the address of the contract you want to connect to
contractABI	ContractInterface	a javacript object representing the ABI
provider	JsonRpcProvider	-
signer?	Wallet	-

Returns

C

---

createEthConnection

▸ createEthConnection(rpcUrl): Promise<EthConnection>

Parameters

Name	Type
rpcUrl	string

Returns

Promise<EthConnection>

---

ethToWei

▸ ethToWei(eth): BigNumber

Returns the given amount of eth in wei as a big integer.

Parameters

Name	Type
eth	number

Returns

BigNumber

---

getAutoGasPrices

▸ getAutoGasPrices(): Promise<GasPrices>

Gets the current gas prices from xDai's price oracle. If the oracle is broken, return some sane defaults.

Returns

Promise<GasPrices>

---

getGasSettingGwei

▸ getGasSettingGwei(setting, gasPrices): number | undefined

Given the user's auto gas setting, and the current set of gas prices on the network, returns the preferred gas price. If an invalid {@link AutoGasSetting} is provided, then returns undefined.

Parameters

Name	Type
setting	AutoGasSetting
gasPrices	GasPrices

Returns

number | undefined

---

getResult

▸ getResult(pendingTransaction): Promise<TransactionReceipt>

When you submit a transaction via TxExecutor, you are given a PendingTransaction. This function either resolves when the transaction confirms, or rejects if there is any error.

Parameters

Name	Type
pendingTransaction	PendingTransaction

Returns

Promise<TransactionReceipt>

---

gweiToWei

▸ gweiToWei(gwei): BigNumber

Returns the given amount of gwei in wei as a big integer.

Parameters

Name	Type
gwei	number

Returns

BigNumber

---

isPurchase

▸ isPurchase(tx): boolean

Whether or not some value is being transferred in this transaction.

Parameters

Name	Type
tx	providers.TransactionRequest

Returns

boolean

---

makeProvider

▸ makeProvider(rpcUrl): JsonRpcProvider

Creates a new {@link JsonRpcProvider}, and makes sure that it's connected to xDai if we're in production.

Parameters

Name	Type
rpcUrl	string

Returns

JsonRpcProvider

---

neverResolves

▸ neverResolves(): Promise<void>

A function that just never resolves.s

Returns

Promise<void>

---

verifySignature

▸ verifySignature(message, signature, address): boolean

Returns whether or not the given message was signed by the given address.

Parameters

Name	Type
message	string
signature	string
address	EthAddress

Returns

boolean

---

waitForTransaction

▸ waitForTransaction(provider, txHash): Promise<TransactionReceipt>

Given a transaction hash and a JsonRpcProvider, waits for the given transaction to complete.

Parameters

Name	Type
provider	JsonRpcProvider
txHash	string

Returns

Promise<TransactionReceipt>

---

weiToEth

▸ weiToEth(wei): number

Returns the given amount of wei in gwei as a number.

Parameters

Name	Type
wei	BigNumber

Returns

number

---

weiToGwei

▸ weiToGwei(wei): number

Returns the given amount of wei in gwei as a number.

Parameters

Name	Type
wei	BigNumber

Returns

number