All notable changes to this project will be documented in this file.
- Added fields:
BlockchainMessage { src_code_hash dst_code_hash },BlockchainTransaction { code_hash },Message { src_code_hash dst_code_hash },Transaction { code_hash }. - Added arguments:
blockchain.messages(src_code_hash dst_code_hash),blockchain.transactions(code_hash). - In
TCP_ADNLrequest mode Q-Server uses TON LiteServer API as an account provider.
- Account provider JSON RPC terminated a process in case of request timeout.
- GraphQL queries with body more than 100KB was failed with
PayloadTooLargeError: request entity too large. The size of the body is increased up to 50MB.
config.blockBocs.s3.numBucketsfield
-
Added support for node-jrpc protocol changes.
-
Added cache for the last key block. Config parameters:
last-key-block-cache-enabled– default istrue.last-key-block-cache-ttl-ms– cached block TTL. Default is five min. This cached block is returned for the following queries:-
blocks( filter: { key_block: { eq: true } workchain_id: { eq: -1 } } orderBy: [{ direction: DESC path: "seq_no" }] ) limit: 1 ) -
blockchain { key_blocks(last:1) }
-
Added timeouts for external service queries:
config.queries.maxRuntimeInS– timeout seconds for ArangoDB queries.config.accountProvider.evernodeRpc.timeout– timeout millis for Evernode RPC queries.config.blockBocs.s3.timeout– timeout millis for block storage S3 queries.
-
Added support for YAML config file.
-
Added
request.durationtiming stat.
blocks.bocshould not use block's BOC provider (block S3 storage).
blockchain.account.transactions_by_ltpagination cursor is a transactionlt. Sobeforeandafterargs should be specified as a string withbigintrepresentation (e.g.0xabcfor hex or123for dec). Cursors are returned using0xhex bigint representation.
- Added field
BlockchainBlock.signatures– available only in non archive mode. - Added support for ArangoDB url format
http://server:8529/_db/blockchain - Account info resolver now uses EvernodeRPC boc or meta queries.
- Added argument
blockchain.account.info(byBlock)– works only with Evernode RPC.
- account.info.address was null
- Added account BOC provider via evernode RPC (new config parameter 'accountProvider`).
- Added BOC parsing for transactions, messages and blocks in
archivedatabase when user selects non parsed fields.
tracefield in transaction is a list of VM step info objects
- implemented support for
archiveparameter in all blockchain queries. archiveparameter was not propagated to the nested join queries.
- All user parameters that are enums are now checked for typos on startup
-
tracefield in transaction -
archiveparameter in blockchain signle-entity fields (block,block_by_seq_no,transaction,message). When istruethe blockchain requests use an archive database with full blockchain history but reduced field set. -
transactions_by_ltquery is added toblockchain.accountto paginate account transactions by logical time -
threadparameter inblockchain.block_by_seq_noandblockchain.blocksis deprecated.shardparameter should be used instead -
blockchain.prev_shard_blocksandblockchain.next_shard_blocksqueries for blocks chain iteration -
blockchain.transactions_by_in_msgquery for retrieving transaction by inbound message -
blockscollection latency is calculated fromgen_utimeof masterchain block which has commited last known shard block
- Latency calculation failed
-
Added config parameter
archivetoblockchain.blocks,blockchain.transactionssections. Specifies config for the database used in blockchain API when thearchiveparameter istrue. -
Added parameter
archiveto blockchain lists fields. When istruethe blockchain requests use an archive database with full blockchain history but reduced field set. -
Added config parameters
hotto specify default values forblockchain.blocks.hot,blockchain.transactions.hot,blockchain.accounts. -
Added config parameters
archiveto specify default values forblockchain.blocks.archive,blockchain.transactions.archive. -
Removed deprecated config parameters
--data-mut Q_DATA_MUT--data-hot Q_DATA_HOT--data-cold Q_DATA_COLD--data-cache Q_DATA_CACHE--data-counterparties Q_DATA_COUNTERPARIES--slow-queries-mut Q_SLOW_QUERIES_MUT--slow-queries-hot Q_SLOW_QUERIES_HOT--slow-queries-cold Q_SLOW_QUERIES_COLD--slow-queries-cache Q_SLOW_QUERIES_CACHE--slow-queries-counterparties Q_SLOW_QUERIES_COUNTERPARTIES
-
Added parameter
archiveto blockchain lists fields. -
Added
blockBocsconfig parameter allowing to resolve block bocs from external S3 compatible storage. See README.md for details. -
Removed a database sharding.
-
Added helpful error messages in case of invalid
inandnotInfilter{in: null}. -
Database query deduplication.
master_seq_nofield in blocks, transactions and messages representing seq_no of masterchain block which commited the block, transaction or messagechain_orderin messages is derived fromsrc_chain_orderanddst_chain_ordermessage.counterpartiesinblockchainAPI are not limited to internal messages
-
Case-insensitive filtering in args:
blockchain.block(hash),blockchain.transaction(hash),blockchain.message(hash) -
Address filtering in args (accepts address in any format):
blockchain.account(address),messages.src,messages.dst,transactions.account_addr,accounts.id -
Address formatting args in fields:
blockchain.account.info.address,blockchain.transaction.account_addr,blockchain.message.src,blockchain.message.dst,messages.src,messages.dst,transactions.account_addr,accounts.id -
accounts(filter:{id:{eq:""}}),accounts(filter:{id:{in:[""]}}),blockchain.account(address:"")returns account of typeNonExistif an account is missing in current shard state. -
Support new config parameter 44 (black list)
- Post external messages to JRPC endpoint
- Fast queries exceptions in slow detector.
- Support new caps in capabilities_flags.
PageInfo.startCursorandPageInfo.endCursorwere required.
- Remove "UNSTABLE" marks from
blockchainAPI - Add indexHint to
messages(filter: {src: *, dst: *, created_at: *, * } orderBy: {path: "created_at"})queries
- From now slow detector will properly interpret
idorderBy path as_key
- From now
Info.latencyalways returns last known cached latency. Every 30 seconds (latency cache TLL) it start background refreshing.
- increase
Q_REQUESTS_MAX_SIZEdefault to 64kb
- increase
Q_SUBSCRIPTIONS_MAX_FILTER_SIZEdefault to 64kb
- removed obsolete auth mutations (
revokeAccessKeys,registerAccessKeys) and all other auth related logic. - removed obsolete
finishOperationmutation.
capabilities_flagscompanion field to p8 config parametercapabilities
in: [](empty list) filter now leads to an empty query result as expectednotIn: [](empty list) filter now is ignored as expected
- Fix memory leak in Promise.race()
- Add new option
--query-max-timeout-argorQ_QUERY_MAX_TIMEOUT_ARG.
This adds upper boundary fortimeoutparameter in collection API queries.
Default is 24 hours.
- Support
timeoutargument values >= 2^31 (by coercing them down using--query-max-timeout-arg).
It is needed for ever-sdk + evernode-se with time shifts > 24 days. - Tweak waitFor logic to properly support
--query-wait-for-periodvalues less than 100 ms
- Fix
src_accountanddst_accountjoins for multiple databases (hot, cold) case.
-
Add
src_accountanddst_accountjoins toBlockchainMessagetype (used inblockchainqueries) -
Increase max allowed joins depth for
blockchain { transaction },blockchain { transactions }andblockchain { account { transactions } }queries from 1 to 2 to allowin_message { src_account }andout_messages { dst_account }joins.
-
UNSTABLE!
stringify-key-in-aql-comparisonparameter – iftruethen AQL will useTO_STRING(doc._key)conversion if _key comparison operator is used in filter (e.g.{ id: { lt: "123" }). -
New paramter
--walking-use-cacheorQ_WALKING_USE_CACHE.
Set this parameter to true to serve the block walking algorithm from the Redis cache
BlockchainTransactionfields: orig_status_name, status_name, tr_type_name
- Fix rare race condition in waitFor
- master config
p30,p40,p42fields types prev_code_hashaccount fieldallow_latest_inconsistent_dataoption in paginatedblockchainqueries:By default there is a delay of realtime data (several seconds) to ensure impossibility of data inserts before the latest accessible cursor. Now it became possible to disable this guarantee and thus - to reduce delay of realtime data by setting this flag to true.
- two config options for reading external subscriptions health messages from Redis channel
subscriptions-health-redis-channelsubscriptions-health-timeout
blockchain.master_seq_no_rangebehavior for edge cases (when boundaries are close to first and/or latests blocks) E.g. fortime_start=time_end=nowthis function used to returnend<startbut now it returnsend=null, because a masterblock for end doesn't exist yet.max_shard_gen_utime_stringandmin_shard_gen_utime_stringinBlockMaster
- faster and more reliable ArangoDB query for
blockchain.master_seq_no_range.end
See the migration guide
Queries:
blockchain.workchain_blocks. Useblockchain{ blocks }instead.blockchain.workchain_transactions. Useblockchain{ transactions }instead.blockchain.account_transactions. Useblockchain{ account{ transactions } }instead.explainQueryAccountsexplainQueryTransactionsexplainQueryMessagesexplainQueryBlocksexplainQueryBlockSignaturesexplainQueryZerostatesgetAccountsCountgetTransactionsCountgetAccountsTotalBalanceQueryExplanationandSlowReasontypes
- configuration option
ignore-messages-for-latencyto exclude messages latency from total latency for networks without service messages
- joins in subscriptions (e.g.
in_messageandout_messagesfor transactions) for external subscriptions mode
Subscription.remReceiptssubscription.Query.info.rempEnabledfield.rempconfig section.
rempReceiptsreturns internal server error when redis is inaccessiblerempReceiptssubscription terminated q-server if redis disconnected unexpectedly
- new
subscriptions-modeconfig parameter with three options:disabled,arango(default),external- describes which backend should be used for subscriptions - new
externalsubscriptions mode (publishes filters to Kafka and gets documents from Redis)
use-listenersconfig parameter (usesubscriptions-modeinstead)
- prettify code:)
- Fixed documentation about deprecated and soon to be removed API parts
- Added
init_code_hashto BlockchainAccount andext_in_msg_feeto BlockchainTransaction types (affected queries areblockchain {...})
- New functions:
blockchain { account { messages }}to fetch account messagesblockchain { block }to fetch block by hashblockchain { block_by_seq_no }to fetch block by (workchain, thread, seq_no) tripletblockchain { transaction }to fetch transaction by hashblockchain { message }to fetch message by hash
- Fixed
created_at_stringandstatus_namefields resolvers in BlockchainMessage - Messages subscriptions now ignore patch records
- Fix
blockchain.account(address).info
- Support for
nullin scalar filter. e.g.filter: { last_paid: null }. Means missing filter. - Add new functions to
blockchainroot api:account, allows:- to fetch account info (e.g. boc) via
infofield - to fetch transaction info via
transactions(similar to now deprecatedblockchain.account_transactions)
- to fetch account info (e.g. boc) via
blocks(is similar to now deprecatedworkchain_blocks)transactions(is similar to now deprecatedworkchain_transactions)
blockchain.workchain_blocks. Useblockchain{ blocks }instead.blockchain.workchain_transactions. Useblockchain{ transactions }instead.blockchain.account_transactions. Useblockchain{ account{ transactions } }instead.
- In
blockchain.key_blocksrenameseq_noargument tomaster_seq_no_range.
- Prepare code for messages joins in TBD
blockchainandaccountmessages queries.
X-Evernode-Expected-Account-Boc-Versionheader handler did not handle lowercase version of the header.
-
Support
X-Evernode-Expected-Account-Boc-Versionheader.1(default) means old version,2– new (withinit_code_hashfield). -
Support
boc1field in accounts collection.bocfield contains new2version,boc1contains downgraded to1version. -
account.init_code_hash– account 's initial code hash (when it was deployed).
- Add joined fields to
blockchain.account_transactionsandblockchain.workchain_transactions:accountin_messageout_messages
whenargument in all joined fields (for example, transaction.in_message'swhenargument)- the following root queries:
explainQueryAccountsexplainQueryTransactionsexplainQueryMessagesexplainQueryBlocksexplainQueryBlockSignaturesexplainQueryZerostatesgetAccountsCountgetTransactionsCountgetAccountsTotalBalance
QueryExplanationtype
Check the deprecation schedule, policy and migration guides for more info https://tonlabs.gitbook.io/evernode-platform/reference/breaking-changes/deprecation-schedule
- Collection filters should allow incorrect ids in the setup with multiple hot databases. Example affected query:
blocks(filter:{id:{eq:"a"}}) { id }.
- Fix recurring join queries when trying to fetch non-existent documents
- New
blockchainUNSTABLE root query, which features reliable pagination with cursor of blocks and transactions:master_seq_no_rangeto transform time range into masterchain seq_no rangekey_blocks- paginate through key blocksworkchain_blockswith optional filter by thread (former 'shard')workchain_transactionsaccount_transactions
Later, it will be expanded with messages pagination.
- Without chain ranges verification database the verified boundary now 10 seconds ago instead of 120.
- StatsD reporting now has timeout to tackle with rare freeze problem
- Bump apollo-server from 2.16.1 to 2.25.3
- diagnostic timeout added to statsD reporting
- "Cannot read property 'length' of null" error
- q-server didn't write error messages to log
- subscriptions with joins didn't work
- subscriptions for companion fields (
*_name,*_string) didn't work
- subscriptions for accounts didn't work
file_hashin blockfile_hashandroot_hashin zerostateext_in_msg_feein message
- API functions sorted in logical order
gen_software_capabilitiesblock field is big integer
main(number of masterchain validators) parameter added in ValidatorSet typechain_orderfields added inblocks,transactions,messageschainOrderBoundary(the boundary before which no data inserts are possible) field added ininfo
- Flexible data sources configuration (including separation/sharding for accounts, blocks, messages/transactions). Old data configurations are deprecated now but supported yet. For details see README.
- Option to set max execution time for queries on ArangoDb side
- Option to configure polling period in waitFor queries (queries with timeout)
- Memjs data cache support for hot databases
- Joins loading optimisations.
- Latency refreshing optimisation.
- Info query optimisation.
- Better jaeger tracing.
- When messages database is sharded, use two collections
messagesandmessages_complementfor queries - New
qserver.stats.error.internalStartD counter for internal server errors
- Subscriptions for sharded data sources
- Q-Server failed on StatsD sending
- optimizations for queries with
OR– use two simple sorted queries instead of usingORAQL operator. filter-or-conversionoption to select filter OR conversion strategy (see README).- ESLINT configuration and npm commands
run npm eslintandrun npm eslint-fix.
configconfig parameter added that allows to specify the configuration via JSON-based config file- config file reload without restart on
SIGHUPsignal - optimizations for aggregation queries
MINandMAXwere made – use simple sorted queries instead ofCOLLECT AGGREGATE. - port q-server code base to TypeScript
slow-queriesconfig parameter allows specifying how to handle slow queries (see README for details).- IMPORTANT!
zerostatescollection must reside inmutdatabase (where theaccountsreside).
- Incorrect sort order result when sorting fields are not included into the result set.
- Query returned more than
limitrecords (and exceeded records were sorted wrong).
- incorrect sort order result when sorting by two or more fields.
- info query returned incorrect latency
- info query failed if collections was empty
infofieldsblocksLatencycalculated as now() - max(blocks.gen_utime)messagesLatencycalculated as now() - max(messages.created_at)transactionsLatencycalculated as now() - max(transactions.now)latencycalculated as max(blocks_latency, messages_latency, transactions_latency)
statsd-reset-intervalconfig parameter. Q-Server will recreate statsd socket periodically if this parameter is specified.0means disabled recreation.
- querying of the
lastBlockTimeand latency fields took a long time over big collections during write loads. AQL queries used for max time were simplified (got rid of COLLECT AGGREGATE).
- Now you can retrieve account's code_hash from messages and transactions in the result set of
fields: joined account fields were added to messages and transactions:
messages.src_account,messages.dst_account,transaction.account. Remember, you can not filter by fields of joined objects.
- Some queries took a long time for execution. For example
messagesquery withdst_transactionfor the external outbound message ifmsg_typewasn't included into the result set.
lastBlockTimefield ofinfoquery returnsMAX(blocks.gen_utime). This value is updated in realtime.
- counterparties sort order was ascending.
counterpatiesquery that allows to retrieve account counterparties, i.e. accounts that the account interacted with, sorted by last interaction (internal message between accounts) timecounterpartiessubscription that allows to get updates in counterparties list.data-counterpartiesconfiguration parameter specifies endpoint to the database with counterparties collection.
requests-max-sizeconfig parameter sets limit of request message size in bytes. Default value is 16384 bytes.
- Aggregation of fields with negative values.
bocfield inzerostatecollection.
bits,cellsandpublic_cellsfields inaccountscollection representing account used storage statistics for storage fee calculation.
qserver.subscription.countStatsD counter.- Filters for fields with a hex encoded content (id's, hashes and so on) can be represented in any case. Q-Server converts filter values into lower case before use.
notInwith more than two elements generates wrong AQL condition.
id notInwas detected as a fast.
- Fields in the schema are sorted in alphabetical order.
- When the server responds with the timeout termination error, in addition to the error message server attaches the reason why this query was detected as a slow.
explainQuery*queries that examine the provided query parameters and return the conclusion – is this query fast or potentially slow. In case when the query is marked as slow, the additional information is provided about the reasons why this query is slow.
- Before: if query timeout was triggered before the db responded, the client would receive a successful result with an empty result set. Now: in this situation the client will receive error " request terminated due to timeout".
- Before: Q-Server crashed if statsd endpoint was unavailable. Now: StatsD socket recreates on statsd sending error.
- Tailing comma is ignored in ArangoDB configuration string.
info.endpointsfield returns list of alternative endpoints
ZerostateAccountschema info
zerostatesuses immutable database
zerostatesquery to access blockchain Zero State.
- Update node-fetch version to 2.6.1
- MemcachedClient: use hashedKey constructed from fingerprint of cold collection sizes
- MemcachedClient: hotUpdate fingerprint on mutator
dropCachedDbInfo
- crash when subscription filter is invalid.
- aggregation of empty set failed when it runs over partitioned data.
- MemcachedClient: by using memjs library
- MaxListenersExceededWarning in case when more than 6 joined objects in result.
- Size limit for external messages (60000).
- Aggregation functions worked wrong on partitioned data.
- Request broker that supports new gate-node arch (hot-dbs, cold-cache, cold-dbs).
- False execution of subscriptions that had
some_big_int_field: { ne: null }in filter.
acc_typefield in Account expanded withNonExiststatus
mammutationdropCachedDbInfoto reset cached indexes.
- Update indexes retries if index creation has failed on the timeout.
- Basic Debian image updated from "Stretch" to "Buster" to meet dependencies.
- Release resources associated with aborted GraphQL requests.
- StatsD counter
qserver.startwith additional tag{version=package.json.version}.
- Slow detector must detects queries like
FILTER workchain_id == -1 SORT seq_no DESCas a fast query.
- Field
state_hashinaccountscollection
- Add message tracing at: 1) post request 2) db notification / message has inserted
- Field
created_byinblocks.
- Query builder generates reduced
RETURNsection according to the result set requested by user.
- Queries like
{ signatures: { any: { node_id: { in: ["1", "2"] } } } }generates optimized AQL like(doc.signatures[*].node_id IN @v1) OR (doc.signatures[*].node_id IN @v2).
-
Support for signed numbers encoded with strings.
-
Field
balance_deltaandbalance_delta_otherofTransaction. -
whenarg to join fields – ability to include joined objects into result set only if some conditions met.In following example we return
dst_transactiononly for messages withvaluegreater than zero:query { messages { dst_transaction(timeout: 0, when: { value: { gt: "0" } }) { id } value dst } }
-
Unit test infrastructure is now suitable for TDD. It starts q-server and performs graphql queries during tests.
⚠️ Important to CI: you must run tests in environment correctly configured to start q-server connected to valid Arangodb with enough for tests set of data. You can configure q-server using env variables due to README.
- Unix time strings now correctly show unix seconds.
- Fields
Block.key_fieldandBlock.boc. - Field
expireAtin post requests. - Field
timeininfoquery. src_transactionwill wait only whenmessages.created_lt!== 0 (because there is no transaction for such messages).
- master config
p20,p21,p18fields types
- master config p17 field sizes
- Aggregates on nested array fields failed with
value.substr is not function. - Slow detector for
MINMAXaggregates must use a specified field asorder byto detect fast query. - Indexes reloaded from db first time on demand and then every 1 hour.
- Config p17 stake types.
- companion fields
*_stringfor fields that holds unix time values timeoutargument (default to 40sec) to all join fields (used to wait joined document in condition of eventual consistency)- companion fields
*_hashcontaining BOC root hash forcode,dataandlibraryfields in accounts and messages qserver.query.failed- statsd counter for failed queriesqserver.query.slow- statsd counter for slow queriesqserver.post.count- statsd counter for node requestsqserver.post.failed- statsd counter for failed node requestsQ_KEEP_ALIVEconfiguration parameter specify interval in ms of keep alive messages for active subscriptions (default 60000).
- array
anyfilter with single fieldeqoperator optimized to<param> IN <path-to-field>AQL - aggregate with empty filter and single
COUNTusesRETURN LENGTH(<collection>)
- fixed
seq_nofield inBlockSignatures(it contained shard ident before), added correctshardfield. - aggregation functions must return
nullwhen no data to aggregate (was[Object object])
- Schema graph enhancements
- Filter language enhancements
- some ENV configuration variables have renamed (to be prefixed with
Q_).
blockjoin added toMessage,Transaction, andBlockSignaturesORcombination operator in filters- Added new fields (
gen_utime,seq_no,workchain_id,proof,validator_list_hash_short,catchain_seqno,sig_weight) intoBlockSignatures - aggregation queries:
aggregateBlockSignatures,aggregateBlocks,aggregateTransactions,aggregateMessages,aggregateAccounts --statsd-tags(Q_STATSD_TAGS) config parameter to specify additional tags
- all configuration env variables changed to be prefixed with
Q_
- internal memory optimizations
- jaeger injection format has changed from BINARY to TEXT_MAP
shuffle_mc_validatorsfield toCatchainConfigstruct (config param 28)new_catchain_idsfield toConsensusConfigstruct (config param 29)- jaeger endpoint without protocol part will use agent instead of collector.
- supported new type of outbound message
dequeueShort(msg_type: 7): added fieldsmsg_env_hash,next_workchain,next_addr_pfx,import_block_lttoOutMsgtype.
StatsD support
--statsd-serverparameter (Q_STATSD_SERVERenv) config option to specify StatsD server addressqserver.doc.count,qserver.query.count,qserver.query.time,qserver.query.activestatsd metrics
Stability fixes
- slow queries detector use filter and orderBy analysis
- fixed string format for big numbers
- change arangochair dependency to forked version (cause of dropped original repository)
- type of
total_weightandweightfixed tou64
Stability fixes
operationIdparameter to query methodsfinishOperationsmutation
- inactive listeners were reduced with help of operation ids
- subscriptions with arrays crash
Scheme enhancements Security fixes
- all big number fields can be optionally parametrized with
formatargumentHEX(default) orDEC. Messagecontains new joined fieldssrc_transaction(from where this message was originated) anddst_transaction(where this message was handled).--mam-access-keysandMAM_ACCESS_KEYSconfig to protect mam endpoint.- all queries and mutations inside single GraphQL request must use the same access key.
- change type of
transaction_idto string authparameter of subscription changed toaccessKey- invalid
accessKeytreated by subscribe as a valid key - all internal errors are logged as is but converted to
Service temporary unavailablebefore sending to client - server side stack traces are truncated before sending to client
- waitFor 2 minute limit timeout has been removed
Stability fixes
min_shard_gen_utimeandmax_shard_gen_utimefields inblock.master
- joined objects returned as
nullif joined object inserted in DB later than parent object.
Ability to set restrictions to accounts for particular access keys
accessKeyoptional header used instead ofauthorization.- keys passed to
registerAccessKeysas structures (instead of strings) and includerestrictToAccountsoptional field
- message & transaction ids in
out_msg_descr
--trace-service(orQ_TRACE_SERVICEenv) specify service name that will be used in jaeger.--trace-tags(orQ_TRACE_TAGSenv) specify additional tags associated with a spans.
- Auth support
--auth-endpoint(orAUTH_ENDPOINTenv) config option. Specify address of auth service.authorizationoptional header added to specify access token.accessKeyoptional parameter added to all GraphQL queries to specify access token in GraphQL playground.getManagementAccessKeyquery one time management access key.registerAccessKeysmutation to register account's access keys.revokeAccessKeysmutation to revoke account's access keys.
- OpenTracing (jaeger) support
- workchain_id field added alongside with account address to
accounts.workchain_id,transactions.workchain_id,messages.src_workchain_id,messages.dst_workchain_id - field
prev_key_block_seqnointoblockscollection
- Support for redirecting slow queries to alternative db connection.
- In scalar operations
undefined(or missing) value is treated asnull.
- Skip execution of queries with
falsefilter.