Skip to content

Commit 29a9f0c

Browse files
bchochobchocho
authored
[api] add a long poll API /transactions/wait_by_hash/:txn_hash (aptos-labs#12419)
### Description The motivation is to reduce e2e latencies by learning of committed responses immediately. Currently, it is up to the client to poll /transactions/by_hash and there is overhead on the poll intervals and the RTT of the poll. There is concern around holding large numbers of connections for an extended time -- to alleviate this we put a limit on active long polls, and simply return immediately when that limit is reached. The API does not give guarantees about how long the long poll will wait. ### Test Plan Added unit tests. Deployed locally and in previewnet and tested long poll behavior.
1 parent 4aeb104 commit 29a9f0c

10 files changed

+1164
-4
lines changed

‎api/doc/spec.json

Lines changed: 524 additions & 0 deletions
Large diffs are not rendered by default.

‎api/doc/spec.yaml

Lines changed: 385 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6285,6 +6285,391 @@ paths:
62856285
type: integer
62866286
format: uint64
62876287
operationId: get_transaction_by_hash
6288+
/transactions/wait_by_hash/{txn_hash}:
6289+
get:
6290+
tags:
6291+
- Transactions
6292+
summary: Wait for transaction by hash
6293+
description: |-
6294+
Same as /transactions/by_hash, but will wait for a pending transaction to be committed. To be used as a long
6295+
poll optimization by clients, to reduce latency caused by polling. The "long" poll is generally a second or
6296+
less but dictated by the server; the client must deal with the result as if the request was a normal
6297+
/transactions/by_hash request, e.g., by retrying if the transaction is pending.
6298+
parameters:
6299+
- name: txn_hash
6300+
schema:
6301+
$ref: '#/components/schemas/HashValue'
6302+
in: path
6303+
description: Hash of transaction to retrieve
6304+
required: true
6305+
deprecated: false
6306+
explode: true
6307+
responses:
6308+
'200':
6309+
description: ''
6310+
content:
6311+
application/json:
6312+
schema:
6313+
$ref: '#/components/schemas/Transaction'
6314+
application/x-bcs:
6315+
schema:
6316+
type: array
6317+
items:
6318+
type: integer
6319+
format: uint8
6320+
headers:
6321+
X-APTOS-CHAIN-ID:
6322+
description: Chain ID of the current chain
6323+
required: true
6324+
deprecated: false
6325+
schema:
6326+
type: integer
6327+
format: uint8
6328+
X-APTOS-LEDGER-VERSION:
6329+
description: Current ledger version of the chain
6330+
required: true
6331+
deprecated: false
6332+
schema:
6333+
type: integer
6334+
format: uint64
6335+
X-APTOS-LEDGER-OLDEST-VERSION:
6336+
description: Oldest non-pruned ledger version of the chain
6337+
required: true
6338+
deprecated: false
6339+
schema:
6340+
type: integer
6341+
format: uint64
6342+
X-APTOS-LEDGER-TIMESTAMPUSEC:
6343+
description: Current timestamp of the chain
6344+
required: true
6345+
deprecated: false
6346+
schema:
6347+
type: integer
6348+
format: uint64
6349+
X-APTOS-EPOCH:
6350+
description: Current epoch of the chain
6351+
required: true
6352+
deprecated: false
6353+
schema:
6354+
type: integer
6355+
format: uint64
6356+
X-APTOS-BLOCK-HEIGHT:
6357+
description: Current block height of the chain
6358+
required: true
6359+
deprecated: false
6360+
schema:
6361+
type: integer
6362+
format: uint64
6363+
X-APTOS-OLDEST-BLOCK-HEIGHT:
6364+
description: Oldest non-pruned block height of the chain
6365+
required: true
6366+
deprecated: false
6367+
schema:
6368+
type: integer
6369+
format: uint64
6370+
X-APTOS-CURSOR:
6371+
description: |-
6372+
Cursor to be used for endpoints that support cursor-based
6373+
pagination. Pass this to the `start` field of the endpoint
6374+
on the next call to get the next page of results.
6375+
deprecated: false
6376+
schema:
6377+
type: string
6378+
'400':
6379+
description: ''
6380+
content:
6381+
application/json:
6382+
schema:
6383+
$ref: '#/components/schemas/AptosError'
6384+
headers:
6385+
X-APTOS-CHAIN-ID:
6386+
description: Chain ID of the current chain
6387+
deprecated: false
6388+
schema:
6389+
type: integer
6390+
format: uint8
6391+
X-APTOS-LEDGER-VERSION:
6392+
description: Current ledger version of the chain
6393+
deprecated: false
6394+
schema:
6395+
type: integer
6396+
format: uint64
6397+
X-APTOS-LEDGER-OLDEST-VERSION:
6398+
description: Oldest non-pruned ledger version of the chain
6399+
deprecated: false
6400+
schema:
6401+
type: integer
6402+
format: uint64
6403+
X-APTOS-LEDGER-TIMESTAMPUSEC:
6404+
description: Current timestamp of the chain
6405+
deprecated: false
6406+
schema:
6407+
type: integer
6408+
format: uint64
6409+
X-APTOS-EPOCH:
6410+
description: Current epoch of the chain
6411+
deprecated: false
6412+
schema:
6413+
type: integer
6414+
format: uint64
6415+
X-APTOS-BLOCK-HEIGHT:
6416+
description: Current block height of the chain
6417+
deprecated: false
6418+
schema:
6419+
type: integer
6420+
format: uint64
6421+
X-APTOS-OLDEST-BLOCK-HEIGHT:
6422+
description: Oldest non-pruned block height of the chain
6423+
deprecated: false
6424+
schema:
6425+
type: integer
6426+
format: uint64
6427+
'403':
6428+
description: ''
6429+
content:
6430+
application/json:
6431+
schema:
6432+
$ref: '#/components/schemas/AptosError'
6433+
headers:
6434+
X-APTOS-CHAIN-ID:
6435+
description: Chain ID of the current chain
6436+
deprecated: false
6437+
schema:
6438+
type: integer
6439+
format: uint8
6440+
X-APTOS-LEDGER-VERSION:
6441+
description: Current ledger version of the chain
6442+
deprecated: false
6443+
schema:
6444+
type: integer
6445+
format: uint64
6446+
X-APTOS-LEDGER-OLDEST-VERSION:
6447+
description: Oldest non-pruned ledger version of the chain
6448+
deprecated: false
6449+
schema:
6450+
type: integer
6451+
format: uint64
6452+
X-APTOS-LEDGER-TIMESTAMPUSEC:
6453+
description: Current timestamp of the chain
6454+
deprecated: false
6455+
schema:
6456+
type: integer
6457+
format: uint64
6458+
X-APTOS-EPOCH:
6459+
description: Current epoch of the chain
6460+
deprecated: false
6461+
schema:
6462+
type: integer
6463+
format: uint64
6464+
X-APTOS-BLOCK-HEIGHT:
6465+
description: Current block height of the chain
6466+
deprecated: false
6467+
schema:
6468+
type: integer
6469+
format: uint64
6470+
X-APTOS-OLDEST-BLOCK-HEIGHT:
6471+
description: Oldest non-pruned block height of the chain
6472+
deprecated: false
6473+
schema:
6474+
type: integer
6475+
format: uint64
6476+
'404':
6477+
description: ''
6478+
content:
6479+
application/json:
6480+
schema:
6481+
$ref: '#/components/schemas/AptosError'
6482+
headers:
6483+
X-APTOS-CHAIN-ID:
6484+
description: Chain ID of the current chain
6485+
deprecated: false
6486+
schema:
6487+
type: integer
6488+
format: uint8
6489+
X-APTOS-LEDGER-VERSION:
6490+
description: Current ledger version of the chain
6491+
deprecated: false
6492+
schema:
6493+
type: integer
6494+
format: uint64
6495+
X-APTOS-LEDGER-OLDEST-VERSION:
6496+
description: Oldest non-pruned ledger version of the chain
6497+
deprecated: false
6498+
schema:
6499+
type: integer
6500+
format: uint64
6501+
X-APTOS-LEDGER-TIMESTAMPUSEC:
6502+
description: Current timestamp of the chain
6503+
deprecated: false
6504+
schema:
6505+
type: integer
6506+
format: uint64
6507+
X-APTOS-EPOCH:
6508+
description: Current epoch of the chain
6509+
deprecated: false
6510+
schema:
6511+
type: integer
6512+
format: uint64
6513+
X-APTOS-BLOCK-HEIGHT:
6514+
description: Current block height of the chain
6515+
deprecated: false
6516+
schema:
6517+
type: integer
6518+
format: uint64
6519+
X-APTOS-OLDEST-BLOCK-HEIGHT:
6520+
description: Oldest non-pruned block height of the chain
6521+
deprecated: false
6522+
schema:
6523+
type: integer
6524+
format: uint64
6525+
'410':
6526+
description: ''
6527+
content:
6528+
application/json:
6529+
schema:
6530+
$ref: '#/components/schemas/AptosError'
6531+
headers:
6532+
X-APTOS-CHAIN-ID:
6533+
description: Chain ID of the current chain
6534+
deprecated: false
6535+
schema:
6536+
type: integer
6537+
format: uint8
6538+
X-APTOS-LEDGER-VERSION:
6539+
description: Current ledger version of the chain
6540+
deprecated: false
6541+
schema:
6542+
type: integer
6543+
format: uint64
6544+
X-APTOS-LEDGER-OLDEST-VERSION:
6545+
description: Oldest non-pruned ledger version of the chain
6546+
deprecated: false
6547+
schema:
6548+
type: integer
6549+
format: uint64
6550+
X-APTOS-LEDGER-TIMESTAMPUSEC:
6551+
description: Current timestamp of the chain
6552+
deprecated: false
6553+
schema:
6554+
type: integer
6555+
format: uint64
6556+
X-APTOS-EPOCH:
6557+
description: Current epoch of the chain
6558+
deprecated: false
6559+
schema:
6560+
type: integer
6561+
format: uint64
6562+
X-APTOS-BLOCK-HEIGHT:
6563+
description: Current block height of the chain
6564+
deprecated: false
6565+
schema:
6566+
type: integer
6567+
format: uint64
6568+
X-APTOS-OLDEST-BLOCK-HEIGHT:
6569+
description: Oldest non-pruned block height of the chain
6570+
deprecated: false
6571+
schema:
6572+
type: integer
6573+
format: uint64
6574+
'500':
6575+
description: ''
6576+
content:
6577+
application/json:
6578+
schema:
6579+
$ref: '#/components/schemas/AptosError'
6580+
headers:
6581+
X-APTOS-CHAIN-ID:
6582+
description: Chain ID of the current chain
6583+
deprecated: false
6584+
schema:
6585+
type: integer
6586+
format: uint8
6587+
X-APTOS-LEDGER-VERSION:
6588+
description: Current ledger version of the chain
6589+
deprecated: false
6590+
schema:
6591+
type: integer
6592+
format: uint64
6593+
X-APTOS-LEDGER-OLDEST-VERSION:
6594+
description: Oldest non-pruned ledger version of the chain
6595+
deprecated: false
6596+
schema:
6597+
type: integer
6598+
format: uint64
6599+
X-APTOS-LEDGER-TIMESTAMPUSEC:
6600+
description: Current timestamp of the chain
6601+
deprecated: false
6602+
schema:
6603+
type: integer
6604+
format: uint64
6605+
X-APTOS-EPOCH:
6606+
description: Current epoch of the chain
6607+
deprecated: false
6608+
schema:
6609+
type: integer
6610+
format: uint64
6611+
X-APTOS-BLOCK-HEIGHT:
6612+
description: Current block height of the chain
6613+
deprecated: false
6614+
schema:
6615+
type: integer
6616+
format: uint64
6617+
X-APTOS-OLDEST-BLOCK-HEIGHT:
6618+
description: Oldest non-pruned block height of the chain
6619+
deprecated: false
6620+
schema:
6621+
type: integer
6622+
format: uint64
6623+
'503':
6624+
description: ''
6625+
content:
6626+
application/json:
6627+
schema:
6628+
$ref: '#/components/schemas/AptosError'
6629+
headers:
6630+
X-APTOS-CHAIN-ID:
6631+
description: Chain ID of the current chain
6632+
deprecated: false
6633+
schema:
6634+
type: integer
6635+
format: uint8
6636+
X-APTOS-LEDGER-VERSION:
6637+
description: Current ledger version of the chain
6638+
deprecated: false
6639+
schema:
6640+
type: integer
6641+
format: uint64
6642+
X-APTOS-LEDGER-OLDEST-VERSION:
6643+
description: Oldest non-pruned ledger version of the chain
6644+
deprecated: false
6645+
schema:
6646+
type: integer
6647+
format: uint64
6648+
X-APTOS-LEDGER-TIMESTAMPUSEC:
6649+
description: Current timestamp of the chain
6650+
deprecated: false
6651+
schema:
6652+
type: integer
6653+
format: uint64
6654+
X-APTOS-EPOCH:
6655+
description: Current epoch of the chain
6656+
deprecated: false
6657+
schema:
6658+
type: integer
6659+
format: uint64
6660+
X-APTOS-BLOCK-HEIGHT:
6661+
description: Current block height of the chain
6662+
deprecated: false
6663+
schema:
6664+
type: integer
6665+
format: uint64
6666+
X-APTOS-OLDEST-BLOCK-HEIGHT:
6667+
description: Oldest non-pruned block height of the chain
6668+
deprecated: false
6669+
schema:
6670+
type: integer
6671+
format: uint64
6672+
operationId: wait_transaction_by_hash
62886673
/transactions/by_version/{txn_version}:
62896674
get:
62906675
tags:

‎api/goldens/aptos_api__tests__transactions_test__test_wait_pending_transaction_by_hash.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"message": "Transaction not found by Transaction hash(0xdadfeddcca7cb6396c735e9094c76c6e4e9cb3e3ef814730693aed59bd87b31d)",
3+
"error_code": "transaction_not_found",
4+
"vm_error_code": null
5+
}

0 commit comments

Comments
 (0)