> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Stellar Horizon → RPC Migration (v2)

> Stellar raw and assets schemas are migrating from Horizon-API-sourced (v1) to Stellar-RPC-sourced (v2) datasets. Migrate your queries to the _v2 tables before the cutover.

<Warning>
  **Important**: Stellar's raw and assets datasets are migrating from the Horizon API to the Stellar RPC. The Stellar-RPC-sourced (`v2`) tables are available now — **switch your queries to the `v2` datasets by 10 July 2026**. Some legacy entities (`effects`, `contract_events`) are being deprecated entirely.
</Warning>

## Overview

Stellar's [Horizon API is being deprecated](https://developers.stellar.org/docs/data/apis/migrate-from-horizon-to-rpc). Allium has re-built its Stellar raw and enriched datasets directly from the **Stellar RPC**. These are the `v2` datasets that will be supported moving forward.

One of the core benefits of the `v2` datasets is **complete, accurate historical token transfers and balances**. The Stellar RPC exposes a [unified events stream](https://stellar.org/blog/developers/stellar-events-track-all-the-things) that captures all token movement — classic operations and contract events — in one place. This lets Allium ingest a full history of token transfers and compute balances directly from on-chain events.

## Migration approach

Migration happens in two phases:

<Steps>
  <Step title="Switch to the v2 datasets — by 10 July 2026">
    Update your workflows to query the `_v2` tables (and the new RPC-sourced enriched tables) listed below by **10 July 2026**. Both `v1` and `v2` pipelines run in parallel during this transition period.
  </Step>

  <Step title="Suffix removal (future, separate notice)">
    Once customers have transitioned, the `_v2` suffix will be dropped — e.g. `stellar.raw.ledgers_v2` will be renamed back to `stellar.raw.ledgers`. **We'll send a separate notice with the timeline before this rename happens** — no action is needed on this step yet. (see [What to do](#what-to-do)).
  </Step>
</Steps>

## Table migration

<table>
  <thead>
    <tr><th>Current table (v1, Horizon)</th><th>New table (v2, Stellar RPC)</th><th>Notes</th></tr>
  </thead>

  <tbody>
    <tr>
      <td>`stellar.raw.ledgers`</td>
      <td>`stellar.raw.ledgers_v2`</td>
      <td>v2 adds count columns for the new related entities, e.g. `token_transfer_count`, `balance_snapshot_count`, `event_count`. Some existing count columns are updated to reflect v2 entity logic.</td>
    </tr>

    <tr>
      <td>`stellar.raw.transactions`</td>
      <td>`stellar.raw.transactions_v2`</td>
      <td>Some columns removed (see [schema changes](#raw-transactions)); shape of some data may differ.</td>
    </tr>

    <tr>
      <td>`stellar.raw.operations`</td>
      <td>`stellar.raw.operations_v2`</td>
      <td>Some columns removed and the `operation_details` JSON shape has changed (see [schema changes](#raw-operations)).</td>
    </tr>

    <tr>
      <td>`stellar.raw.diagnostic_events`</td>
      <td>`stellar.raw.diagnostic_events_v2`</td>
      <td>v2 contains **only** diagnostic events. In v1 this table also included contract events — those now live in the new `stellar.raw.events` entity.</td>
    </tr>

    <tr>
      <td>`stellar.raw.effects`</td>
      <td>*Deprecated — no replacement*</td>
      <td>Removed in v2. As advised by the Stellar Foundation, effects are no longer required. Use `stellar.raw.events` / `stellar.raw.token_transfers` for token movement instead.</td>
    </tr>

    <tr>
      <td>`stellar.raw.contract_events`</td>
      <td>*Deprecated — folded into `stellar.raw.events`*</td>
      <td>Contract events are now part of the new unified `stellar.raw.events` entity.</td>
    </tr>

    <tr>
      <td>`stellar.assets.fungible_balances`</td>
      <td>`stellar.raw.balance_snapshots` (unhydrated) / `stellar.assets.balances` (hydrated)</td>
      <td>**Action required.** The legacy `fungible_balances` computes balances via a cumulative sum of transfers and is prone to errors. Switch to `balance_snapshots` / `assets.balances` for accurate data. `assets.fungible_balances` will later be re-pointed at `balance_snapshots`.</td>
    </tr>
  </tbody>
</table>

### New entities (v2 only)

The Stellar RPC migration introduces new RPC-sourced entities that have no `v1` equivalent:

| Entity            | Table                                                                    | Description                                                                 |
| ----------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Events            | `stellar.raw.events`                                                     | Unified events stream — classic operations + contract events in one entity. |
| Token transfers   | `stellar.raw.token_transfers`, `stellar.assets.fungible_token_transfers` | Complete historical token transfers from the events stream.                 |
| Balance snapshots | `stellar.raw.balance_snapshots`, `stellar.assets.balances`               | Accurate per-ledger balances.                                               |
| Tokens            | `stellar.tokens`                                                         | Token metadata.                                                             |

<Note>
  NFT token transfers and balances are also available in the same tables — filter on `token_id is not null` (e.g. `select * from stellar.raw.token_transfers where token_id is not null`).
</Note>

## Schema changes

<AccordionGroup>
  <Accordion title="Raw transactions — removed columns" icon="table">
    <span id="raw-transactions" />

    The following columns are removed in `stellar.raw.transactions_v2`:

    * `SOURCE_ACCOUNT_MUXED`
    * `SOURCE_ACCOUNT_SEQUENCE`
    * `MEMO_BYTES`
    * `FEE_ACCOUNT_MUXED`
    * `FEE_ACCOUNT_MUXED_ID`
    * `ENVELOPE_XDR`
    * `FEE_META_XDR`
    * `RESULT_XDR`
    * `RESULT_META_XDR`
  </Accordion>

  <Accordion title="Raw operations — removed columns & operation_details shape" icon="table">
    <span id="raw-operations" />

    Removed columns in `stellar.raw.operations_v2`:

    * `SOURCE_ACCOUNT_MUXED`
    * `SOURCE_ACCOUNT_MUXED_ID`

    The `operation_details` JSON shape has changed. Example:

    **Old (v1):**

    ```json theme={null}
    {
      "amount": "8.1569786",
      "buying_asset_type": "native",
      "offer_id": "1804392843",
      "parameters": null,
      "price": "0.1199950",
      "price_r": { "d": 200000, "n": 23999 },
      "selling_asset_code": "WGS",
      "selling_asset_issuer": "GBBTHBKKYEO72Y2ZC5URURGQU6XWD26FFQVZELRSE5YDLRHPS6MITWGS",
      "selling_asset_type": "credit_alphanum4"
    }
    ```

    **New (v2):**

    ```json theme={null}
    {
      "amount": 81569786,
      "buying": "native",
      "offer_id": 1804392843,
      "price": { "d": 200000, "n": 23999 },
      "selling": {
        "credit_alphanum4": {
          "asset_code": "WGS",
          "issuer": "GBBTHBKKYEO72Y2ZC5URURGQU6XWD26FFQVZELRSE5YDLRHPS6MITWGS"
        }
      }
    }
    ```

    Note that amounts are now raw integers (not decimal strings) and asset details are nested under the asset type.
  </Accordion>

  <Accordion title="Diagnostic events — narrowed scope" icon="table">
    `stellar.raw.diagnostic_events_v2` contains **only** diagnostic events. In v1, this table also included contract events. Contract events are now available in the new unified `stellar.raw.events` entity.
  </Accordion>
</AccordionGroup>

## What to do

1. **Update your queries** to read from the `_v2` tables and the new RPC-sourced entities using the mappings above.
2. **Switch your balances source** from `stellar.assets.fungible_balances` to `stellar.raw.balance_snapshots` (unhydrated) or `stellar.assets.balances` (hydrated) for accurate historical balances.
3. **Stop referencing deprecated entities** — `stellar.raw.effects` and `stellar.raw.contract_events` will be removed. Move token-movement logic to `stellar.raw.events` / `stellar.raw.token_transfers`.
4. **Adjust for removed columns and the new `operation_details` shape** in transactions and operations.
5. **Use the colon-delimited `asset_id` format.** In the `v2` datasets, `asset_id` is formatted as `code:issuer` (e.g. `USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN`) — a colon (`:`), not a hyphen (`-`). Update any queries that filter, join, or parse on `asset_id` to expect the colon-delimited form.
6. **Prepare for the eventual suffix removal** — after the transition period the `_v2` suffix will be dropped (`ledgers_v2` → `ledgers`, etc.). We'll send a separate notice with the timeline before this happens, so no action is needed yet.

## Support

If this migration impacts your workflows or you need help, reach out to [support@allium.so](mailto:support@allium.so) or your account team.