GetWalletTransactions API

See: Technical_Articles, NodeCore_CommandLine#getwallettransactions

Overview

getwallettransactions shows transactions for imported wallets. If the address does not show up in "getbalance", then the transaction for that address will not show up in getwallettransactions either.

It requires the wallet cache to be rebuilt (see: NodeCore_CommandLine#refreshwalletcache). The status of this cache can be seen in the "wallet_cache_sync_height" field of getstateinfo.

It is exposed via the API (grpc and http), as well as the NC_CLI.

Code sample

There is a code sample in the Java UI wallet that calls grpc:

https://github.com/VeriBlock/nodecore-wallet-ui/blob/master/src/main/java/veriblock/wallet/core/NodeCoreGateway.java

Look for this method: CommandResult<WalletTransactionsEntity> getWalletTransactions(...)

GetWalletTransactions

message GetWalletTransactionsRequest {
    enum Type {
        LIST = 0;
        QUERY = 1;
    }
    Type request_type = 1;
    bytes address = 2;
    WalletTransaction.Type transaction_type = 3;
    TransactionMeta.Status status = 4;
    NumericFilter amount_filter = 5;
    NumericFilter timestamp_filter = 6;
    Paging page = 7;
}

It is possible to invoke this endpoint with an empty request object. Doing so defaults two parameters: request_type and page.

request_type - a "LIST" (0) value lists the most recent non-pending transactions, meaning the transactions that have shown up in some block. A LIST request ignores parameters 2-6. A QUERY type utilizes parameters 2-6 to construct a query.

page - A Paging message that indicates the page number and number of results per page. If not supplied, the defaults are page 1 and 20 results per page

message Paging {
    int32 page_number = 1;
    int32 results_per_page = 2;
}

When querying, the other parameters are used to filter down results:

address - The byte array representation of an address in the wallet. There is some nuance to this parameter if used in conjunction with other filters. For example, if you have a transaction in which coins are transferred from address "A" in the wallet to address "B", also in the wallet. The transaction_type and amount filter would have opposing values if you were filtering on address A or B. Address "A" would be a "SENT" transaction_type, whereas to the same transaction a querying on Address "B" would require a "RECEIVED" transaction_type.

transaction_type - This is not equivalent to the notions of TransactionType in NodeCore, but rather the type of effect it has on a particular address.

enum Type {
    NOT_SET = 0;
    POW_COINBASE = 1;
    POP_COINBASE = 2;
    BOTH_COINBASE = 3;
    SENT = 4;
    RECEIVED = 5;
    SENT_AND_RECEIVED = 6;
    POP = 7;
}

NOT_SET is the default and will result in no filtering for this parameter.

status - A filter on the "confirmation" state of a transaction. Possible values:

enum Status {
    UNKNOWN = 0;
    PENDING = 1;
    CONFIRMED = 2;
    DEAD = 3;
}

• UNKNOWN is the default and will result in no filtering for this parameter.
• PENDING relates to transactions sitting in the mempool. A query for PENDING transactions short-circuits all other filters and just returns all pending transactions. Generally, this is because transactions have a very short time to live in this state. Also, an implementation detail is that the pending transactions are kept in memory and must be scanned to filter as opposed to persisted to disk where they can be queried on different attributes.
• CONFIRMED is a transaction that is included in a block that is part of the best chain
• DEAD is a transaction that is ONLY contained in a non-best chain fork. DEAD is not permanent as a reorganization or subsequent inclusion in a best chain block could resurrect it to CONFIRMED status.

amount_filter - A NumericFilter message type that allows for different equality/inequality comparisons, against a computed "net amount" from the perspective of a particular address. The net amount is the sum of outputs to a given address minus the input if from that same address. Generally, a SENT (or SENT_AND_RECEIVED) transaction would have a negative net amount, whereas a RECEIVED transaction would be positive. For coinbase transactions, it is the sum of all outputs (POW & POP) for the address, and will always be a positive net amount.

message NumericFilter {
    enum Operator {
        EQUAL = 0;
        LESS_THAN = 1;
        LESS_THAN_OR_EQUAL = 2;
        GREATER_THAN = 3;
        GREATER_THAN_OR_EQUAL = 4;
        BETWEEN = 5;
    }
    Operator operator = 1;
    sint64 value = 2;
    sint64 secondary_value = 3;
}

The operator defaults to an "EQUAL" filter. Operator types 0-4 will use the "value" property for their comparison. Only the BETWEEN operator requires the secondary_value parameter as well.

timestamp_filter - Also uses a NumericFilter message type for comparisons against the epoch timestamp associated with a transaction.

GetWalletTransactionsReply

A reply object looks like:

message GetWalletTransactionsReply {
    Paging next = 1;
    repeated WalletTransaction transactions = 2;
}

The next property indicates the paging parameters that should be used in the "page" property of the next request to continue iterating the resultset.

A WalletTransaction has the following format:

message TransactionMeta {
    enum Status {
        UNKNOWN = 0;
        PENDING = 1;
        CONFIRMED = 2;
        DEAD = 3;
    }

    bytes tx_id = 1;
    bytes block_header = 2;
    repeated bytes appears_in = 3;
    int32 confirmations = 4;
    Status status = 5;
}

message WalletTransaction {
    enum Type {
        NOT_SET = 0;
        POW_COINBASE = 1;
        POP_COINBASE = 2;
        BOTH_COINBASE = 3;
        SENT = 4;
        RECEIVED = 5;
        SENT_AND_RECEIVED = 6;
        POP = 7;
    }

    bytes tx_id = 1;
    bytes address = 2;
    int32 timestamp = 3;
    Type type = 4;
    sint64 net_amount = 5;
    Output input = 6;
    repeated Output outputs = 7;
    TransactionMeta meta = 8;
}

Most properties and their significance have already been touched upon.