Public Client

A public client reads Aleo chain state and nothing else: blocks, transactions, balances, program mappings, staking data, and network metrics. It carries no account and no proving configuration, so it cannot sign or submit a transaction — every method is a network read through its transport. This mirrors viem's publicClient: the read surface is separate from the write surface, so an application can hold a public client with no wallet connected at all.

Create a public client

import { createPublicClient, http } from '@provablehq/veil-core'

const client = createPublicClient({
  transport: http('https://api.provable.com/v2', { network: 'mainnet' }),
})

createPublicClient takes a PublicClientConfig:

Field	Type	Description
transport	Transport	Carries every read request to the network. See Transports.
key	string (optional)	Identifier for the client's type. Defaults to 'public'.
name	string (optional)	Human-readable name. Defaults to 'Public Client'.

Actions

Every method below hits the network through the client's transport and returns a typed result. Full parameters, return types, and examples live on each action's own page.

Chain state

Action	Description
getBlockNumber	Latest block height.
getBlockHash	Latest block hash.
getBlock	Block by height or hash.
getBlocks	Blocks in a height range.
getBlockTransactions	Confirmed transactions in a block, by height.
getBlockTransactionsByHash	Confirmed transactions in a block, by hash.
getBlockHeightByHash	Height of the block with the given hash.
getBlockSummary	Summary of the latest 1000 blocks.
getStateRoot	Global state root at a height, or the latest.
getStatePath	Merkle path proving a record commitment's inclusion.
getStatePaths	Merkle paths for multiple commitments.
findBlockHeightByStateRoot	Height of the block that produced a state root.
findBlockHash	Hash of the block containing a transaction.

Transactions

Action	Description
getTransaction	Full transaction by id.
getConfirmedTransaction	Confirmed transaction, wrapped with accepted/rejected status.
getUnconfirmedTransaction	Transaction in its as-submitted form.
getTransactionByTransition	Transaction that contains a given transition.
getTransactionsByAddress	Transactions involving an address.
getTransactionSummary	Summary of the latest 1000 transactions.
findTransactionId	Transaction id that contains a transition.

Transitions

Action	Description
getTransitions	Transition summaries involving an address.
findTransitionId	Transition id that consumed or produced an input/output.
getTransitionViewKeys	View keys for a transition's outputs.

Programs, mappings & editions

Action	Description
getCode	Program source code.
getProgram	Alias of getCode.
readContract	Read a mapping value.
readMapping	Alias for readContract.
getMappingNames	Mapping names declared by a program.
getDeploymentTransaction	Transaction that deployed a program.
getProgramCalls	Latest calls into a program.
getProgramCallsPaginated	Calls into a program, paginated.
getLatestEdition	Latest edition number for an upgradeable program.
getProgramByEdition	Program source at a specific edition.
getAmendmentCount	Number of amendments made to a program.
getAmendmentCountByEdition	Amendment count as of a specific edition.
getDeploymentTransactionByEdition	Deployment transaction for a specific edition.
getOriginalDeploymentTransaction	The program's first deployment transaction.
getAmendmentDeploymentTransaction	Deployment transaction for a specific amendment.
getProgramIdByAddress	Program id owning a given program address.
getProgramAddress	Program address for a given program id.

Account

Action	Description
getBalance	Public credits balance for an address, in microcredits.

Committee & staking

Action	Description
getCommittee	Current or historical validator committee.
getDelegators	Delegator addresses bonded to a validator.
getStakingEarnings	Cumulative staking rewards for an address.

Metrics

Action	Description
getTransactionMetrics	Daily transaction counts.
getProgramMetrics	Program call counts over the last 7 days.
getProgramMetricsByRange	Program call counts over a custom range.
getApy	Current network-wide staking APY.
getValidatorApy	Per-validator APY.

Supply & tokens

Action	Description
getTotalSupply	Total ALEO supply.
getCirculatingSupply	Circulating ALEO supply.
getTvl	Total value locked across DeFi programs.
getTokens	Token registry data.
getTokenDetails	Detail record for one token.

Examples

Read a mapping value

const balance = await client.readContract({
  programId: 'credits.aleo',
  mapping: 'account',
  key: 'aleo1...',
})
// '5000000u64'

Get the current block

const height = await client.getBlockNumber()
const block = await client.getBlock({ height: Number(height) })
console.log(block.block_hash, block.header.metadata.timestamp)

Query staking state

const committee = await client.getCommittee()
const delegators = await client.getDelegators({ validator: 'aleo1validator...' })
const earnings = await client.getStakingEarnings({ address: 'aleo1...' })

extend()

createPublicClient builds on the base client returned by createClient and layers its read actions on with extend. Any client — public, wallet, or test — can take the same path to add its own methods without losing what an earlier extend call attached:

const client = createPublicClient({
  transport: http('https://api.provable.com/v2', { network: 'mainnet' }),
}).extend((base) => ({
  getBlockAge: async () => {
    const block = await base.request({ method: 'getBlock', params: {} })
    return Date.now() / 1000 - (block as any).header.metadata.timestamp
  },
}))

Each extend call returns a new client carrying the base client's properties plus whatever the passed function returns, so decorators compose — this is how publicActions, walletActions, testActions, devnodeActions, and leoActions are all implemented.