Merge pull request #808 from onflow/peter/update-access-interface

Update access interface to align with latest changes
onflow · Mar 11, 2025 · b9ce455 · b9ce455
2 parents fdd2e42 + 3cf648e
commit b9ce455
Show file tree

Hide file tree

Showing 7 changed files with 1,086 additions and 40 deletions.
diff --git a/access/client.go b/access/client.go
@@ -37,57 +37,90 @@ type Client interface {
 	// Ping is used to check if the access node is alive and healthy.
 	Ping(ctx context.Context) error
 
-	// GetNetworkParameters gets the network parameters.
+	// GetNetworkParameters returns the network parameters.
 	GetNetworkParameters(ctx context.Context) (*flow.NetworkParameters, error)
 
-	// GetNodeVersionInfo gets the node information about the network.
+	// GetNodeVersionInfo returns the node information about the network.
 	GetNodeVersionInfo(ctx context.Context) (*flow.NodeVersionInfo, error)
 
-	// GetLatestBlockHeader gets the latest sealed or unsealed block header.
+	// GetLatestBlockHeader returns the latest sealed or unsealed block header.
 	GetLatestBlockHeader(ctx context.Context, isSealed bool) (*flow.BlockHeader, error)
 
-	// GetBlockHeaderByID gets a block header by ID.
+	// GetBlockHeaderByID returns a block header by ID.
 	GetBlockHeaderByID(ctx context.Context, blockID flow.Identifier) (*flow.BlockHeader, error)
 
-	// GetBlockHeaderByHeight gets a block header by height.
+	// GetBlockHeaderByHeight returns a block header by height.
 	GetBlockHeaderByHeight(ctx context.Context, height uint64) (*flow.BlockHeader, error)
 
-	// GetLatestBlock gets the full payload of the latest sealed or unsealed block.
+	// GetLatestBlock returns the full payload of the latest sealed or unsealed block.
 	GetLatestBlock(ctx context.Context, isSealed bool) (*flow.Block, error)
 
-	// GetBlockByID gets a full block by ID.
+	// GetBlockByID returns a full block by ID.
 	GetBlockByID(ctx context.Context, blockID flow.Identifier) (*flow.Block, error)
 
-	// GetBlockByHeight gets a full block by height.
+	// GetBlockByHeight returns a full block by height.
 	GetBlockByHeight(ctx context.Context, height uint64) (*flow.Block, error)
 
-	// GetCollection gets a collection by ID.
+	// GetCollection returns a collection by ID.
 	GetCollection(ctx context.Context, colID flow.Identifier) (*flow.Collection, error)
 
+	// GetCollectionByID returns a collection by ID.
+	GetCollectionByID(ctx context.Context, id flow.Identifier) (*flow.Collection, error)
+
+	// GetFullCollectionByID returns a full collection including transaction bodies by ID.
+	GetFullCollectionByID(ctx context.Context, id flow.Identifier) (*flow.FullCollection, error)
+
 	// SendTransaction submits a transaction to the network.
 	SendTransaction(ctx context.Context, tx flow.Transaction) error
 
-	// GetTransaction gets a transaction by ID.
+	// GetTransaction returns a transaction by ID.
 	GetTransaction(ctx context.Context, txID flow.Identifier) (*flow.Transaction, error)
 
-	// GetTransactionsByBlockID gets all the transactions for a specified block.
+	// GetTransactionsByBlockID returns all the transactions for a specified block.
 	GetTransactionsByBlockID(ctx context.Context, blockID flow.Identifier) ([]*flow.Transaction, error)
 
-	// GetTransactionResult gets the result of a transaction.
+	// GetTransactionResult returns the result of a transaction.
 	GetTransactionResult(ctx context.Context, txID flow.Identifier) (*flow.TransactionResult, error)
 
-	// GetTransactionResultsByBlockID gets all the transaction results for a specified block.
+	// GetTransactionResultByIndex returns a transaction result by transaction index for the given block ID.
+	GetTransactionResultByIndex(ctx context.Context, blockID flow.Identifier, index uint32) (*flow.TransactionResult, error)
+
+	// GetTransactionResultsByBlockID returns all the transaction results for a specified block.
 	GetTransactionResultsByBlockID(ctx context.Context, blockID flow.Identifier) ([]*flow.TransactionResult, error)
 
+	// GetSystemTransaction returns the system transaction for the given block ID.
+	GetSystemTransaction(ctx context.Context, blockID flow.Identifier) (*flow.Transaction, error)
+
+	// GetSystemTransactionResult returns the transaction result of the system transaction for the given block ID.
+	GetSystemTransactionResult(ctx context.Context, blockID flow.Identifier) (*flow.TransactionResult, error)
+
 	// GetAccount is an alias for GetAccountAtLatestBlock.
 	GetAccount(ctx context.Context, address flow.Address) (*flow.Account, error)
 
-	// GetAccountAtLatestBlock gets an account by address at the latest sealed block.
+	// GetAccountAtLatestBlock returns an account by address at the latest sealed block.
 	GetAccountAtLatestBlock(ctx context.Context, address flow.Address) (*flow.Account, error)
 
-	// GetAccountAtBlockHeight gets an account by address at the given block height
+	// GetAccountAtBlockHeight returns an account by address at the given block height
 	GetAccountAtBlockHeight(ctx context.Context, address flow.Address, blockHeight uint64) (*flow.Account, error)
 
+	// GetAccountBalanceAtLatestBlock returns the balance of an account at the latest sealed block.
+	GetAccountBalanceAtLatestBlock(ctx context.Context, address flow.Address) (uint64, error)
+
+	// GetAccountBalanceAtBlockHeight returns the balance of an account at the given block height.
+	GetAccountBalanceAtBlockHeight(ctx context.Context, address flow.Address, blockHeight uint64) (uint64, error)
+
+	// GetAccountKeyAtLatestBlock returns the account key with the provided index at the latest sealed block.
+	GetAccountKeyAtLatestBlock(ctx context.Context, address flow.Address, keyIndex uint32) (*flow.AccountKey, error)
+
+	// GetAccountKeyAtBlockHeight returns the account key with the provided index at the given block height.
+	GetAccountKeyAtBlockHeight(ctx context.Context, address flow.Address, keyIndex uint32, height uint64) (*flow.AccountKey, error)
+
+	// GetAccountKeysAtLatestBlock returns all account keys at the latest sealed block.
+	GetAccountKeysAtLatestBlock(ctx context.Context, address flow.Address) ([]*flow.AccountKey, error)
+
+	// GetAccountKeysAtBlockHeight returns all account keys at the given block height.
+	GetAccountKeysAtBlockHeight(ctx context.Context, address flow.Address, height uint64) ([]*flow.AccountKey, error)
+
 	// ExecuteScriptAtLatestBlock executes a read-only Cadence script against the latest sealed execution state.
 	ExecuteScriptAtLatestBlock(ctx context.Context, script []byte, arguments []cadence.Value) (cadence.Value, error)
 
@@ -97,34 +130,167 @@ type Client interface {
 	// ExecuteScriptAtBlockHeight executes a ready-only Cadence script against the execution state at the given block height.
 	ExecuteScriptAtBlockHeight(ctx context.Context, height uint64, script []byte, arguments []cadence.Value) (cadence.Value, error)
 
-	// GetEventsForHeightRange retrieves events for all sealed blocks between the start and end block heights (inclusive) with the given type.
+	// GetEventsForHeightRange returns events for all sealed blocks between the start and end block heights (inclusive) with the given type.
 	GetEventsForHeightRange(ctx context.Context, eventType string, startHeight uint64, endHeight uint64) ([]flow.BlockEvents, error)
 
-	// GetEventsForBlockIDs retrieves events with the given type from the specified block IDs.
+	// GetEventsForBlockIDs returns events with the given type from the specified block IDs.
 	GetEventsForBlockIDs(ctx context.Context, eventType string, blockIDs []flow.Identifier) ([]flow.BlockEvents, error)
 
-	// GetLatestProtocolStateSnapshot retrieves the latest snapshot of the protocol
-	// state in serialized form. This is used to generate a root snapshot file
-	// used by Flow nodes to bootstrap their local protocol state database.
+	// GetLatestProtocolStateSnapshot returns the protocol state snapshot in serialized form at latest sealed block.
+	// This is used to generate a root snapshot file used by Flow nodes to bootstrap their local protocol state database.
 	GetLatestProtocolStateSnapshot(ctx context.Context) ([]byte, error)
 
-	// GetExecutionResultForBlockID gets the execution results at the block ID.
+	// GetProtocolStateSnapshotByBlockID returns the protocol state snapshot in serialized form at the given block ID.
+	// This is used to generate a root snapshot file used by Flow nodes to bootstrap their local protocol state database.
+	GetProtocolStateSnapshotByBlockID(ctx context.Context, blockID flow.Identifier) ([]byte, error)
+
+	// GetProtocolStateSnapshotByHeight returns the protocol state snapshot in serialized form at the given block height.
+	// This is used to generate a root snapshot file used by Flow nodes to bootstrap their local protocol state database.
+	GetProtocolStateSnapshotByHeight(ctx context.Context, blockHeight uint64) ([]byte, error)
+
+	// GetExecutionResultByID returns the execution result by ID.
+	GetExecutionResultByID(ctx context.Context, id flow.Identifier) (*flow.ExecutionResult, error)
+
+	// GetExecutionResultForBlockID returns the execution results at the block ID.
 	GetExecutionResultForBlockID(ctx context.Context, blockID flow.Identifier) (*flow.ExecutionResult, error)
 
 	// GetExecutionDataByBlockID returns execution data for a specific block ID.
 	GetExecutionDataByBlockID(ctx context.Context, blockID flow.Identifier) (*flow.ExecutionData, error)
 
 	// SubscribeExecutionDataByBlockID subscribes to execution data updates starting at the given block ID.
-	SubscribeExecutionDataByBlockID(ctx context.Context, startBlockID flow.Identifier) (<-chan *flow.ExecutionDataStreamResponse, <-chan error, error)
+	SubscribeExecutionDataByBlockID(
+		ctx context.Context,
+		startBlockID flow.Identifier,
+	) (<-chan *flow.ExecutionDataStreamResponse, <-chan error, error)
 
 	// SubscribeExecutionDataByBlockHeight subscribes to execution data updates starting at the given block height.
-	SubscribeExecutionDataByBlockHeight(ctx context.Context, startHeight uint64) (<-chan *flow.ExecutionDataStreamResponse, <-chan error, error)
+	SubscribeExecutionDataByBlockHeight(
+		ctx context.Context,
+		startHeight uint64,
+	) (<-chan *flow.ExecutionDataStreamResponse, <-chan error, error)
 
 	// SubscribeEventsByBlockID subscribes to events starting at the given block ID.
-	SubscribeEventsByBlockID(ctx context.Context, startBlockID flow.Identifier, filter flow.EventFilter, opts ...SubscribeOption) (<-chan flow.BlockEvents, <-chan error, error)
+	SubscribeEventsByBlockID(
+		ctx context.Context,
+		startBlockID flow.Identifier,
+		filter flow.EventFilter,
+		opts ...SubscribeOption,
+	) (<-chan flow.BlockEvents, <-chan error, error)
 
 	// SubscribeEventsByBlockHeight subscribes to events starting at the given block height.
-	SubscribeEventsByBlockHeight(ctx context.Context, startHeight uint64, filter flow.EventFilter, opts ...SubscribeOption) (<-chan flow.BlockEvents, <-chan error, error)
+	SubscribeEventsByBlockHeight(
+		ctx context.Context,
+		startHeight uint64,
+		filter flow.EventFilter,
+		opts ...SubscribeOption,
+	) (<-chan flow.BlockEvents, <-chan error, error)
+
+	// SubscribeBlockDigestsFromStartBlockID subscribes to block digests with the given status
+	// starting at the given block ID.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlockDigestsFromStartBlockID(
+		ctx context.Context,
+		startBlockID flow.Identifier,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.BlockDigest, <-chan error, error)
+
+	// SubscribeBlockDigestsFromStartHeight subscribes to block digests with the given status
+	// starting at the given block height.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlockDigestsFromStartHeight(
+		ctx context.Context,
+		startHeight uint64,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.BlockDigest, <-chan error, error)
+
+	// SubscribeBlockDigestsFromLatest subscribes to block digests with the given status
+	// starting at the latest block.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlockDigestsFromLatest(
+		ctx context.Context,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.BlockDigest, <-chan error, error)
+
+	// SubscribeBlocksFromStartBlockID subscribes to blocks with the given status starting at the
+	// given block ID.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlocksFromStartBlockID(
+		ctx context.Context,
+		startBlockID flow.Identifier,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.Block, <-chan error, error)
+
+	// SubscribeBlocksFromStartHeight subscribes to blocks with the given status starting at the
+	// given block height.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlocksFromStartHeight(
+		ctx context.Context,
+		startHeight uint64,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.Block, <-chan error, error)
+
+	// SubscribeBlocksFromLatest subscribes to blocks with the given status starting at the latest block.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlocksFromLatest(
+		ctx context.Context,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.Block, <-chan error, error)
+
+	// SubscribeBlockHeadersFromStartBlockID subscribes to block headers with the given status starting
+	// at the given block ID.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlockHeadersFromStartBlockID(
+		ctx context.Context,
+		startBlockID flow.Identifier,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.BlockHeader, <-chan error, error)
+
+	// SubscribeBlockHeadersFromStartHeight subscribes to block headers with the given status starting
+	// at the given block height.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlockHeadersFromStartHeight(
+		ctx context.Context,
+		startHeight uint64,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.BlockHeader, <-chan error, error)
+
+	// SubscribeBlockHeadersFromLatest subscribes to block headers with the given status starting
+	// at the latest block.
+	// The status may be either flow.BlockStatusFinalized or flow.BlockStatusSealed
+	SubscribeBlockHeadersFromLatest(
+		ctx context.Context,
+		blockStatus flow.BlockStatus,
+	) (<-chan *flow.BlockHeader, <-chan error, error)
+
+	// SubscribeAccountStatusesFromStartHeight subscribes to account status events starting at the
+	// given block height.
+	SubscribeAccountStatusesFromStartHeight(
+		ctx context.Context,
+		startBlockHeight uint64,
+		filter flow.AccountStatusFilter,
+	) (<-chan *flow.AccountStatus, <-chan error, error)
+
+	// SubscribeAccountStatusesFromStartBlockID subscribes to account status events starting at the
+	// given block ID.
+	SubscribeAccountStatusesFromStartBlockID(
+		ctx context.Context,
+		startBlockID flow.Identifier,
+		filter flow.AccountStatusFilter,
+	) (<-chan *flow.AccountStatus, <-chan error, error)
+
+	// SubscribeAccountStatusesFromLatestBlock subscribes to account status events starting at the
+	// latest block.
+	SubscribeAccountStatusesFromLatestBlock(
+		ctx context.Context,
+		filter flow.AccountStatusFilter,
+	) (<-chan *flow.AccountStatus, <-chan error, error)
+
+	// SendAndSubscribeTransactionStatuses submits a transaction to the network and subscribes to the
+	// transaction status updates.
+	SendAndSubscribeTransactionStatuses(
+		ctx context.Context,
+		tx flow.Transaction,
+	) (<-chan *flow.TransactionResult, <-chan error, error)
 
 	// Close stops the client connection to the access node.
 	Close() error

diff --git a/access/grpc/client.go b/access/grpc/client.go
@@ -391,7 +391,7 @@ func (c *Client) SubscribeBlockHeadersFromStartHeight(
 	return c.grpc.SubscribeBlockHeadersFromStartHeight(ctx, startHeight, blockStatus)
 }
 
-func (c *Client) SubscribeBlocksHeadersFromLatest(
+func (c *Client) SubscribeBlockHeadersFromLatest(
 	ctx context.Context,
 	blockStatus flow.BlockStatus,
 ) (<-chan *flow.BlockHeader, <-chan error, error) {

diff --git a/access/grpc/grpc.go b/access/grpc/grpc.go
@@ -657,13 +657,14 @@ func (c *BaseClient) GetAccountKeyAtLatestBlock(
 	ctx context.Context,
 	address flow.Address,
 	keyIndex uint32,
+	opts ...grpc.CallOption,
 ) (*flow.AccountKey, error) {
 	request := &access.GetAccountKeyAtLatestBlockRequest{
 		Address: address.Bytes(),
 		Index:   keyIndex,
 	}
 
-	response, err := c.rpcClient.GetAccountKeyAtLatestBlock(ctx, request)
+	response, err := c.rpcClient.GetAccountKeyAtLatestBlock(ctx, request, opts...)
 	if err != nil {
 		return nil, newRPCError(err)
 	}
@@ -681,14 +682,15 @@ func (c *BaseClient) GetAccountKeyAtBlockHeight(
 	address flow.Address,
 	keyIndex uint32,
 	height uint64,
+	opts ...grpc.CallOption,
 ) (*flow.AccountKey, error) {
 	request := &access.GetAccountKeyAtBlockHeightRequest{
 		Address:     address.Bytes(),
 		Index:       keyIndex,
 		BlockHeight: height,
 	}
 
-	response, err := c.rpcClient.GetAccountKeyAtBlockHeight(ctx, request)
+	response, err := c.rpcClient.GetAccountKeyAtBlockHeight(ctx, request, opts...)
 	if err != nil {
 		return nil, newRPCError(err)
 	}
@@ -704,12 +706,13 @@ func (c *BaseClient) GetAccountKeyAtBlockHeight(
 func (c *BaseClient) GetAccountKeysAtLatestBlock(
 	ctx context.Context,
 	address flow.Address,
+	opts ...grpc.CallOption,
 ) ([]*flow.AccountKey, error) {
 	request := &access.GetAccountKeysAtLatestBlockRequest{
 		Address: address.Bytes(),
 	}
 
-	response, err := c.rpcClient.GetAccountKeysAtLatestBlock(ctx, request)
+	response, err := c.rpcClient.GetAccountKeysAtLatestBlock(ctx, request, opts...)
 	if err != nil {
 		return nil, newRPCError(err)
 	}
@@ -726,13 +729,14 @@ func (c *BaseClient) GetAccountKeysAtBlockHeight(
 	ctx context.Context,
 	address flow.Address,
 	height uint64,
+	opts ...grpc.CallOption,
 ) ([]*flow.AccountKey, error) {
 	request := &access.GetAccountKeysAtBlockHeightRequest{
 		Address:     address.Bytes(),
 		BlockHeight: height,
 	}
 
-	response, err := c.rpcClient.GetAccountKeysAtBlockHeight(ctx, request)
+	response, err := c.rpcClient.GetAccountKeysAtBlockHeight(ctx, request, opts...)
 	if err != nil {
 		return nil, newRPCError(err)
 	}