Class: BSV::Network::ARC

Inherits:
Object
  • Object
show all
Defined in:
lib/bsv/network/arc.rb

Overview

ARC broadcaster for submitting transactions to the BSV network.

This facade preserves the legacy public API contract while delegating all HTTP logic to Protocols::ARC. It translates Result objects returned by the protocol into BroadcastResponse instances or raised BroadcastError exceptions as required by consumer code.

Any object responding to #broadcast(tx) can serve as a broadcaster; this class implements that contract using the ARC API.

Constant Summary collapse

REJECTED_STATUSES =

ARC response statuses that indicate the transaction was NOT accepted.

%w[
  REJECTED
  DOUBLE_SPEND_ATTEMPTED
  INVALID
  MALFORMED
  MINED_IN_STALE_BLOCK
].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url_or_protocol, api_key: nil, deployment_id: nil, callback_url: nil, callback_token: nil, http_client: nil) ⇒ ARC

Returns a new instance of ARC.

Parameters:

  • url_or_protocol (String, Protocols::ARC) —

    ARC base URL (without trailing slash) or a pre-configured Protocols::ARC instance. When a URL string is supplied, the remaining keyword arguments are forwarded to the underlying protocol constructor. When a protocol instance is supplied, all keyword arguments are ignored.

  • api_key (String, nil) (defaults to: nil) —

    optional bearer token for Authorization

  • deployment_id (String, nil) (defaults to: nil) —

    optional deployment identifier for the XDeployment-ID header; defaults to a per-instance random value

  • callback_url (String, nil) (defaults to: nil) —

    optional X-CallbackUrl for ARC status callbacks

  • callback_token (String, nil) (defaults to: nil) —

    optional X-CallbackToken for ARC status callback authentication

  • http_client (#request, nil) (defaults to: nil) —

    injectable HTTP client for testing



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/bsv/network/arc.rb', line 57

def initialize(url_or_protocol, api_key: nil, deployment_id: nil, callback_url: nil,
               callback_token: nil, http_client: nil)
  @protocol =
    if url_or_protocol.is_a?(String)
      Protocols::ARC.new(
        base_url: url_or_protocol,
        api_key: api_key,
        deployment_id: deployment_id,
        callback_url: callback_url,
        callback_token: callback_token,
        http_client: http_client
      )
    else
      url_or_protocol
    end
end

Class Method Details

.default(testnet: false, api_key: nil, http_client: nil, **opts) ⇒ ARC

Returns an ARC instance pointed at the GorillaPool public ARC endpoint.

Parameters:

  • testnet (Boolean) (defaults to: false) —

    when true, uses the GorillaPool testnet endpoint

  • api_key (String, nil) (defaults to: nil) —

    optional bearer token for Authorization

  • http_client (#request, nil) (defaults to: nil) —

    injectable HTTP client for testing

  • opts (Hash) —

    ARC-specific options forwarded to the protocol (e.g. deployment_id:, callback_url:, callback_token:)

Returns:



23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/bsv/network/arc.rb', line 23

def self.default(testnet: false, api_key: nil, http_client: nil, **opts)
  provider = Providers::GorillaPool.default(testnet: testnet)
  arc_protocol = provider.protocol_for(:broadcast)
  base_url = arc_protocol.base_url
  new(
    base_url,
    api_key: api_key,
    http_client: http_client,
    **opts
  )
end

Instance Method Details

#broadcast(tx, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil) ⇒ BroadcastResponse

Submit a transaction to ARC.

Parameters:

  • tx (Transaction) —

    the transaction to broadcast

  • wait_for (String, nil) (defaults to: nil) —

    ARC wait condition

  • skip_fee_validation (Boolean, nil) (defaults to: nil) —

    when truthy, sends X-SkipFeeValidation header

  • skip_script_validation (Boolean, nil) (defaults to: nil) —

    when truthy, sends X-SkipScriptValidation header

Returns:

Raises:

  • (BroadcastError) —

    when ARC returns a non-2xx HTTP status or a rejected/orphan txStatus



83
84
85
86
87
88
89
90
91
 
# File 'lib/bsv/network/arc.rb', line 83

def broadcast(tx, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
  result = @protocol.call(
    :broadcast, tx,
    wait_for: wait_for,
    skip_fee_validation: skip_fee_validation,
    skip_script_validation: skip_script_validation
  )
  result_to_response!(result)
end

#broadcast_many(txs, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil) ⇒ Array<BroadcastResponse, BroadcastError>

Submit multiple transactions to ARC in a single batch request.

Returns a mixed array of BroadcastResponse and BroadcastError objects. Per-transaction rejections are returned as BroadcastError values rather than raised. Only HTTP-level errors raise a BroadcastError for the whole batch.

Parameters:

  • txs (Array<Transaction>) —

    transactions to broadcast

  • wait_for (String, nil) (defaults to: nil) —

    ARC wait condition

  • skip_fee_validation (Boolean, nil) (defaults to: nil)
  • skip_script_validation (Boolean, nil) (defaults to: nil)

Returns:

Raises:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/bsv/network/arc.rb', line 105

def broadcast_many(txs, wait_for: nil, skip_fee_validation: nil, skip_script_validation: nil)
  result = @protocol.call(
    :broadcast_many, txs,
    wait_for: wait_for,
    skip_fee_validation: skip_fee_validation,
    skip_script_validation: skip_script_validation
  )

  case result
  when Result::Success
    result.data.map { |item| item_to_response_or_error(item) }
  else
    raise broadcast_error_from_result(result)
  end
end

#status(txid) ⇒ BroadcastResponse

Query the status of a previously submitted transaction.

Parameters:

  • txid (String) —

    transaction ID to query

Returns:

Raises:



126
127
128
129
 
# File 'lib/bsv/network/arc.rb', line 126

def status(txid)
  result = @protocol.call(:get_tx_status, txid)
  result_to_response!(result)
end