Skip to main content

ArbOS precompiles

ArbOS provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. This reference exhaustively documents the specific calls ArbOS makes available. For more details on the infrastructure that makes this possible, please refer to the ArbOS documentation. For an abbreviated reference on the precompiles we expect users to most often use, please see the common precompiles documentation.

From the perspective of user applications, precompiles live as contracts at the following addresses. Click on any to jump to their section.

PrecompileAddress  Purpose
ArbAddressTable0x66Supporting compression of addresses
ArbAggregator0x6dConfiguring transaction aggregation
ArbBLS0x67Managing BLS keys
ArbDebug0xffTesting tools
ArbFunctionTable0x68No longer used
ArbGasInfo0x6cInfo about gas pricing
ArbInfo0x65Info about accounts
ArbOwner0x70Chain administration, callable only by chain owner
ArbOwnerPublic0x6bInfo about chain owners
ArbosTest0x69No longer used
ArbRetryableTx0x6eManaging retryables
ArbStatistics0x6fInfo about the pre-Nitro state
ArbSys0x64System-level functionality

ArbAddressTable

ArbAddressTable provides the ability to create short-hands for commonly used accounts.

Methods
addressExists(address)Checks if an address exists in the table
compress(address)Gets bytes that represent the address
decompress(buffer, offset)  Replaces the compressed bytes at the given offset with those of the corresponding account
lookup(address)Gets the index of an address in the table
lookupIndex(index)Gets the address at an index in the table
register(address)Adds an address to the table, shrinking its compressed representation
size()Gets the number of addresses in the table

ArbAggregator

ArbAggregator provides aggregators and their users methods for configuring how they participate in L1 aggregation. Arbitrum One's default aggregator is the Sequencer, which a user will prefer unless SetPreferredAggregator is invoked to change it.

Compression ratios are measured in basis points. Methods that are checkmarked are access-controlled and will revert if not called by the aggregator, its fee collector, or a chain owner.

Methods
getPreferredAggregator(account)Gets an account's preferred aggregator
setPreferredAggregator(aggregator)Sets the caller's preferred aggregator to that provided
getDefaultAggregator()Gets the chain's default aggregator
setDefaultAggregator(default)Sets the chain's default aggregator✔️
getCompressionRatio(aggregator)Gets the aggregator's compression ratio
setCompressionRatio(aggregator, ratio)Set the aggregator's compression ratio✔️
getFeeCollector(aggregator)Gets an aggregator's fee collector
setFeeCollector(aggregator, collector)  Sets an aggregator's fee collector✔️
Deprecated Methods
getTxBaseFee(aggregator)Returns 0
setTxBaseFee(aggregator, fee)Does nothing

ArbBLS

ArbBLS provides a registry of BLS public keys for accounts.

Methods
registerAltBN128(x0, x1, y0, y1)  Associate an AltBN128 public key with the caller's address
getAltBN128(account)Gets the AltBN128 public key associated with an address
registerBLS12381(key)Associate a BLS 12-381 public key with the caller's address
getBLS12381(account)Gets the BLS 12-381 public key associated with an address
Deprecated Methods
register(x0, x1, y0, y1)  equivalent to registerAltBN128
getPublicKey(account)equivalent to getAltBN128

ArbDebug

ArbDebug provides mechanisms useful for testing. The methods of ArbDebug are only available for chains with the AllowDebugPrecompiles chain parameter set. Otherwise, calls to this precompile will revert.

Methods
becomeChainOwner()Caller becomes a chain owner
events(flag, value)  Emit events with values based on the args provided
Events
basic  Emitted in Events for testing
mixedEmitted in Events for testing
storeNever emitted (used for testing log sizes)

ArbFunctionTable

ArbFunctionTable provides aggregators the ability to manage function tables, to enable one form of transaction compression. The Nitro aggregator implementation does not use these, so these methods have been stubbed and their effects disabled. They are kept for backwards compatibility.

Methods
get(address, index)  Reverts since the table is empty
size(address)Returns the empty table's size, which is 0
upload(bytes)Does nothing

ArbGasInfo

ArbGasInfo provides insight into the cost of using the chain. These methods have been adjusted to account for Nitro's heavy use of calldata compression. Of note to end-users, we no longer make a distinction between non-zero and zero-valued calldata bytes.

Methods
getPricesInWeiWithAggregator(aggregator)Get prices in wei when using the provided aggregator
getPricesInWei()Get prices in wei when using the caller's preferred aggregator
getPricesInArbGasWithAggregator(aggregator)Get prices in ArbGas when using the provided aggregator
getPricesInArbGas()Get prices in ArbGas when using the caller's preferred aggregator
getGasAccountingParams()Get the chain speed limit, pool size, and transaction gas limit
getMinimumGasPrice()Get the minimum gas price needed for a transaction to succeed
getGasPoolSeconds()Get the number of seconds worth of the speed limit the gas pool contains
getGasPoolTarget()Get the target fullness in bips the pricing model will try to keep the pool at
getGasPoolWeight()Get the extent in bips to which the pricing model favors filling the pool over increasing speeds
getRateEstimate()Get ArbOS's estimate of the amount of gas being burnt per second
getRateEstimateInertia()Get how slowly ArbOS updates its estimate the amount of gas being burnt per second
getL1BaseFeeEstimate()Get ArbOS's estimate of the L1 basefee in wei
getL1BaseFeeEstimateInertia()Get how slowly ArbOS updates its estimate of the L1 basefee
getL1GasPriceEstimate()Deprecated -- Same as getL1BaseFeeEstimate()
getCurrentTxL1GasFees()Get L1 gas fees paid by the current transaction

ArbInfo

ArbInfo provides the ability to lookup basic info about accounts and contracts.

Methods
getBalance(account)  Retrieves an account's balance
getCode(account)Retrieves a contract's deployed code

ArbosTest

ArbosTest Ppovides a method of burning arbitrary amounts of gas, which exists for historical reasons. In Classic, ArbosTest had additional methods only the zero address could call. These have been removed since users don't use them and calls to missing methods revert.

MethodsNitro changes
burnArbGas(amount)  unproductively burns the amount of L2 ArbGas  Now pure

ArbOwner

ArbOwner provides owners with tools for managing the rollup. Calls by non-owners will always revert.

Most of Arbitrum Classic's owner methods have been removed since they no longer make sense in Nitro:

  • What were once chain parameters are now parts of ArbOS's state, and those that remain are set at genesis.
  • ArbOS upgrades happen with the rest of the system rather than being independent
  • Exemptions to address aliasing are no longer offered. Exemptions were intended to support backward compatibility for contracts deployed before aliasing was introduced, but no exemptions were ever requested.
Methods
addChainOwner(newOwner)Adds account as a chain owner
removeChainOwner(addr)Removes account from the list of chain owners
isChainOwner(addr)Sees if account is a chain owner
getAllChainOwners()Retrieves the list of chain owners
setL1BaseFeeEstimateInertia(inertia)Sets how slowly ArbOS updates its estimate of the L1 basefee
setL2BaseFee(priceInWei)Sets the L2 gas price directly, bypassing the pool calculus
setMinimumL2BaseFee(priceInWei)Sets the minimum base fee needed for a transaction to succeed
setSpeedLimit(limit)Sets the computational speed limit for the chain
setMaxTxGasLimit(limit)Sets the maximum size a transaction (and block) can be
setL2GasPricingInertia(sec)Sets the L2 gas pricing inertia
setL2GasBacklogTolerance(sec)Sets the the L2 gas backlog tolerance
getNetworkFeeAccount()Gets the network fee collector
getInfraFeeAccount()Gets the infrastructure fee collector
setNetworkFeeAccount(newNetworkFeeAccount)Sets the network fee collector to the new network fee account
setInfraFeeAccount(newNetworkFeeAccount)Sets the infra fee collector to the new network fee account
scheduleArbOSUpgrade(newVersion, timestamp)Schedules and ArbOS upgrade to the requested version at the requested timestamp
setL1PricingEquilibrationUnits(equilibrationUnits)Sets the L1 price equilibration units
setL1PricingInertia(inertia)Sets how slowly ArbOS updates its estimate of the L1 price
setL1PricingRewardRecipient(recipient)Sets the recipient of the l1 pricing rewards
setL1PricingRewardRate(weiPerUnit)Sets the L1 pricing rewards rate
setL1PricePerUnit(pricePerUnit)Sets the L1 price per unit
setPerBatchGasCharge(cost)Sets the cost per batch to charge
setAmortizedCostCapBips(cap)Sets the amortized cost cap bips
releaseL1PricerSurplusFunds(maxWeiToRelease)Releases the L1Pricer surplus funds
Events
OwnerActsEmitted when a successful call is made to this precompile

ArbOwnerPublic

ArbOwnerPublic provides non-owners with info about the current chain owners.

Methods
isChainOwner(account)  See if account is a chain owner
getAllChainOwners()Gets the list of chain owners
getNetworkFeeAccount()Gets the network fee collector

ArbRetryableTx

ArbRetryableTx provides methods for managing retryables. The model has been adjusted for Nitro, most notably in terms of how retry transactions are scheduled. For more information on retryables, please see the retryable documentation.

MethodsNitro changes
cancel(ticket)Cancel the ticket and refund its callvalue to its beneficiary
getBeneficiary(ticket)  Gets the beneficiary of the ticket
getLifetime()Gets the default lifetime period a retryable has at creationReverts when not found
getTimeout(ticket)Gets the timestamp for when ticket will expire
keepAlive(ticket)Adds one lifetime period to the ticket's expiryDoesn't add callvalue
redeem(ticket)Schedule an attempt to redeem the retryable, donating all of the call's gas  Happens in a future transaction
EventsNitro Changes
ticketCreatedEmitted when creating a retryable
lifetimeExtended  Emitted when extending a retryable's expiry  
redeemScheduledEmitted when scheduling a retryableReplaces Redeemed
canceledEmitted when cancelling a retryable

ArbStatistics

ArbStatistics provides statistics about the chain as of just before the Nitro upgrade. In Arbitrum Classic, this was how a user would get info such as the total number of accounts, but there are better ways to get that info in Nitro.

Methods
GetStats()  Returns the current block number and some statistics about the rollup's pre-Nitro state

ArbSys

ArbSys provides system-level functionality for interacting with L1 and understanding the call stack.

MethodsNitro changes
arbBlockNumber()Gets the current L2 block number
arbBlockHash(blocknum)Gets the L2 block hash at blocknum, if blocknum is sufficiently recent
arbChainID()Gets the chain's ChainID
arbOSVersion()Gets the current ArbOS versionNow view
getStorageGasAvailable()Returns 0 since Nitro has no concept of storage gasNow always 0
isTopLevelCall()Checks if the caller is top-level (i.e. if the caller was called directly by an EOA or an L1 contract)
mapL1SenderContractAddressToL2Alias(contract, unused)  Gets contract's L2 alias2nd arg is unused
wasMyCallersAddressAliased()Checks if the caller's caller was aliased
myCallersAddressWithoutAliasing()Gets the caller's caller without any potential address aliasingNew outbox scheme
sendTxToL1(destination, calldataForL1)Sends a transaction to L1, adding it to the outbox; callvalue is sent to L1 attached to the sent transactionNew outbox scheme
sendMerkleTreeState()Gets the root, size, and partials of the outbox Merkle tree stateNew outbox scheme
withdrawEth(destination)Send callvalue to the destination address on L1
Events
L2ToL1Transaction  Logs a send transaction from L2 to L1, including data for outbox proving
sendMerkleUpdateLogs a new merkle branch needed for constructing outbox proofs
Removed Methods
getStorageAt(account, index)  Nitro doesn't need this introspection, and users couldn't call it
getTransactionCount(account)Nitro doesn't need this introspection, and users couldn't call it