Background
The current ckb-indexer only accepts one single scirpt to index, but with the addition of ACPL (anyone-can-pay lock) and SUDT (simple user defined token), new features need to be realized in ckb-indexer to accommodate more scenarios.
1. ex_get_cells
Expand filters: two scripts(lock script and type script), data, block range and cell capacity sorting.
Parameters
search_lock_key: // optional
script - Script
args_len - maximal prefix search args len, optional
search_type_key: // optional
script - Script | null
args_len - maximal prefix search args len, optional
search_data_key: occupied | null // optional
order: enum, asc | desc | size_asc | size_desc
range: [fromBlock, toBlock] // optional e.g.[0x253b40, 0x253f28] ["0x" + 2440000n.toString(16), "0x" + 2441000n.toString(16)]
needed_capacity: needed capacity, optional
limit: result size limit
after_cursor: pagination parameter, optional
Returns
objects - live cells
last_cursor - pagination parameter
Explanation
The difference between empty field and the field filled with null:
*Parameters where the field is not filled means no filtering, when the value of the field in parameter is: Script means the part of the data has to satisfy the Script format, null means the part of the data is empty, occupied means the part of the data is non-empty.
In addition, script args should also be filtered: specify args | null (==all), when script args is null, the search returns cells that meet the specified code_hash condition. *Refer to ckb-lumos-indexer: if script_args fills “”, args_len = N, prefix search will satisfy this function.
needed_capacity: Based on the capacity of CKBytes requested, return the cells that meet the demand.
Example: When a user needs to transfer 1000 CKB, when requesting cells, instead of returning all cells, just return the cells that meet the 1000 CKB transfer requirement according to the order policy.
- For cells
with lock scriptandwithout type scriptandwithout data(i.e., the available CKB in an address). Provide theneeded_capacityparameter to return cells based on the required amount of capacity.
Order：
- asc | desc: sort by the formation time of a cell
- size_asc | size_desc：sort by the capacity of a cell
Block search range：
- [fromBlock, toBlock]
Refer to ckb-lumos-indexer: [0x253b40, 0x253f28] is [“0x” + 2440000n.toString(16), “0x” + 2441000n.toString(16)]
2.ex_get_transactions
Returns the transactions by the lock script, type script and data
Parameters
search_lock_key: // optional
script - Script
args_len - maximal prefix search args len, optional
search_type_key: // optional
script - Script | null
args_len - maximal prefix search args len, optional
search_data_key: occupied | null // optional
order: enum, asc | desc
range: [fromBlock, toBlock] // optional e.g.[0x253b40, 0x253f28] ["0x" + 2440000n.toString(16), "0x" + 2441000n.toString(16)]
limit: result size limit
after_cursor: pagination parameter, optional
Returns
objects - transactions
last_cursor - pagination parameter
3.ex_get_cells_capacity
Returns the live cells‘ capacity by the lock script, type script and data
Parameters
search_lock_key: //optional
script - Script
args_len - maximal prefix search args len, optional
search_type_key: //optional
script - Script | null
args_len - maximal prefix search args len, optional
search_data_key: occupied | null //optional
Returns
capacity - total capacity
block_hash - indexed tip block hash
block_number - indexed tip block number
4.get_sudt_cells_balance
Returns the live sudt cells‘ sudt balance and capacity by the lock script and type script.
Parameters
search_lock_key: //optional
script - Script
args_len - maximal prefix search args len, optional
search_type_key:
script - Script
args: <SUDT args>
code_hash: <SUDT code_hash>
hash_type: type
args_len - maximal prefix search args len, optional
Returns
balance - total balance
capacity - total capacity
block_hash - indexed tip block hash
block_number - indexed tip block number
Description of some practical examples
Get the available CKB balance of an address
- For cells that
with lock scriptandwithout type scriptandwithout data(i.e., the available CKB in an address), returns the capacity of available CKBytes in that address
ex_get_cells_capacity (search_lock_key : Scirpt, search_type_key : null, search_data_key : null)
Get the capacity of CKB occupied in an address (without type script)
- For cells that
with lock scriptandwithout type scriptandwith data(i.e., unoccupied CKB in an address), returns the capacity of CKBytes that are currently occupied (without type script) in that address.
ex_get_cells_capacity (search_lock_key : Scirpt, search_type_key : null, search_data_key: occupied)
Get the capacity of CKB occupied in an address (with type script)
- For cells that
with lock scriptandwith type script(i.e., CKBs with type script in an address), returns the capacity of CKBytes that are currently occupied (with type script) in that address.
ex_get_cells_capacity (search_lock_key : Scirpt, search_type_key : script)
Get the balance of a SUDT in an address and the capacity of occupied CKB (also suitable for Nervos DAO).
- For cells that
with lock scriptandwith type scriptandcode_hash of type script is the SUDT contract and args is one kind of SUDT(i.e. a SUDT cell in an address), provide thebalancefunction to return the balance of the SUDT in that address; provide thecapacityfunction to return the capacity of CKBytes occupied by the SUDT in that address.
get_sudt_cells_balance (search_lock_key : Scirpt, search_type_key : sudt_ID_script)
Get the available amount of a SUDT and the total capacity of CKB occupied (also suitable for Nervos DAO).
- For cells that
without lock scriptandwith type scriptandcode_hash of type script is the SUDT contract and args is one kind of SUDT(i.e., one kind of SUDT), provide thebalancefunction to return the available amount of the SUDT; provide thecapacityfunction to return the total capacity of CKBytes occupied by the SUDT.
get_sudt_cells_balance (search_type_key : sudt_ID_script)
