Class: BlockGiven::Transaction

Inherits:
Object
  • Object
show all
Defined in:
lib/block_given/transaction.rb

Overview

A broadcast transaction identified by its hash. Wraps receipt polling.

tx = usdc.transfer(to: "0x...", amount: 1e6)
tx.hash            # => "0x..."
receipt = tx.wait  # polls until mined (see BlockGiven.config.timeout / polling_interval)
tx.wait!           # same, but raises BlockGiven::TransactionRevertedError on failure

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(hash, client:) ⇒ Transaction 



13
14
15
16
17
 
# File 'lib/block_given/transaction.rb', line 13

def initialize(hash, client:)
  @hash = hash
  @client = client
  @receipt = nil
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



11
12
13
 
# File 'lib/block_given/transaction.rb', line 11

def client
  @client
end

#hash ⇒ Object (readonly)

Returns the value of attribute hash.



11
12
13
 
# File 'lib/block_given/transaction.rb', line 11

def hash
  @hash
end

Instance Method Details

#==(other) ⇒ Object 



78
 
# File 'lib/block_given/transaction.rb', line 78

def ==(other) = other.is_a?(Transaction) && other.hash == hash

#confirmations ⇒ Object

Blocks since inclusion, 1 when mined in the latest block, 0 while not mined.



50
51
52
53
54
 
# File 'lib/block_given/transaction.rb', line 50

def confirmations
  return 0 unless mined?

  [client.block_number - receipt.block_number + 1, 0].max
end

#confirmed?(count = nil) ⇒ Boolean

Non-blocking counterpart of wait(confirmations:). Defaults to BlockGiven.config.confirmations.



57
 
# File 'lib/block_given/transaction.rb', line 57

def confirmed?(count = nil) = confirmations >= (count || BlockGiven.config.confirmations)

#details ⇒ Object

Raw transaction object from the node (nil while it is not yet known).



73
 
# File 'lib/block_given/transaction.rb', line 73

def details = client.get_transaction(hash)

#explorer_url ⇒ Object 



75
 
# File 'lib/block_given/transaction.rb', line 75

def explorer_url = client.chain&.explorer_tx_url(hash)

#inspect ⇒ Object 



79
 
# File 'lib/block_given/transaction.rb', line 79

def inspect = "#<BlockGiven::Transaction #{hash}#{mined_flag}>"

#mined? ⇒ Boolean 



31
 
# File 'lib/block_given/transaction.rb', line 31

def mined? = !receipt.nil?

#pending? ⇒ Boolean 



46
 
# File 'lib/block_given/transaction.rb', line 46

def pending? = status == :pending

#receipt ⇒ Object

Non-blocking: the receipt if the transaction is mined, nil otherwise. Cached once found: call #reload (or build a fresh handle with client.transaction) to re-query the node, e.g. on every tick of a long-lived worker.



22
23
24
 
# File 'lib/block_given/transaction.rb', line 22

def receipt
  @receipt ||= client.get_transaction_receipt(hash)
end

#reload ⇒ Object 



26
27
28
29
 
# File 'lib/block_given/transaction.rb', line 26

def reload
  @receipt = nil
  self
end

#reverted? ⇒ Boolean 



45
 
# File 'lib/block_given/transaction.rb', line 45

def reverted? = mined? && receipt.reverted?

#status ⇒ Object

One RPC round trip to classify the transaction (two while it is not mined):

:success / :reverted  mined, from the receipt status
:pending              known by the node, waiting in the mempool
:unknown              the node has never seen it, or dropped it: safe to re-broadcast
                    the same signed bytes (see SignedTransaction#replacement)



38
39
40
41
42
 
# File 'lib/block_given/transaction.rb', line 38

def status
  return receipt.status if mined?

  details ? :pending : :unknown
end

#success? ⇒ Boolean 



44
 
# File 'lib/block_given/transaction.rb', line 44

def success? = mined? && receipt.success?

#to_s ⇒ Object 



77
 
# File 'lib/block_given/transaction.rb', line 77

def to_s = hash

#unknown? ⇒ Boolean 



47
 
# File 'lib/block_given/transaction.rb', line 47

def unknown? = status == :unknown

#wait(confirmations: nil, timeout: nil, polling_interval: nil) ⇒ Object 



59
60
61
62
63
 
# File 'lib/block_given/transaction.rb', line 59

def wait(confirmations: nil, timeout: nil, polling_interval: nil)
  @receipt = client.wait_for_transaction_receipt(
    hash, confirmations: confirmations, timeout: timeout, polling_interval: polling_interval
  )
end

#wait!(**options) ⇒ Object

Raises:



65
66
67
68
69
70
 
# File 'lib/block_given/transaction.rb', line 65

def wait!(**options)
  receipt = wait(**options)
  raise TransactionRevertedError, receipt if receipt.reverted?

  receipt
end