gRPC protocol

Protocol Documentation

Table of Contents

• github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/entity_filters.proto

  • AddressFilter
  • DeclareFilters
  • DeployAccountFilters
  • DeployAccountFilters.ParsedCalldataEntry
  • DeployFilters
  • DeployFilters.ParsedCalldataEntry
  • EventFilter
  • EventFilter.ParsedDataEntry
  • FeeFilter
  • FeeFilter.ParsedCalldataEntry
  • InternalFilter
  • InternalFilter.ParsedCalldataEntry
  • InvokeFilters
  • InvokeFilters.ParsedCalldataEntry
  • L1HandlerFilter
  • L1HandlerFilter.ParsedCalldataEntry
  • MessageFilter
  • StorageDiffFilter
  • TokenBalanceFilter
  • TokenFilter
  • TransferFilter

• github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/enum.proto

  • CallType
  • EntrypointType
  • Status

• github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/filters.proto

  • BetweenInteger
  • BytesArray
  • BytesFilter
  • EnumFilter
  • EqualityFilter
  • EqualityIntegerFilter
  • IntegerArray
  • IntegerFilter
  • StringArray
  • StringFilter
  • TimeFilter

• github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/indexer.proto

  • Bytes

  • JsonSchema

  • JsonSchemaItem

  • SubscribeRequest

  • Subscription

  • IndexerService

• github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/response.proto

  • Address
  • Block
  • Declare
  • Deploy
  • DeployAccount
  • EndOfBlock
  • Event
  • Fee
  • Internal
  • Invoke
  • L1Handler
  • StarknetMessage
  • StorageDiff
  • Token
  • TokenBalance
  • Transfer

• Scalar Value Types

Top

github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/entity_filters.proto

AddressFilter

Field	Type	Label	Description
id	IntegerFilter
only_starknet	bool
height	IntegerFilter

DeclareFilters

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
status	EnumFilter
version	EnumFilter
id	IntegerFilter

DeployAccountFilters

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
status	EnumFilter
class	BytesFilter
parsed_calldata	DeployAccountFilters.ParsedCalldataEntry	repeated
id	IntegerFilter

DeployAccountFilters.ParsedCalldataEntry

Field	Type	Label	Description
key	string
value	string

DeployFilters

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
status	EnumFilter
class	BytesFilter
parsed_calldata	DeployFilters.ParsedCalldataEntry	repeated
id	IntegerFilter

DeployFilters.ParsedCalldataEntry

Field	Type	Label	Description
key	string
value	string

EventFilter

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
contract	BytesFilter
from	BytesFilter
name	StringFilter
parsed_data	EventFilter.ParsedDataEntry	repeated
id	IntegerFilter

EventFilter.ParsedDataEntry

Field	Type	Label	Description
key	string
value	string

FeeFilter

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
status	EnumFilter
contract	BytesFilter
caller	BytesFilter
class	BytesFilter
selector	EqualityFilter
entrypoint	StringFilter
entrypoint_type	EnumFilter
call_type	EnumFilter
parsed_calldata	FeeFilter.ParsedCalldataEntry	repeated
id	IntegerFilter

FeeFilter.ParsedCalldataEntry

Field	Type	Label	Description
key	string
value	string

InternalFilter

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
status	EnumFilter
contract	BytesFilter
caller	BytesFilter
class	BytesFilter
selector	EqualityFilter
entrypoint	StringFilter
entrypoint_type	EnumFilter
call_type	EnumFilter
parsed_calldata	InternalFilter.ParsedCalldataEntry	repeated
id	IntegerFilter

InternalFilter.ParsedCalldataEntry

Field	Type	Label	Description
key	string
value	string

InvokeFilters

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
status	EnumFilter
version	EnumFilter
contract	BytesFilter
selector	EqualityFilter
entrypoint	StringFilter
parsed_calldata	InvokeFilters.ParsedCalldataEntry	repeated
id	IntegerFilter

InvokeFilters.ParsedCalldataEntry

Field	Type	Label	Description
key	string
value	string

L1HandlerFilter

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
status	EnumFilter
contract	BytesFilter
selector	EqualityFilter
entrypoint	StringFilter
parsed_calldata	L1HandlerFilter.ParsedCalldataEntry	repeated
id	IntegerFilter

L1HandlerFilter.ParsedCalldataEntry

Field	Type	Label	Description
key	string
value	string

MessageFilter

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
contract	BytesFilter
from	BytesFilter
to	BytesFilter
selector	EqualityFilter
id	IntegerFilter

StorageDiffFilter

Field	Type	Label	Description
height	IntegerFilter
contract	BytesFilter
key	EqualityFilter
id	IntegerFilter

TokenBalanceFilter

Field	Type	Label	Description
owner	BytesFilter
contract	BytesFilter
token_id	StringFilter

TokenFilter

Field	Type	Label	Description
contract	BytesFilter
owner	BytesFilter
type	EnumFilter

TransferFilter

Field	Type	Label	Description
height	IntegerFilter
time	TimeFilter
contract	BytesFilter
from	BytesFilter
to	BytesFilter
token_id	StringFilter
id	IntegerFilter

Top

github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/enum.proto

CallType

Call type of transactions

Name	Number	Description
CALL_TYPE_RESERVED	0	unused
CALL_TYPE_UNKNOWN	1	used only if entity has unknown call type for the system
CALL_TYPE_CALL	2	call
CALL_TYPE_DELEGATE	3	delegate call

EntrypointType

Entrypoint type of transactions

Name	Number	Description
ENTRYPOINT_TYPE_RESERVED	0	unused
ENTRYPOINT_TYPE_UNKNOWN	1	used only if entity has unknown entrypoint type for the system
ENTRYPOINT_TYPE_EXTERNAL	2	external entrypoint type
ENTRYPOINT_TYPE_CONSTRUCTOR	3	constructor entrypoint type
ENTRYPOINT_TYPE_L1_HANDLER	4	l1 handler entrypoint type

Status

Block status

Name	Number	Description
STATUS_RESERVED	0	unused
STATUS_UNKNOWN	1	used only if entity has unknown status for the system
STATUS_NOT_RECEIVED	2	not received
STATUS_RECEIVED	3	received
STATUS_PENDING	4	pending
STATUS_REJECTED	5	rejected
STATUS_ACCEPTED_ON_L2	6	accepted on L2
STATUS_ACCEPTED_ON_L1	7	accepted on L1

Top

github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/filters.proto

BetweenInteger

Between unsigned interger filter. Equals to SQL expression: x BETWEEN from AND to.

Field	Type	Label	Description
from	uint64		from value
to	uint64		to value

BytesArray

Wrapper over bytes array for using repeated option

Field	Type	Label	Description
arr	bytes	repeated	array

BytesFilter

Set of bytes filters

Field	Type	Label	Description
eq	bytes		equals
in	BytesArray		check the value is in array x IN (\x00, \x0010)

EnumFilter

Set of filters for enumerations

Field	Type	Label	Description
eq	uint64		equals
neq	uint64		not equals
in	IntegerArray		check the value is in array x IN (1,2,3,4)
notin	IntegerArray		check the value is not in array x NOT IN (1,2,3,4)

EqualityFilter

Equality filters

Field	Type	Label	Description
eq	string		equals
neq	string		not equals

EqualityIntegerFilter

Equality filters for integer values

Field	Type	Label	Description
eq	uint64		equals
neq	uint64		not equals

IntegerArray

Wrapper over integer array for using repeated option

Field	Type	Label	Description
arr	uint64	repeated	array

IntegerFilter

Set of integer filters

Field	Type	Label	Description
gt	uint64		greater than
gte	uint64		greater than or equals
lt	uint64		less than
lte	uint64		less than or equals
eq	uint64		equals
neq	uint64		not equals
between	BetweenInteger		between

StringArray

Wrapper over string array for using repeated option

Field	Type	Label	Description
arr	string	repeated	array

StringFilter

Set of string filters

Field	Type	Label	Description
eq	string		equals
in	StringArray		check the value is in array x IN (a, abc)

TimeFilter

Set of time filters

Field	Type	Label	Description
gt	uint64		greater than
gte	uint64		greater than or equals
lt	uint64		less than
lte	uint64		less than or equals
between	BetweenInteger		between

Top

github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/indexer.proto

Bytes

Bytes array

Field	Type	Label	Description
data	bytes		array

JsonSchema

Json schema entity

Field	Type	Label	Description
functions	JsonSchemaItem	repeated	list of functions json schema
l1_handlers	JsonSchemaItem	repeated	list of l1 handlers json schema
constructors	JsonSchemaItem	repeated	list of contructors json schema
events	JsonSchemaItem	repeated	list of events json schema
structs	JsonSchemaItem	repeated	list of declared structures json schema

JsonSchemaItem

Json schema item

Field	Type	Label	Description
name	string		name of json schema item
schema	bytes		json schema

SubscribeRequest

List of requested subscriptions

Field	Type	Label	Description
head	bool
invokes	InvokeFilters	repeated
declares	DeclareFilters	repeated
deploys	DeployFilters	repeated
deploy_accounts	DeployAccountFilters	repeated
l1_handlers	L1HandlerFilter	repeated
internals	InternalFilter	repeated
fees	FeeFilter	repeated
events	EventFilter	repeated
msgs	MessageFilter	repeated
transfers	TransferFilter	repeated
storage_diffs	StorageDiffFilter	repeated
token_balances	TokenBalanceFilter	repeated
tokens	TokenFilter	repeated
addresses	AddressFilter	repeated

Subscription

Subscription entity. It contains subscription id and subscription's live notifications. It's response on Subscribe request.

Field	Type	Label	Description
response	SubscribeResponse		message containing subscription id
block	Block
declare	Declare
deploy	Deploy
deploy_account	DeployAccount
event	Event
fee	Fee
internal	Internal
invoke	Invoke
l1_handler	L1Handler
message	StarknetMessage
storage_diff	StorageDiff
token_balance	TokenBalance
transfer	Transfer
token	Token
address	Address
end_of_block	EndOfBlock		message which signals about block data ends

IndexerService

Desription of server interface

Method Name	Request Type	Response Type	Description
Subscribe	SubscribeRequest	Subscription stream	Subscribe to live notification from indexer
Unsubscribe	UnsubscribeRequest	UnsubscribeResponse	Unsubscribe from live notification from indexer
JSONSchemaForClass	Bytes	Bytes	Receives JSON schema of class ABI by class hash
JSONSchemaForContract	Bytes	Bytes	Receives JSON schema of class ABI by contract hash

Top

github.com/dipdup-io/starknet-indexer/pkg/grpc/proto/response.proto

Address

Field	Type	Label	Description
id	uint64
hash	bytes
class_id	uint64	optional
height	uint64

Block

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
version	string
tx_count	uint64
invokes_count	uint64
declares_count	uint64
deploys_count	uint64
deploy_account_count	uint64
l1_handlers_count	uint64
storage_diffs_count	uint64
status	uint64
hash	bytes
parent_hash	bytes
new_root	bytes
sequencer_address	bytes

Declare

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
version	uint64
position	uint64
sender	Address	optional
contract	Address	optional
status	uint64
class	bytes
hash	bytes
max_fee	string
nonce	string

Deploy

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
position	uint64
contract	Address
status	uint64
class	bytes
hash	bytes
salt	bytes
calldata	string	repeated
parsed_calldata	bytes

DeployAccount

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
position	uint64
contract	Address
status	uint64
class	bytes
hash	bytes
salt	bytes
max_fee	string
nonce	string
calldata	string	repeated
parsed_calldata	bytes

EndOfBlock

Field	Type	Label	Description
height	uint64

Event

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
order	uint64
contract	Address
from	Address
keys	string	repeated
data	string	repeated
name	string
parsed_data	bytes

Fee

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
contract	Address
caller	Address
class	bytes
selector	bytes
entrypoint_type	uint64
call_type	uint64
calldata	string	repeated
result	string	repeated
entrypoint	string
parsed_calldata	bytes

Internal

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
status	uint64
hash	bytes
contract	Address
caller	Address
class	bytes
selector	bytes
entrypoint_type	uint64
call_type	uint64
calldata	string	repeated
result	string	repeated
entrypoint	string
parsed_calldata	bytes
parsed_result	bytes

Invoke

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
status	uint64
hash	bytes
version	uint64
position	uint64
contract	Address
selector	bytes
max_fee	string
nonce	string
calldata	string	repeated
entrypoint	string
parsed_calldata	bytes

L1Handler

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
status	uint64
hash	bytes
position	uint64
contract	Address
selector	bytes
max_fee	string
nonce	string
calldata	string	repeated
entrypoint	string
parsed_calldata	bytes

StarknetMessage

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
contract	Address
from	Address
to	Address
selector	string
nonce	string
payload	string	repeated

StorageDiff

Field	Type	Label	Description
id	uint64
height	uint64
contract	Address
key	bytes
value	bytes

Token

Field	Type	Label	Description
id	uint64
deploy_height	uint64
deploy_time	uint64
contract	Address
owner	bytes
type	int32
metadata	bytes

TokenBalance

Field	Type	Label	Description
owner	Address
contract	Address
token_id	string
balance	string

Transfer

Field	Type	Label	Description
id	uint64
height	uint64
time	uint64
contract	Address
from	Address
to	Address
amount	string
token_id	string

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)