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.
| Precompile | Address | Purpose |
|---|---|---|
ArbAddressTable | 0x66 | Supporting compression of addresses |
ArbAggregator | 0x6d | Configuring transaction aggregation |
ArbBLS | 0x67 | Managing BLS keys |
ArbDebug | 0xff | Testing tools |
ArbFunctionTable | 0x68 | No longer used |
ArbGasInfo | 0x6c | Info about gas pricing |
ArbInfo | 0x65 | Info about accounts |
ArbOwner | 0x70 | Chain administration, callable only by chain owner |
ArbOwnerPublic | 0x6b | Info about chain owners |
ArbosTest | 0x69 | No longer used |
ArbRetryableTx | 0x6e | Managing retryables |
ArbStatistics | 0x6f | Info about the pre-Nitro state |
ArbSys | 0x64 | System-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 |
mixed | Emitted in Events for testing |
store | Never 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.
| Methods | Nitro 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 | |
|---|---|
OwnerActs | Emitted 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.
| Methods | Nitro 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 creation | Reverts when not found |
getTimeout(ticket) | Gets the timestamp for when ticket will expire | |
keepAlive(ticket) | Adds one lifetime period to the ticket's expiry | Doesn't add callvalue |
redeem(ticket) | Schedule an attempt to redeem the retryable, donating all of the call's gas | Happens in a future transaction |
| Events | Nitro Changes | |
|---|---|---|
ticketCreated | Emitted when creating a retryable | |
lifetimeExtended | Emitted when extending a retryable's expiry | |
redeemScheduled | Emitted when scheduling a retryable | Replaces Redeemed |
canceled | Emitted 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.
| Methods | Nitro 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 version | Now view |
getStorageGasAvailable() | Returns 0 since Nitro has no concept of storage gas | Now 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 alias | 2nd arg is unused |
wasMyCallersAddressAliased() | Checks if the caller's caller was aliased | |
myCallersAddressWithoutAliasing() | Gets the caller's caller without any potential address aliasing | New outbox scheme |
sendTxToL1(destination, calldataForL1) | Sends a transaction to L1, adding it to the outbox; callvalue is sent to L1 attached to the sent transaction | New outbox scheme |
sendMerkleTreeState() | Gets the root, size, and partials of the outbox Merkle tree state | New 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 |
sendMerkleUpdate | Logs 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 |