Network Provider

The CashScript-Py SDK needs to connect to the BCH network to perform certain operations, like retrieving a contract’s balance, fetching UTXOs, or broadcasting transactions.

Tip: CashScript-Py providers implement a standardized interface, so it’s easy to swap out dependencies.

Interface NetworkProvider

Network

The NetworkProvider.network property uses the Network enum:

Network.MAINNET
Network.CHIPNET
Network.TESTNET3
Network.TESTNET4
Network.MOCKNET (placeholder)
Network.REGTEST (placeholder)

Example

connected_network = provider.network

get_utxos()

await provider.get_utxos(address: str) -> list[Utxo]

Returns all UTXOs at an address (confirmed and unconfirmed).

Utxo has:

txid: str
vout: int
satoshis: int
token: TokenDetails | None

Example

from cashscript_py import Utxo

user_utxos: list[Utxo] = await provider.get_utxos(user_address)

get_block_height()

await provider.get_block_height() -> int

Get the current block height.

Example

current_block_height: int = await provider.get_block_height()

get_raw_transaction()

await provider.get_raw_transaction(txid: str) -> str

Retrieve the raw transaction hex for a given transaction ID.

Example

raw_transaction_hex: str = await provider.get_raw_transaction(txid)

send_raw_transaction()

await provider.send_raw_transaction(tx_hex: str) -> str

Broadcast a raw hex transaction to the network, returning the txid.

Example

txid: str = await provider.send_raw_transaction(tx_hex)

Custom NetworkProviders

A big strength of the provider setup is that it allows custom providers. If you want to use a different BCH indexer for network information, implement the NetworkProvider interface and pass your provider into Contract and TransactionBuilder.

Provider-specific functionality

Beyond the standardized interface, each provider can expose its own extra methods. This can either be done by extending the NetworkProvider interface or simply by adding extra methods to the concrete provider class.

Limitations

The provider interface currently does not include confirmation metadata (e.g., confirmation count, block hash). This means your application cannot always distinguish whether state is confirmed, pending, or later reversed by a reorg.

If your application needs confirmation guarantees, build confirmation logic on top of provider methods.