# Writing RPCX Methods

> Write methods in the RPCX method language: the header and params, the pipeline, the correctness rules, and the validation report.

Canonical: https://nolimitnodes.com/docs/api-reference/rpcx/writing-methods

A method is plain text in the RPCX method language. It has a header with the name and params, then a pipeline that starts from a table and shapes the rows. Save it with a name and it becomes callable as `rpcx_`.

```text RPCX method
method txsFor(wallets: pubkey[] "Accounts", from: time, to: time) {
  from live_transactions
  filter (address | in wallets) && ts >= from && ts (, , ...) {
```

- The name is 1 to 64 letters, digits, or underscores. You call the method as `rpcx_`.
- Each param is `name: type`. Add `= value` for a default and a double-quoted string for a description: `limit: uint64 = 10 "How many wallets"`.
- A param is required unless it has a default or a `?` after its name: `wallet?: pubkey`. A `?` param that a call leaves out is `null`, so `filter (wallet == null || user == wallet)` makes the filter optional. See [Optional filters](/docs/api-reference/rpcx/language#optional-filters).
- Params may span several lines, and a trailing comma is allowed.
- Lines that start with `#` are comments.

### Param types

| Type | Accepts |
|---|---|
| `pubkey` | A base58 Solana address |
| `signature` | A base58 transaction signature |
| `string` | Any text |
| `uint64` | An integer from 0 to 2^64 - 1 |
| `int64` | A signed 64-bit integer |
| `float64` | A number |
| `bool` | `true` or `false` |
| `time` | A UTC time, as RFC 3339 or `YYYY-MM-DD`. `datetime` and `timestamp` mean the same. |
| `pubkey[]` | A list of base58 Solana addresses, as a JSON array |
| `signature[]` | A list of base58 transaction signatures, as a JSON array |
| `string[]` | A list of texts, as a JSON array |
| `uint64[]` | A list of integers from 0 to 2^64 - 1, as a JSON array |

A default is a number, a double-quoted string, `true`, or `false`. A list param holds up to 1,000 values. Use it with `in`: `filter (address | in wallets)`.

### Params in the body

- A bare name that matches a param means the param. In `filter address == wallet`, `address` is a column and `wallet` is the param.
- `$name` also means the param, for example `filter fee >= $min_fee`.
- When a column has the same name as a param, write `this.` for the column.

## The pipeline

The body is a pipeline. Each line is one step, and each step works on the rows from the step before. The language is based on [PRQL](https://prql-lang.org/book/). The [Method language reference](/docs/api-reference/rpcx/language) lists every step, function, and operator with an example.

| Step | Form | What it does |
|---|---|---|
| `from` | `from ` | Start from a table. `from s = ` gives it a short name. |
| `filter` | `filter ` | Keep rows where the condition is true. |
| `derive` | `derive { = , ...}` | Add computed columns and keep the others. |
| `select` | `select {,  = , ...}` | Keep only these columns. |
| `sort` | `sort {, -}` | Order rows. A leading `-` sorts descending. |
| `take` | `take ` or `take ..` | Keep the first n rows. An integer param works: `take limit`. |
| `group` | `group {, ...} ()` | Run the inner pipeline once per group, usually `aggregate`. With `sort` and `take` inside, it keeps the top rows per group. |
| `aggregate` | `aggregate { = , ...}` | Reduce all rows, or each group, to one row. |
| `join` | `join side:left  = (from  \| filter ) (==)` | Join another table, read with its own key or range. `side` is `inner` (default), `left`, `right`, or `full`. |
| `window` | `window rows:.. ()` | Compute columns over a sliding frame of rows, in the current sort order. |

There is no `distinct` step. To keep one row per value, use `group {} (take 1)`.

`let` names a relation or a function you use later in the method.

### Functions

| Kind | Functions |
|---|---|
| Aggregate | `count this`, `count_distinct`, `sum`, `average`, `min`, `max`, `first`, `last` |
| Window | `row_number this`, `rank`, `rank_dense` |
| Math | `math.round`, `math.abs`, `math.floor`, `math.ceil`, `math.pow`, `math.sqrt`, `math.exp`, `math.ln`, `math.log10`, `math.log` |
| Text | `text.lower`, `text.upper`, `text.trim`, `text.ltrim`, `text.rtrim`, `text.length`, `text.extract`, `text.replace`, `text.starts_with`, `text.contains`, `text.ends_with` |
| Time | `date.to_text`, `date.trunc`, `date.diff` |
| Other | `in` (a range, a list, or a list param), `as` (convert to a type such as `DOUBLE` or `Float64`) |

Arguments follow the function name without parentheses, for example `date.trunc "hour" ts` or `math.round 2 x`. In the dashboard, the Code tab completes table names, columns, params, and functions as you type.

Operators: `==`, `!=`, `>`, `>=`, `` for any address (a wallet, a program, a pool, a mint, or a token account), `sig == ` for one transaction, or on `live_instructions` `program == `. On `live_accounts` the key is `address`, and on `live_token_accounts` it is `owner`. For many values, use `(address | in )` or a literal list `(address | in ["A...", "B..."])`.
- **A bounded range**, on a chain table: `ts >= from && ts = start && slot = from && ts = from && ts = from && ts = from && ts = from && ts `. **Run** in the dashboard needs the saved method, so save before you run it.

Saving the same name again creates a new version and makes it active. Deleting a method deletes every version, and calls to it fail from then on. See [Calling RPCX methods](/docs/api-reference/rpcx/calling-methods).

## Read the validation report

**Validate** returns errors, which block the method, and warnings, which do not. In the dashboard, each problem is marked in the code. Fix every error. Read every warning.

Problems in the method text itself have a line and column, and their codes start with `dsl_` in the report.

| Code | Level | What to do |
|---|---|---|
| `dsl_syntax` | error | Fix the text at the marked place. The text must start with `method () {` and end with `}`. |
| `dsl_unknown_type`, `dsl_bad_default`, `dsl_bad_name`, `dsl_duplicate_param` | error | Fix the param in the header. |
| `dsl_unknown_param`, `dsl_type_mismatch` | error | Declare the param in the header, or give it a type that fits where it is used. |
| `dsl_raw_sql_not_allowed`, `dsl_not_allowed` | error | Remove the s-string or the construct. Use the listed steps and functions. |
| `dsl_compile` | error | The pipeline cannot be built. Read the message at the marked place. |
| `unknown_table` | error | Use one of the nine live tables from `list_tables`. |
| `live_key_missing` | error | Add a key or a bounded range to the filter right after `from live_...`: `address == `, `(address \| in )`, `sig == `, `program == ` on `live_instructions`, `owner` on `live_token_accounts`, or `ts >= from && ts < to` on a chain table. |
| `dry_run_failed` | error | The method was checked on empty tables and refused, for example because a column does not exist. Read the message. |
