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

Brayden Langley (<brayden@projectbabbage.com>)

## Abstract

This specification defines a backwards-compatible extension to [BRC-100](/wallet/0100.md) 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](/wallet/0100.md) 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](/wallet/0100.md) and module label rules in [BRC-111](/wallet/0111.md).

### 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bsv.brc.dev/wallet/0114.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.