wavecli activityInspectActivity
InspectActivity returns a technical trace for one WalletEntry id.
Endpoints
rpc InspectActivity(InspectActivityRequest) returns (InspectActivityResponse)POST/v1/wallet/inspect/activityExamples
wavecli activity inspect a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9wavecli activity inspect a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9conn, err := grpc.NewClient("localhost:10029",
grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
log.Fatal(err)
}
defer conn.Close()
client := wavewalletrpc.NewWalletInspectionServiceClient(conn)
ctx := context.Background()
req := &wavewalletrpc.InspectActivityRequest{
Id: "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9",
}
resp, err := client.InspectActivity(ctx, req)
if err != nil {
log.Fatal(err)
}
fmt.Println(resp)import grpc
import wallet_pb2
import wallet_pb2_grpc
channel = grpc.insecure_channel('localhost:10029')
stub = wallet_pb2_grpc.WalletInspectionServiceStub(channel)
request = wallet_pb2.InspectActivityRequest(
id="a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9",
)
response = stub.InspectActivity(request)
print(response)const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('wallet.proto');
const { wavewalletrpc } = grpc.loadPackageDefinition(packageDefinition);
const client = new wavewalletrpc.WalletInspectionService(
'localhost:10029',
grpc.credentials.createInsecure(),
);
const request = {
"id": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9"
};
// Calls wavewalletrpc.WalletInspectionService.InspectActivity.
client.inspectActivity(request, (err, response) => {
if (err) throw err;
console.log(response);
});curl -X POST http://localhost:10031/v1/wallet/inspect/activity \
-H 'Content-Type: application/json' \
-d '{"id":"a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9"}'const res = await fetch('http://localhost:10031/v1/wallet/inspect/activity', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"id": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9"
}),
});
const inspectActivityResponse = await res.json();RequestInspectActivityRequest
InspectActivityRequest identifies the activity entry to inspect.
idstringid is the WalletEntry.id to inspect. InspectActivity searches the daemon's current activity window, which is capped by the daemon maximum list limit.
ledger_limituint32ledger_limit caps how many ledger rows are scanned for correlation. Zero means use the daemon's maximum list limit.
ResponseInspectActivityResponse
InspectActivityResponse contains the friendly activity row plus the lower-level records that explain how the daemon derived it.
entryWalletEntryentry is the user-facing activity row being inspected.
swapActivitySwapTraceswap is populated when the entry is backed by a pay or receive swap.
vtxosrepeated ActivityVTXOTracevtxos contains best-effort VTXO movements correlated to this activity. Rows are derived from local swap summaries and ledger accounting, so ids may be OOR session/output ids when a full VTXO outpoint is not persisted by the source row.
ledger_rowsrepeated ActivityLedgerTraceledger_rows are the local accounting rows used to build the trace, including rows hidden from the friendly activity feed.
notesrepeated stringnotes contains plain-English caveats about best-effort correlation.
WalletEntrymessage
WalletEntry is the single flat row type returned by the ACTIVITY view of List and by SubscribeWallet. The shape is deliberately minimal: display clients should be able to render kind/status/amount/fee/phase directly without parsing daemon-specific swap or ledger internals. Power-user detail belongs in WalletInspectionService.InspectActivity.
idstringid is the stable identifier for this entry. Swap-backed SEND and RECV rows use the Lightning payment_hash. Credit-backed RECV rows use the credit operation id (see CreditReceive.operation_id); the payment_hash lives on recv progress/detail instead. EXIT rows use leave_job_id (or sweep txid); DEPOSIT rows use the boarding outpoint or txid.
kindEntryKindkind is the user-visible category.
statusEntryStatusstatus is the coarse user-facing outcome: PENDING, COMPLETE, or FAILED. It mirrors the backing source's durable state and should not be reinterpreted by display clients.
amount_satint64amount_sat is signed: positive values are incoming to the wallet, negative values are outgoing.
fee_satint64fee_sat is the absolute fee paid (or pending) for this operation.
counterpartystringcounterparty is a short, display-friendly identifier of the other side: a truncated invoice for Lightning, an ark peer address for OOR, a bech32 onchain address for exits, or "boarding" for deposits.
created_at_unixint64created_at_unix is the local creation timestamp in unix seconds.
updated_at_unixint64updated_at_unix is the last persisted update timestamp in unix seconds. List ACTIVITY and SubscribeWallet sort by this field, descending.
notestringnote is the caller-supplied label captured at submit time, if any.
failure_reasonstringfailure_reason is populated only when status is FAILED. It is a single human-readable string, never a coded enum tree.
requestWalletEntryRequestrequest is the original payment request or destination associated with the entry, when the backing subsystem persists it. This is useful for expanded views and inspection; compact clients should not need to parse it to explain status or lifecycle.
progressWalletEntryProgressprogress carries lifecycle-specific metadata already normalized by the wallet service. Clients can render phase_label directly or switch on phase without inferring meaning from swap/ledger internals.
failure_codeEntryFailureCodeoptionalfailure_code is a stable, machine-readable classification of why a FAILED entry failed. It is set ONLY on FAILED entries; a non-failed entry omits the field entirely (presence-tracked), so its absence is the canonical "no failure" signal and ENTRY_FAILURE_CODE_UNSPECIFIED is never sent on the wire. failure_reason remains the human-readable supplement.
EntryKindenum
EntryKind tags each WalletEntry with the user-visible category of the underlying operation. Internal subtypes (same-Ark p2p vs real Lightning, OOR session correlators, round IDs) are deliberately not surfaced.
| Name | Number | Description |
|---|---|---|
ENTRY_KIND_UNSPECIFIED | 0 | ENTRY_KIND_UNSPECIFIED is the proto zero value used when the operation category is unknown. |
ENTRY_KIND_SEND | 1 | ENTRY_KIND_SEND is an outbound payment over any rail (Lightning, same-Ark, onchain, or credit). |
ENTRY_KIND_RECV | 2 | ENTRY_KIND_RECV is an inbound receive. |
ENTRY_KIND_DEPOSIT | 3 | ENTRY_KIND_DEPOSIT is a boarding deposit rolled into a VTXO. |
ENTRY_KIND_EXIT | 4 | ENTRY_KIND_EXIT is a cooperative leave or unilateral exit to on-chain funds. |
EntryStatusenum
EntryStatus collapses every backing FSM into the three states user-facing surfaces actually need.
| Name | Number | Description |
|---|---|---|
ENTRY_STATUS_UNSPECIFIED | 0 | ENTRY_STATUS_UNSPECIFIED is the proto zero value used when the backing state has not been mapped yet. |
ENTRY_STATUS_PENDING | 1 | ENTRY_STATUS_PENDING means the operation is still in flight. |
ENTRY_STATUS_COMPLETE | 2 | ENTRY_STATUS_COMPLETE means the operation reached a durable success state. |
ENTRY_STATUS_FAILED | 3 | ENTRY_STATUS_FAILED means the operation reached a terminal failure state. |
WalletEntryRequestmessage
WalletEntryRequest describes the user-recognizable request that created a WalletEntry. It is a oneof because each operation is backed by exactly one request shape.
lightning_invoiceLightningInvoiceRequestoneof requestlightning_invoice is populated for Lightning send and receive entries.
onchain_addressOnchainAddressRequestoneof requestonchain_address is populated for deposit and exit entries.
ark_addressArkAddressRequestoneof requestark_address is populated for direct Ark send or receive entries.
LightningInvoiceRequestmessage
LightningInvoiceRequest captures the Lightning request associated with an activity entry.
invoicestringinvoice is the BOLT-11 payment request.
payment_hashstringpayment_hash identifies the invoice and remains stable after the invoice itself is no longer convenient to display.
OnchainAddressRequestmessage
OnchainAddressRequest captures the onchain address associated with an activity entry.
addressstringaddress is the bech32 onchain address originally issued or targeted.
sweep_allboolsweep_all marks an onchain send that drained the selected VTXOs entirely (wavecli send --sweep-all). A sweep's pending amount is the gross outflow with the operator fee still baked in (the fee is only known once the leave round seals), so completion uses this marker to net the settled fee back out of the displayed amount. Bounded sends leave it false: their amount is the exact destination value and the fee is paid on top out of change.
ArkAddressRequestmessage
ArkAddressRequest captures the Ark address associated with an activity entry.
addressstringaddress is the Ark address originally issued or targeted.
WalletEntryProgressmessage
WalletEntryProgress carries lifecycle metadata normalized by the wallet service.
phaseWalletEntryPhasephase is the coarse lifecycle phase for this entry.
phase_labelstringphase_label is a short lowercase label that clients can render as-is while they migrate to enum-based presentation.
payment_hashstringpayment_hash is populated for Lightning-backed send/recv entries.
txidstringtxid is populated when the backing ledger row has an onchain txid.
confirmation_heightint32confirmation_height is populated once the source records it.
vtxo_outpointstringvtxo_outpoint is populated when a swap observes the Ark vHTLC output.
preimagestringpreimage is the hex-encoded Lightning payment preimage once the swap revealed it. For a completed Lightning-backed send this is the proof of payment for the paid invoice (sha256(preimage) == payment_hash); it is empty until the preimage is durably known and for non-Lightning entries.
WalletEntryPhaseenum
WalletEntryPhase is a coarse, wallet-facing lifecycle phase. It is not a replacement for status; status answers whether the operation is pending, complete, or failed, while phase explains the current backing-system step.
| Name | Number | Description |
|---|---|---|
WALLET_ENTRY_PHASE_UNSPECIFIED | 0 | WALLET_ENTRY_PHASE_UNSPECIFIED is the proto zero value used when the backing subsystem has no lifecycle hint. |
WALLET_ENTRY_PHASE_REQUEST_CREATED | 1 | WALLET_ENTRY_PHASE_REQUEST_CREATED means the request was created but no payment has been observed. |
WALLET_ENTRY_PHASE_WAITING_FOR_PAYMENT | 2 | WALLET_ENTRY_PHASE_WAITING_FOR_PAYMENT means the wallet is waiting for an inbound payment or swap funding. |
WALLET_ENTRY_PHASE_PAYMENT_DETECTED | 3 | WALLET_ENTRY_PHASE_PAYMENT_DETECTED means the backing subsystem has detected a payment but it is not yet settled. |
WALLET_ENTRY_PHASE_SETTLING | 4 | WALLET_ENTRY_PHASE_SETTLING means the operation is being settled through Ark, Lightning, or onchain machinery. |
WALLET_ENTRY_PHASE_CONFIRMED | 5 | WALLET_ENTRY_PHASE_CONFIRMED means the backing operation is confirmed or otherwise durably complete. |
WALLET_ENTRY_PHASE_REFUNDING | 6 | WALLET_ENTRY_PHASE_REFUNDING means the operation is currently refunding. |
WALLET_ENTRY_PHASE_REFUNDED | 7 | WALLET_ENTRY_PHASE_REFUNDED means the refund path completed. |
WALLET_ENTRY_PHASE_FAILED | 8 | WALLET_ENTRY_PHASE_FAILED means the backing operation reached a terminal failed state. |
WALLET_ENTRY_PHASE_WAITING_FOR_CONFIRMATION | 9 | WALLET_ENTRY_PHASE_WAITING_FOR_CONFIRMATION means an onchain payment has been detected and is waiting for block confirmation. |
EntryFailureCodeenum
EntryFailureCode is a stable, machine-readable classification of why a FAILED WalletEntry failed. It complements the free-text failure_reason so clients can branch on failure cause without string matching.
| Name | Number | Description |
|---|---|---|
ENTRY_FAILURE_CODE_UNSPECIFIED | 0 | ENTRY_FAILURE_CODE_UNSPECIFIED is the zero value used for non-failed entries or when the cause is unknown. |
ENTRY_FAILURE_CODE_TIMED_OUT | 1 | ENTRY_FAILURE_CODE_TIMED_OUT means the operation exceeded the wallet deadline before reaching a terminal state. |
ENTRY_FAILURE_CODE_EXPIRED | 2 | ENTRY_FAILURE_CODE_EXPIRED means the swap expired before it was funded. |
ENTRY_FAILURE_CODE_REFUNDED | 3 | ENTRY_FAILURE_CODE_REFUNDED means an outbound payment was refunded back to the wallet. |
ENTRY_FAILURE_CODE_NEEDS_INTERVENTION | 4 | ENTRY_FAILURE_CODE_NEEDS_INTERVENTION means the swap reached an anomalous state requiring manual recovery. |
ENTRY_FAILURE_CODE_FAILED | 5 | ENTRY_FAILURE_CODE_FAILED is a generic terminal failure with no more specific classification. |
ActivitySwapTracemessage
ActivitySwapTrace is the swap-service snapshot correlated to one wallet activity entry.
payment_hashstringpayment_hash is the Lightning payment hash that identifies the swap-backed activity.
directionstringdirection is the raw swapclientrpc.SwapDirection enum name, kept as a string so this debug surface can expose swap state without importing the swap service proto into the wallet proto.
statestringstate is the raw swapclientrpc.SwapState enum name at inspection time.
pendingboolpending is true while the backing swap state machine is still active.
amount_satint64amount_sat is the swap amount in satoshis using the swap service's unsigned amount convention.
fee_satuint64fee_sat is the fee reported by the swap service for this swap.
invoicestringinvoice is the BOLT-11 invoice associated with the swap when known.
vhtlc_outpointstringvhtlc_outpoint is the Ark vHTLC output observed for the swap when known.
vhtlc_amount_satint64vhtlc_amount_sat is the amount held by vhtlc_outpoint when known.
funding_session_idstringfunding_session_id is the OOR session that funded the swap when known.
claim_session_idstringclaim_session_id is the OOR session that claimed the swap when known.
refund_session_idstringrefund_session_id is the OOR session that refunded the swap when known.
terminal_reasonstringterminal_reason is the swap service's terminal reason string when the swap reached a failed or intervention state.
created_at_unixint64created_at_unix is the swap creation timestamp in unix seconds.
updated_at_unixint64updated_at_unix is the last swap update timestamp in unix seconds.
deadline_unixint64deadline_unix is the swap deadline in unix seconds when the swap service exposes one.
refund_locktimeuint32refund_locktime is the absolute locktime after which the swap can be refunded.
settlement_typestringsettlement_type is the raw swapclientrpc.SwapSettlementType enum name when known.
sender_pubkeystringsender_pubkey is the compressed SEC-encoded vHTLC sender key when known.
preimagestringpreimage is the hex-encoded Lightning payment preimage once the swap revealed it. For a completed pay swap this is the proof of payment for the paid invoice; it is empty until the preimage is durably known.
ActivityVTXOTracemessage
ActivityVTXOTrace describes one VTXO movement correlated to a wallet activity entry.
idstringid is the best available identifier. It is an outpoint when the source has one, otherwise an OOR session/output identifier.
amount_satint64amount_sat is the VTXO amount in satoshis.
rolestringrole is a short technical label such as "spent_input", "change_output", "materialized_output", or "vhtlc_output".
oursboolours is true when the row represents wallet-owned funds.
sourcestringsource names the local source used to derive the row, such as "ledger" or "swap".
session_idstringsession_id is the OOR session/correlation id when known.
output_indexuint32output_index is set when the source names a specific OOR output index.
ActivityLedgerTracemessage
ActivityLedgerTrace describes one local ledger row correlated to a wallet activity entry.
sourcestringsource names the subsystem that produced the row, such as "ledger" or "boarding_sweep".
typestringtype is the broad transaction group used by the wallet history query.
subtypestringsubtype is the ledger event type or sweep state.
amount_satint64amount_sat is the row amount in satoshis using the ledger sign convention.
fee_satint64fee_sat is the row's fee contribution in satoshis when the history query can derive one.
created_at_unixint64created_at_unix is the row creation timestamp in unix seconds.
confirmation_statusstringconfirmation_status is the best-known chain confirmation state for the row, for example "pending", "confirmed", or "recorded".
descriptionstringdescription is the local ledger description persisted with the row.
entry_idint64entry_id is the local ledger row id when the source is the ledger.
txidstringtxid is the associated chain transaction id when known.
debit_accountstringdebit_account is the local accounting debit account.
credit_accountstringcredit_account is the local accounting credit account.
round_idstringround_id is the Ark round id associated with the row when known.
session_idstringsession_id is the OOR session/correlation id associated with the row when known.
confirmation_heightint32confirmation_height is the confirmed block height when known.
hidden_from_activityboolhidden_from_activity is true when WalletService.List suppresses the row because it is an internal execution leg.
rolestringrole is the inspection role inferred for this row.
output_indexint32output_index is the transaction output index associated with txid. A negative value means the source has no output index.