From bfced4a048d9a36bdc8125cc27a15a4d439c1064 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Fri, 7 Feb 2025 15:59:04 -0300 Subject: [PATCH] docs: add function documentation for `elcontracts/reader` and `avsregistry/subscriber` (#533) Co-authored-by: Pablo Deymonnaz --- chainio/clients/avsregistry/subscriber.go | 2 + chainio/clients/elcontracts/reader.go | 163 +++++++++++++++++++--- 2 files changed, 143 insertions(+), 22 deletions(-) diff --git a/chainio/clients/avsregistry/subscriber.go b/chainio/clients/avsregistry/subscriber.go index abd9e08be..5be829995 100644 --- a/chainio/clients/avsregistry/subscriber.go +++ b/chainio/clients/avsregistry/subscriber.go @@ -48,6 +48,7 @@ func NewSubscriberFromConfig( return NewChainSubscriber(bindings.RegistryCoordinator, bindings.BlsApkRegistry, logger), nil } +// Returns a channel that receives new BLS pubkey registration events. func (s *ChainSubscriber) SubscribeToNewPubkeyRegistrations() (chan *blsapkreg.ContractBLSApkRegistryNewPubkeyRegistration, event.Subscription, error) { newPubkeyRegistrationChan := make(chan *blsapkreg.ContractBLSApkRegistryNewPubkeyRegistration) sub, err := s.blsApkRegistry.WatchNewPubkeyRegistration( @@ -59,6 +60,7 @@ func (s *ChainSubscriber) SubscribeToNewPubkeyRegistrations() (chan *blsapkreg.C return newPubkeyRegistrationChan, sub, nil } +// Returns a channel that receives operator socket update events. func (s *ChainSubscriber) SubscribeToOperatorSocketUpdates() (chan *regcoord.ContractRegistryCoordinatorOperatorSocketUpdate, event.Subscription, error) { operatorSocketUpdateChan := make(chan *regcoord.ContractRegistryCoordinatorOperatorSocketUpdate) sub, err := s.regCoord.WatchOperatorSocketUpdate( diff --git a/chainio/clients/elcontracts/reader.go b/chainio/clients/elcontracts/reader.go index fe444c0e4..f24df0fdb 100644 --- a/chainio/clients/elcontracts/reader.go +++ b/chainio/clients/elcontracts/reader.go @@ -42,6 +42,7 @@ type ChainReader struct { var errLegacyAVSsNotSupported = errors.New("method not supported for legacy AVSs") +// Returns a new instance of ChainReader from a given set of bindings. func NewChainReader( delegationManager *delegationmanager.ContractDelegationManager, strategyManager *strategymanager.ContractStrategyManager, @@ -66,6 +67,7 @@ func NewChainReader( } } +// Returns a new instance of ChainReader from a given config. func NewReaderFromConfig( cfg Config, ethClient eth.HttpBackend, @@ -91,6 +93,9 @@ func NewReaderFromConfig( ), nil } +// Returns `true` if the operator is registered to the EigenLayer protocol, `false` otherwise. +// Can return an error if the `DelegationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) IsOperatorRegistered( ctx context.Context, operator types.Operator, @@ -102,8 +107,9 @@ func (r *ChainReader) IsOperatorRegistered( return r.delegationManager.IsOperator(&bind.CallOpts{Context: ctx}, gethcommon.HexToAddress(operator.Address)) } -// GetStakerShares returns the amount of shares that a staker has in all of the strategies in which they have nonzero -// shares +// Returns the amount of shares that a staker has in all of the strategies they have shares in. +// Can return an error if the `DelegationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetStakerShares( ctx context.Context, stakerAddress gethcommon.Address, @@ -114,7 +120,9 @@ func (r *ChainReader) GetStakerShares( return r.delegationManager.GetDepositedShares(&bind.CallOpts{Context: ctx}, stakerAddress) } -// GetDelegatedOperator returns the operator that a staker has delegated to +// Returns the operator that a staker has delegated to. +// Can return an error if the `DelegationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetDelegatedOperator( ctx context.Context, stakerAddress gethcommon.Address, @@ -126,6 +134,9 @@ func (r *ChainReader) GetDelegatedOperator( return r.delegationManager.DelegatedTo(&bind.CallOpts{Context: ctx}, stakerAddress) } +// Returns detailed information on an operator. +// Can return an error if the `DelegationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorDetails( ctx context.Context, operator types.Operator, @@ -168,7 +179,8 @@ func (r *ChainReader) GetOperatorDetails( }, nil } -// GetStrategyAndUnderlyingToken returns the strategy contract and the underlying token address +// Returns the bindings of a given strategy and the address of its underlying token. +// Can return an error due to errors in the underlying contract call. func (r *ChainReader) GetStrategyAndUnderlyingToken( ctx context.Context, strategyAddr gethcommon.Address, @@ -185,8 +197,8 @@ func (r *ChainReader) GetStrategyAndUnderlyingToken( return contractStrategy, underlyingTokenAddr, nil } -// GetStrategyAndUnderlyingERC20Token returns the strategy contract, the erc20 bindings for the underlying token -// and the underlying token address +// Returns the bindings of a given strategy and the bindings and address of its underlying token. +// Can return an error due to errors in the underlying contract call. func (r *ChainReader) GetStrategyAndUnderlyingERC20Token( ctx context.Context, strategyAddr gethcommon.Address, @@ -208,6 +220,9 @@ func (r *ChainReader) GetStrategyAndUnderlyingERC20Token( return contractStrategy, contractUnderlyingToken, underlyingTokenAddr, nil } +// Returns the shares an operator has in a given strategy. +// Can return an error if the `DelegationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorSharesInStrategy( ctx context.Context, operatorAddr gethcommon.Address, @@ -224,6 +239,10 @@ func (r *ChainReader) GetOperatorSharesInStrategy( ) } +// Returns the digest hash to be signed by the operator's delegation approver to be used +// when delegating to an operator. +// Can return an error if the `DelegationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) CalculateDelegationApprovalDigestHash( ctx context.Context, staker gethcommon.Address, @@ -246,6 +265,9 @@ func (r *ChainReader) CalculateDelegationApprovalDigestHash( ) } +// Returns the digest hash to be signed by an operator to register with an AVS. +// Can return an error if the `AVSDirectory` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) CalculateOperatorAVSRegistrationDigestHash( ctx context.Context, operator gethcommon.Address, @@ -266,6 +288,9 @@ func (r *ChainReader) CalculateOperatorAVSRegistrationDigestHash( ) } +// Returns the number of distribution roots published. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetDistributionRootsLength(ctx context.Context) (*big.Int, error) { if r.rewardsCoordinator == nil { return nil, errors.New("RewardsCoordinator contract not provided") @@ -274,6 +299,9 @@ func (r *ChainReader) GetDistributionRootsLength(ctx context.Context) (*big.Int, return r.rewardsCoordinator.GetDistributionRootsLength(&bind.CallOpts{Context: ctx}) } +// Returns the timestamp until which rewards submissions have been calculated. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) CurrRewardsCalculationEndTimestamp(ctx context.Context) (uint32, error) { if r.rewardsCoordinator == nil { return 0, errors.New("RewardsCoordinator contract not provided") @@ -282,6 +310,9 @@ func (r *ChainReader) CurrRewardsCalculationEndTimestamp(ctx context.Context) (u return r.rewardsCoordinator.CurrRewardsCalculationEndTimestamp(&bind.CallOpts{Context: ctx}) } +// Returns the latest root that can be claimed against. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetCurrentClaimableDistributionRoot( ctx context.Context, ) (rewardscoordinator.IRewardsCoordinatorTypesDistributionRoot, error) { @@ -294,6 +325,9 @@ func (r *ChainReader) GetCurrentClaimableDistributionRoot( return r.rewardsCoordinator.GetCurrentClaimableDistributionRoot(&bind.CallOpts{Context: ctx}) } +// Returns the index of the latest root that can be claimed against. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetRootIndexFromHash( ctx context.Context, rootHash [32]byte, @@ -305,6 +339,9 @@ func (r *ChainReader) GetRootIndexFromHash( return r.rewardsCoordinator.GetRootIndexFromHash(&bind.CallOpts{Context: ctx}, rootHash) } +// Returns the number of `token` tokens the `earner` has claimed. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetCumulativeClaimed( ctx context.Context, earner gethcommon.Address, @@ -317,6 +354,10 @@ func (r *ChainReader) GetCumulativeClaimed( return r.rewardsCoordinator.CumulativeClaimed(&bind.CallOpts{Context: ctx}, earner, token) } +// Returns `true` if the claim would currently pass the check in +// `ChainWriter.ProcessClaims` or return an error if invalid. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) CheckClaim( ctx context.Context, claim rewardscoordinator.IRewardsCoordinatorTypesRewardsMerkleClaim, @@ -325,9 +366,13 @@ func (r *ChainReader) CheckClaim( return false, errors.New("RewardsCoordinator contract not provided") } + // TODO: this returns an error if the claim is invalid. We map this error to false instead return r.rewardsCoordinator.CheckClaim(&bind.CallOpts{Context: ctx}, claim) } +// Returns the split configured by the `operator` for the `avs`. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorAVSSplit( ctx context.Context, operator gethcommon.Address, @@ -340,6 +385,9 @@ func (r *ChainReader) GetOperatorAVSSplit( return r.rewardsCoordinator.GetOperatorAVSSplit(&bind.CallOpts{Context: ctx}, operator, avs) } +// Returns the split configured by the `operator` for Programmatic Incentives. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorPISplit( ctx context.Context, operator gethcommon.Address, @@ -351,6 +399,9 @@ func (r *ChainReader) GetOperatorPISplit( return r.rewardsCoordinator.GetOperatorPISplit(&bind.CallOpts{Context: ctx}, operator) } +// Returns the split for an operator in an operator set. +// Can return an error if the `RewardsCoordinator` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorSetSplit( ctx context.Context, operator gethcommon.Address, @@ -363,6 +414,10 @@ func (r *ChainReader) GetOperatorSetSplit( return r.rewardsCoordinator.GetOperatorSetSplit(&bind.CallOpts{Context: ctx}, operator, operatorSet) } +// Returns the amount of magnitude on a strategy not currently allocated to any operator set, +// by an operator. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetAllocatableMagnitude( ctx context.Context, operatorAddress gethcommon.Address, @@ -375,6 +430,9 @@ func (r *ChainReader) GetAllocatableMagnitude( return r.allocationManager.GetAllocatableMagnitude(&bind.CallOpts{Context: ctx}, operatorAddress, strategyAddress) } +// Returns the maximum magnitude an operator can allocate for the given strategies. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetMaxMagnitudes( ctx context.Context, operatorAddress gethcommon.Address, @@ -387,6 +445,9 @@ func (r *ChainReader) GetMaxMagnitudes( return r.allocationManager.GetMaxMagnitudes0(&bind.CallOpts{Context: ctx}, operatorAddress, strategyAddresses) } +// Returns the allocation info of a given operator and strategy. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetAllocationInfo( ctx context.Context, operatorAddress gethcommon.Address, @@ -420,6 +481,9 @@ func (r *ChainReader) GetAllocationInfo( return allocationsInfo, nil } +// Returns the shares an operator has delegated to them on a strategy. +// Can return an error if the `DelegationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorShares( ctx context.Context, operatorAddress gethcommon.Address, @@ -434,6 +498,9 @@ func (r *ChainReader) GetOperatorShares( }, operatorAddress, strategyAddresses) } +// Returns the shares that a set of operators have delegated to them in a set of strategies. +// Can return an error if the `DelegationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorsShares( ctx context.Context, operatorAddresses []gethcommon.Address, @@ -445,8 +512,10 @@ func (r *ChainReader) GetOperatorsShares( return r.delegationManager.GetOperatorsShares(&bind.CallOpts{Context: ctx}, operatorAddresses, strategyAddresses) } -// GetNumOperatorSetsForOperator returns the number of operator sets that an operator is part of -// Doesn't include M2 AVSs +// Returns the number of operator sets that an operator is part of. +// This doesn't include M2 quorums. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetNumOperatorSetsForOperator( ctx context.Context, operatorAddress gethcommon.Address, @@ -461,8 +530,10 @@ func (r *ChainReader) GetNumOperatorSetsForOperator( return big.NewInt(int64(len(opSets))), nil } -// GetOperatorSetsForOperator returns the list of operator sets that an operator is part of -// Doesn't include M2 AVSs +// Returns the list of operator sets the operator has current or pending allocations/deallocations in. +// This doesn't include M2 quorums. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorSetsForOperator( ctx context.Context, operatorAddress gethcommon.Address, @@ -475,7 +546,9 @@ func (r *ChainReader) GetOperatorSetsForOperator( return r.allocationManager.GetAllocatedSets(&bind.CallOpts{Context: ctx}, operatorAddress) } -// IsOperatorRegisteredWithOperatorSet returns if an operator is registered with a specific operator set +// Returns `true` if an operator is registered with a specific operator set or M2 quorum. +// Can return an error if the `AVSDirectory` or `AllocationManager` contract addresses were +// not provided, or due to errors in the underlying contract call. func (r *ChainReader) IsOperatorRegisteredWithOperatorSet( ctx context.Context, operatorAddress gethcommon.Address, @@ -513,8 +586,10 @@ func (r *ChainReader) IsOperatorRegisteredWithOperatorSet( } } -// GetOperatorsForOperatorSet returns the list of operators in a specific operator set -// Not supported for M2 AVSs +// Returns the list of operators in a specific operator set. +// Not supported for M2 AVSs. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetOperatorsForOperatorSet( ctx context.Context, operatorSet allocationmanager.OperatorSet, @@ -530,7 +605,10 @@ func (r *ChainReader) GetOperatorsForOperatorSet( } } -// GetNumOperatorsForOperatorSet returns the number of operators in a specific operator set +// Returns the number of operators in a specific operator set. +// Not supported for M2 AVSs. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetNumOperatorsForOperatorSet( ctx context.Context, operatorSet allocationmanager.OperatorSet, @@ -546,8 +624,10 @@ func (r *ChainReader) GetNumOperatorsForOperatorSet( } } -// GetStrategiesForOperatorSet returns the list of strategies that an operator set takes into account -// Not supported for M2 AVSs +// Returns the list of strategies that an operator set takes into account. +// Not supported for M2 AVSs. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetStrategiesForOperatorSet( ctx context.Context, operatorSet allocationmanager.OperatorSet, @@ -563,6 +643,10 @@ func (r *ChainReader) GetStrategiesForOperatorSet( } } +// Returns a list of the number of shares slashable by the operator set +// for each of the given strategies. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetSlashableShares( ctx context.Context, operatorAddress gethcommon.Address, @@ -603,9 +687,11 @@ func (r *ChainReader) GetSlashableShares( return slashableShareStrategyMap, nil } -// GetSlashableSharesForOperatorSets returns the strategies the operatorSets take into account, their +// Returns the strategies the `operatorSets` take into account, their // operators, and the minimum amount of shares that are slashable by the operatorSets. -// Not supported for M2 AVSs +// Not supported for M2 AVSs. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetSlashableSharesForOperatorSets( ctx context.Context, operatorSets []allocationmanager.OperatorSet, @@ -618,11 +704,13 @@ func (r *ChainReader) GetSlashableSharesForOperatorSets( return r.GetSlashableSharesForOperatorSetsBefore(ctx, operatorSets, uint32(currentBlock)) } -// GetSlashableSharesForOperatorSetsBefore returns the strategies the operatorSets take into account, their +// Returns the strategies the `operatorSets` take into account, their // operators, and the minimum amount of shares slashable by the -// operatorSets before a given timestamp. -// Timestamp must be in the future. Used to underestimate future slashable stake. -// Not supported for M2 AVSs +// `operatorSets` before a given timestamp. +// Timestamp must be in the future. Used to estimate future slashable stake. +// Not supported for M2 AVSs. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetSlashableSharesForOperatorSetsBefore( ctx context.Context, operatorSets []allocationmanager.OperatorSet, @@ -667,6 +755,11 @@ func (r *ChainReader) GetSlashableSharesForOperatorSetsBefore( return operatorSetStakes, nil } +// Returns the time in blocks between an operator allocating slashable magnitude +// and the magnitude becoming slashable. +// Returns an error if the operator has not set an allocation delay. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetAllocationDelay( ctx context.Context, operatorAddress gethcommon.Address, @@ -685,6 +778,9 @@ func (r *ChainReader) GetAllocationDelay( return delay, nil } +// Returns a list of all operator sets the operator is registered for. +// Can return an error if the `AllocationManager` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) GetRegisteredSets( ctx context.Context, operatorAddress gethcommon.Address, @@ -695,6 +791,10 @@ func (r *ChainReader) GetRegisteredSets( return r.allocationManager.GetRegisteredSets(&bind.CallOpts{Context: ctx}, operatorAddress) } +// Returns `true` if `appointeeAddress` has permission to call the function with the given +// `selector` on the `target` contract, on behalf of `accountAddress`, and `false` otherwise. +// Can return an error if the `PermissionController` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) CanCall( ctx context.Context, accountAddress gethcommon.Address, @@ -716,6 +816,10 @@ func (r *ChainReader) CanCall( return canCall, nil } +// Returns the list of appointees for a given account, target and function selector. +// Note that this doesn't include any of the appointed admins. +// Can return an error if the `PermissionController` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) ListAppointees( ctx context.Context, accountAddress gethcommon.Address, @@ -735,6 +839,9 @@ func (r *ChainReader) ListAppointees( return appointees, nil } +// Returns the list of permissions of an appointee for a given account. +// Can return an error if the `PermissionController` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) ListAppointeePermissions( ctx context.Context, accountAddress gethcommon.Address, @@ -752,6 +859,9 @@ func (r *ChainReader) ListAppointeePermissions( return targets, selectors, nil } +// Returns the pending admins of an account. +// Can return an error if the `PermissionController` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) ListPendingAdmins( ctx context.Context, accountAddress gethcommon.Address, @@ -764,6 +874,9 @@ func (r *ChainReader) ListPendingAdmins( return pendingAdmins, nil } +// Returns the admins of an account. +// Can return an error if the `PermissionController` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) ListAdmins( ctx context.Context, accountAddress gethcommon.Address, @@ -776,6 +889,9 @@ func (r *ChainReader) ListAdmins( return pendingAdmins, nil } +// Returns `true` if `pendingAdminAddress` is a pending admin for `accountAddress`, `false` otherwise. +// Can return an error if the `PermissionController` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) IsPendingAdmin( ctx context.Context, accountAddress gethcommon.Address, @@ -793,6 +909,9 @@ func (r *ChainReader) IsPendingAdmin( return isPendingAdmin, nil } +// Returns `true` if `adminAddress` is an admin of `accountAddress`. +// Can return an error if the `PermissionController` contract address was not provided, or due to +// errors in the underlying contract call. func (r *ChainReader) IsAdmin( ctx context.Context, accountAddress gethcommon.Address,