Merge pull request #2685 from TucksonDev/add-missing-precompiles-comm…

…ents

chore: add missing precompiles comments based on interfaces

precompiles/ArbAggregator.go

@@ -36,6 +36,7 @@ func (con ArbAggregator) GetBatchPosters(c ctx, evm mech) ([]addr, error) {
 	return c.State.L1PricingState().BatchPosterTable().AllPosters(65536)
 }
 
+// Adds additional batch poster address
 func (con ArbAggregator) AddBatchPoster(c ctx, evm mech, newBatchPoster addr) error {
 	isOwner, err := c.State.ChainOwners().IsMember(c.caller)
 	if err != nil {
@@ -90,12 +91,14 @@ func (con ArbAggregator) SetFeeCollector(c ctx, evm mech, batchPoster addr, newF
 }
 
 // GetTxBaseFee gets an aggregator's current fixed fee to submit a tx
+// Deprecated: always returns zero
 func (con ArbAggregator) GetTxBaseFee(c ctx, evm mech, aggregator addr) (huge, error) {
 	// This is deprecated and now always returns zero.
 	return big.NewInt(0), nil
 }
 
 // SetTxBaseFee sets an aggregator's fixed fee (caller must be the aggregator, its fee collector, or an owner)
+// Deprecated: no-op
 func (con ArbAggregator) SetTxBaseFee(c ctx, evm mech, aggregator addr, feeInL1Gas huge) error {
 	// This is deprecated and is now a no-op.
 	return nil

precompiles/ArbDebug.go

@@ -24,6 +24,7 @@ type ArbDebug struct {
 	UnusedError func() error
 }
 
+// Emits events with values based on the args provided
 func (con ArbDebug) Events(c ctx, evm mech, paid huge, flag bool, value bytes32) (addr, huge, error) {
 	// Emits 2 events that cover each case
 	//   Basic tests an index'd value & a normal value
@@ -42,11 +43,13 @@ func (con ArbDebug) Events(c ctx, evm mech, paid huge, flag bool, value bytes32)
 	return c.caller, paid, nil
 }
 
+// Tries (and fails) to emit logs in a view context
 func (con ArbDebug) EventsView(c ctx, evm mech) error {
 	_, _, err := con.Events(c, evm, common.Big0, true, bytes32{})
 	return err
 }
 
+// Throws a custom error
 func (con ArbDebug) CustomRevert(c ctx, number uint64) error {
 	return con.CustomError(number, "This spider family wards off bugs: /\\oo/\\ //\\(oo)//\\ /\\oo/\\", true)
 }
@@ -61,6 +64,7 @@ func (con ArbDebug) Panic(c ctx, evm mech) error {
 	panic("called ArbDebug's debug-only Panic method")
 }
 
+// Throws a hardcoded error
 func (con ArbDebug) LegacyError(c ctx) error {
 	return errors.New("example legacy error")
 }

precompiles/ArbOwner.go

@@ -120,38 +120,48 @@ func (con ArbOwner) ScheduleArbOSUpgrade(c ctx, evm mech, newVersion uint64, tim
 	return c.State.ScheduleArbOSUpgrade(newVersion, timestamp)
 }
 
+// Sets equilibration units parameter for L1 price adjustment algorithm
 func (con ArbOwner) SetL1PricingEquilibrationUnits(c ctx, evm mech, equilibrationUnits huge) error {
 	return c.State.L1PricingState().SetEquilibrationUnits(equilibrationUnits)
 }
 
+// Sets inertia parameter for L1 price adjustment algorithm
 func (con ArbOwner) SetL1PricingInertia(c ctx, evm mech, inertia uint64) error {
 	return c.State.L1PricingState().SetInertia(inertia)
 }
 
+// Sets reward recipient address for L1 price adjustment algorithm
 func (con ArbOwner) SetL1PricingRewardRecipient(c ctx, evm mech, recipient addr) error {
 	return c.State.L1PricingState().SetPayRewardsTo(recipient)
 }
 
+// Sets reward amount for L1 price adjustment algorithm, in wei per unit
 func (con ArbOwner) SetL1PricingRewardRate(c ctx, evm mech, weiPerUnit uint64) error {
 	return c.State.L1PricingState().SetPerUnitReward(weiPerUnit)
 }
 
+// Set how much ArbOS charges per L1 gas spent on transaction data.
 func (con ArbOwner) SetL1PricePerUnit(c ctx, evm mech, pricePerUnit *big.Int) error {
 	return c.State.L1PricingState().SetPricePerUnit(pricePerUnit)
 }
 
+// Sets the base charge (in L1 gas) attributed to each data batch in the calldata pricer
 func (con ArbOwner) SetPerBatchGasCharge(c ctx, evm mech, cost int64) error {
 	return c.State.L1PricingState().SetPerBatchGasCost(cost)
 }
 
+// Sets the cost amortization cap in basis points
 func (con ArbOwner) SetAmortizedCostCapBips(c ctx, evm mech, cap uint64) error {
 	return c.State.L1PricingState().SetAmortizedCostCapBips(cap)
 }
 
+// Sets the Brotli compression level used for fast compression
+// Available in ArbOS version 12 with default level as 1
 func (con ArbOwner) SetBrotliCompressionLevel(c ctx, evm mech, level uint64) error {
 	return c.State.SetBrotliCompressionLevel(level)
 }
 
+// Releases surplus funds from L1PricerFundsPoolAddress for use
 func (con ArbOwner) ReleaseL1PricerSurplusFunds(c ctx, evm mech, maxWeiToRelease huge) (huge, error) {
 	balance := evm.StateDB.GetBalance(l1pricing.L1PricerFundsPoolAddress)
 	l1p := c.State.L1PricingState()
@@ -295,6 +305,7 @@ func (con ArbOwner) RemoveWasmCacheManager(c ctx, _ mech, manager addr) error {
 	return managers.Remove(manager, c.State.ArbOSVersion())
 }
 
+// Sets serialized chain config in ArbOS state
 func (con ArbOwner) SetChainConfig(c ctx, evm mech, serializedChainConfig []byte) error {
 	if c == nil {
 		return errors.New("nil context")

precompiles/ArbRetryableTx.go

@@ -222,13 +222,17 @@ func (con ArbRetryableTx) Cancel(c ctx, evm mech, ticketId bytes32) error {
 	return con.Canceled(c, evm, ticketId)
 }
 
+// Gets the redeemer of the current retryable redeem attempt.
+// Returns the zero address if the current transaction is not a retryable redeem attempt.
+// If this is an auto-redeem, returns the fee refund address of the retryable.
 func (con ArbRetryableTx) GetCurrentRedeemer(c ctx, evm mech) (common.Address, error) {
 	if c.txProcessor.CurrentRefundTo != nil {
 		return *c.txProcessor.CurrentRefundTo, nil
 	}
 	return common.Address{}, nil
 }
 
+// Do not call. This method represents a retryable submission to aid explorers. Calling it will always revert.
 func (con ArbRetryableTx) SubmitRetryable(
 	c ctx, evm mech, requestId bytes32, l1BaseFee, deposit, callvalue, gasFeeCap huge,
 	gasLimit uint64, maxSubmissionFee huge,