Time Labels: Backwards-Compatible Action Timestamp Filters for List Actions

Brayden Langley ([email protected])

Abstract

This specification defines a backwards-compatible extension to BRC-100 that allows applications to filter listActions results by wallet-tracked action timestamps using reserved query labels. The response format remains unchanged.

Motivation

Wallet applications often need time-windowed action data for analytics and user insights, such as:

• "What app did I spend the most on this week?"

• "How did my balance change over time?"

• "Show spending for today in the user's local timezone."

Wallet-toolbox implementations already track action timestamps. This specification standardizes how applications request timestamp filtering without changing the listActions API surface.

Specification

Reserved Query Label Namespace

This specification reserves only the following exact listActions query-control label forms:

• action time from <unixMillis>

• action time to <unixMillis>

Other labels (including labels that begin with time or action time ) remain valid ordinary labels unless they exactly match one of the reserved query-control forms above.

Timestamp Filter Labels

Timestamp filtering is requested by including one or both reserved labels in listActions:

• action time from <unixMillis>

• action time to <unixMillis>

Where <unixMillis> is an unsigned decimal integer representing Unix time in milliseconds since 1-Jan-1970 UTC.

Examples:

• listActions({ labels: ["expenses", "action time from 1738368000000", "action time to 1740787200000"] })

• listActions({ labels: ["action time from 1738368000000"] })

Request vs Response Label Forms

This specification defines two distinct label roles:

• Request control labels: action time from <unixMillis> and action time to <unixMillis> (input to listActions filtering).

• Response timestamp label: action time <unixMillis> (output annotation in returned action labels).

The wallet must not interpret action time <unixMillis> as a timestamp-filter control label in requests.

Required Behavior

When listActions includes at least one timestamp filter label:

• The wallet must partition args.labels into:

  1. Timestamp control labels (action time from <unixMillis>, action time to <unixMillis>).

  2. Remaining ordinary labels (all other labels, such as awesomeActions).

• Timestamp control labels must not be matched as ordinary action labels.

• The wallet must apply timestamp filtering against its internally tracked action timestamp for each action.

• action time from is an inclusive lower bound (timestamp >= from).

• action time to is an exclusive upper bound (timestamp < to).

• The wallet must apply filtering in this order:

  1. Apply timestamp filtering first.

  2. Apply ordinary label filtering rules from BRC-100 to the remaining (non-time-filter) labels.

• The wallet must still enforce normal permission checks; timestamp filters must not bypass or weaken permissions.

• The wallet must return the normal listActions response shape. No new response fields are introduced.

• totalActions, limit, and offset must be computed against the fully filtered result set.

If no non-time-filter labels remain after parsing, the wallet must treat the request as "all permitted actions within the specified time range."

Example:

• labels: ["action time from <unixMillis>", "action time to <unixMillis>", "awesomeActions"] must return actions with the awesomeActions label that also fall within the specified time range.

Returned Timestamp Labels

When listActions uses timestamp filter labels and includeLabels is true, each returned action must include exactly one timestamp label in its labels array:

• action time <unixMillis>

Where <unixMillis> is the same canonical wallet-tracked timestamp value used for filtering that action.

Additional rules:

• The wallet must include this label only when includeLabels is true.

• If the action already contains the same action time <unixMillis> label, the wallet must avoid duplicating it.

• The action time <unixMillis> label is response-derived query metadata and must not be persisted as a normal action label.

Timestamp Source

Wallets must use their canonical per-action wallet-tracked timestamp (the same timestamp source used by the wallet for action chronology and indexing). If an action has no timestamp in that source, the action must be excluded whenever timestamp filtering is requested.

When both a creation timestamp and an update timestamp are available for an action record, wallets must use the creation timestamp for action time from / action time to filtering and for the derived action time <unixMillis> response label. Update timestamps must not affect time-bucket membership for this specification.

Validation Rules

• The request control prefixes action time from and action time to must be lowercase and followed by a single space.

• The response timestamp label prefix must be exactly action time (lowercase, single trailing space before the value).

• Each request may include at most one action time from label and at most one action time to label.

• Timestamp values must be valid unsigned base-10 integers representing Unix milliseconds.

• If both bounds are present and from >= to, the wallet must return an error.

• If a label uses action time from or action time to but has an invalid timestamp value, the wallet must return an error.

• If a request label begins with action time but does not match either reserved request control form, the wallet must treat it as an ordinary label (not as a timestamp filter control label).

• All labels must still comply with general label constraints in BRC-100 and module label rules in BRC-111.

Timezone Guidance

Timezone-specific views (day/week/month in a user locale) are achieved by computing local window boundaries in the application, converting those boundaries to Unix milliseconds UTC, and supplying them via action time from and action time to.

Conclusion

By reserving action time from and action time to labels for listActions, this specification enables interoperable timestamp-range querying while preserving backwards compatibility and existing wallet permission models.