# Resource filtering pattern

Heimdahl uses a consistent pattern-based filtering approach across all data types, with specific actions for accessing historical data and subscribing to real-time updates. This document explains our filtering pattern syntax, how to use it effectively, and why we chose this approach over alternative filtering methods.

### Pattern Structure

Heimdahl provides a consistent pattern structure across interfaces, with slight naming differences between command line and REST API and SDKs.

#### Command Line Interface

```
{resource} {action} {pattern}
```

Where:

* `{resource}` is the primary data category (event, transfer, swap) - singular form
* `{action}` is either `list` (for historical data) or `subscribe` (for real-time updates)
* `{pattern}` is a structured filtering expression using dot notation

#### REST API Interface

```
/{resources_plural}/{action}/{pattern}
```

Where:

* `{resources_plural}` is the primary data category in plural form (events, transfers, swaps) to follow RESTful conventions
* `{action}` is either `list` (for historical data) or `subscribe` (for real-time updates)
* `{pattern}` is the same structured filtering expression as used in the command line

### Actions

Heimdahl provides two primary actions for each resource type:

* **list**: Retrieves historical data matching the specified pattern
* **subscribe**: Creates a real-time subscription for new data matching the pattern

### Pattern Syntax By Resource Type

Each resource type has a specific pattern format that reflects its unique properties:

#### Event Pattern

```
event list {chain}.{network}.{token_address}.{event_name}
event subscribe {chain}.{network}.{token_address}.{event_name}
```

Examples:

```
event list base.mainnet.0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.Transfer
event subscribe base.mainnet.0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.Transfer
```

The first query returns historical Transfer events, while the second creates a real-time subscription.

#### Transfer Pattern

```
transfer list {chain}.{network}.{symbol}.{sender_addr}.{receiver_addr}.{size}
transfer subscribe {chain}.{network}.{symbol}.{sender_addr}.{receiver_addr}.{size}
```

Examples:

```
transfer list base.mainnet.usdc.all.all.all
transfer subscribe base.mainnet.usdc.all.all.all
```

The first query returns historical USDC transfers, while the second subscribes to new transfers as they occur.

#### Swap Pattern

```
swap list {chain}.{network}.{symbol1}.{symbol2}.{size}
swap subscribe {chain}.{network}.{symbol1}.{symbol2}.{size}
```

Examples:

```
swap list ethereum.mainnet.usdc.weth.all
swap subscribe ethereum.mainnet.usdc.weth.all
```

The first query returns historical USDC-WETH swaps, while the second creates a real-time subscription.

### Using the `all` Placeholder

The keyword `all` serves as a wildcard for any field you don't want to filter on. This allows for flexible queries that can be refined as needed:

**CLI examples:**

```
transfer list base.mainnet.usdc.all.all.all   # All historical USDC transfers on Base mainnet
transfer subscribe base.mainnet.usdc.0x123...abc.all.all   # Subscribe to new USDC transfers from a specific address
swap list ethereum.mainnet.all.weth.all   # All historical swaps involving WETH on Ethereum mainnet
```

**REST API examples:**

```
/transfers/list/base.mainnet.usdc.all.all.all   # All historical USDC transfers on Base mainnet
/transfers/subscribe/base.mainnet.usdc.0x123...abc.all.all   # Subscribe to new USDC transfers from a specific address
/swaps/list/ethereum.mainnet.all.weth.all   # All historical swaps involving WETH on Ethereum mainnet
```

### Examples

Below are examples showing both CLI and REST API usage for the same queries:

#### Events for a Specific Contract

**CLI:**

```
event list ethereum.mainnet.0x6B175474E89094C44Da98b954EedeAC495271d0F.Transfer
```

**REST API:**

```
/events/list/ethereum.mainnet.0x6B175474E89094C44Da98b954EedeAC495271d0F.Transfer
```

#### Real-time Transfer Monitoring by Token

**CLI:**

```
transfer subscribe ethereum.mainnet.dai.all.all.all
```

**REST API:**

```
/transfers/subscribe/ethereum.mainnet.dai.all.all.all
```

#### Historical Transfers from a Specific Sender

**CLI:**

```
transfer list ethereum.mainnet.usdc.0x123...abc.all.all
```

**REST API:**

```
/transfers/list/ethereum.mainnet.usdc.0x123...abc.all.all
```

#### Real-time Swap Monitoring Between Specific Token Pairs

**CLI:**

```
swap subscribe ethereum.mainnet.usdc.weth.all
```

**REST API:**

```
/swaps/subscribe/ethereum.mainnet.usdc.weth.all
```

### Why Pattern-based Filtering?

#### Consistency Across Methods

The same pattern structure works for both historical data retrieval and real-time subscriptions, creating a unified query language for all interactions with Heimdahl.

#### Cross-Chain Scalability

Our pattern approach provides a unified syntax that works across all supported blockchains while respecting their unique characteristics. Adding support for new chains doesn't change the fundamental query structure.

#### Parameter Extensibility

As we add support for new filtering parameters, the pattern syntax naturally accommodates them in a consistent way. This future-proofs your integration with Heimdahl.

#### Readability and Brevity

Patterns using dot notation are more concise and readable than traditional query parameters:

**CLI:**

```
# Pattern approach
transfer list ethereum.mainnet.usdc.0x123...abc.all.all

# Traditional query parameters approach would be more verbose
transfer --chain=ethereum --network=mainnet --token=usdc --sender=0x123...abc
```

**REST API:**

```
# Pattern approach
/transfers/list/ethereum.mainnet.usdc.0x123...abc.all.all

# Traditional query parameters
/transfers/list?chain=ethereum&network=mainnet&token=usdc&sender=0x123...abc
```

### Dotted Pattern vs. Flag-based Filtering

Many blockchain APIs use traditional flag or parameter-based filtering. While familiar, this approach has several disadvantages that our dotted pattern syntax addresses:

1. **Simplicity**: Dotted patterns create a natural hierarchy that's easy to understand and remember
2. **Consistency**: The same pattern structure works across all data types and interfaces
3. **Brevity**: Patterns require significantly fewer characters than equivalent flag-based queries
4. **Extensibility**: New filtering parameters can be added without changing the API structure
5. **Readability**: Patterns visually represent the relationship between filter parameters

For example, a typical flag-based query might look like:

```
?chain=ethereum&network=mainnet&token=usdc&sender=0x123...abc
```

While our dotted pattern approach simplifies this to:

```
ethereum.mainnet.usdc.0x123...abc.all.all
```

This approach scales much better as your queries become more complex.

### Advanced Usage

#### Pattern Refinement

Start with broader patterns and refine as needed:

**CLI:**

```
# Start with all historical USDC transfers
transfer list ethereum.mainnet.usdc.all.all.all

# Refine to specific senders
transfer list ethereum.mainnet.usdc.0x123...abc.all.all

# Subscribe to specific transfers between two addresses
transfer subscribe ethereum.mainnet.usdc.0x123...abc.0x456...def.all
```

**REST API:**

```
# Start with all historical USDC transfers
/transfers/list/ethereum.mainnet.usdc.all.all.all

# Refine to specific senders
/transfers/list/ethereum.mainnet.usdc.0x123...abc.all.all

# Subscribe to specific transfers between two addresses
/transfers/subscribe/ethereum.mainnet.usdc.0x123...abc.0x456...def.all
```

### Implementation Notes

When implementing clients to work with our API, we recommend:

1. Building pattern-construction utilities to help users create valid patterns
2. Creating template functions for common queries (list vs. subscribe)
3. Implementing proper subscription management for real-time data

### Conclusion

Our pattern-based filtering approach provides a powerful, consistent, and future-proof way to query blockchain data across different chains and data types. By using the same pattern syntax for both historical (`list`) and real-time (`subscribe`) data access, Heimdahl creates a unified experience that simplifies blockchain data integration.
