NEBU /ˈnɛ.buː/
ROOT / DOCS / SCHEMAS

# SCHEMAS

Every event nebu emits carries a self-describing _schema identifier. This is the index.

Schemas are versioned independently from the CLI. A processor at v0.9 can still emit nebu.token_transfer.v1 — and should, until the shape of the data actually changes.

## VERSIONING_POLICY

BREAKING → BUMP

These increment the version (v1 → v2):

  • · rename a field
  • · remove a field
  • · change a field's type
  • · change an enum value
  • · flatten or restructure nested objects
NON-BREAKING → KEEP

These do not bump the version:

  • · add a new field
  • · add a new optional field
  • · add a new event type under the same schema
  • · expand the set of enum values

When a breaking change ships, old and new versions can both exist in a pipeline. Filter by _schema if you need to keep the old behavior.

## ENVELOPE

Every event has the same two metadata fields at the top level, regardless of which processor emitted it:

json ENVELOPE 
{
  "_schema":        "<namespace>.<name>.v<N>",  // identifier — required
  "_nebu_version": "v0.6.7",                     // producing nebu CLI — required
  "meta":           { /* common ledger metadata */ },
  ...payload...
}

meta typically contains ledgerSequence, closedAtUnix, txHash, transactionIndex, and contractAddress (when applicable). Exact fields are defined per schema below.

## REGISTRY

Schemas emitted by reference processors. Community processors add their own under different namespaces — browse the community registry.

nebu.token_transfer.v1 [ STABLE · since v0.3.0 ]

One event per classic or Soroban token transfer observation. Emitted by token-transfer.

[ EVENT TYPES ]
transfer · mint · burn · clawback · fee
[ PAYLOAD KEY ]
transfer
json · shape 
{
  "_schema":        "nebu.token_transfer.v1",
  "_nebu_version": "v0.6.7",
  "meta": {
    "ledgerSequence":   60200000,
    "closedAtUnix":     "1765158311",
    "txHash":           "abc...",
    "transactionIndex": 1,
    "contractAddress":  "CA..."
  },
  "transfer": {
    "type":        "transfer",
    "from":        "GA...",
    "to":          "GB...",
    "assetCode":   "USDC",
    "assetIssuer": "GA5Z...",
    "amount":      "1000000"
  }
}

Full field reference: SCHEMA.md.

nebu.contract_events.v1 [ STABLE ]

One event per Soroban diagnostic event emission. Raw XDR SCVals in topics and data.

json · shape 
{
  "_schema":        "nebu.contract_events.v1",
  "_nebu_version": "v0.6.7",
  "meta":           { ... },
  "event": {
    "contractAddress": "CAQ...",
    "type":            "contract",
    "topics":          [ "transfer", "GA...", "GB..." ],
    "data":            { "i128": "1000000" }
  }
}
nebu.contract_invocation.v1 [ STABLE ]

One event per Soroban InvokeHostFunction operation, with function name, arguments, success flag, and nested sub-invocations.

json · shape 
{
  "_schema":        "nebu.contract_invocation.v1",
  "_nebu_version": "v0.6.7",
  "meta":           { ... },
  "invocation": {
    "contractAddress": "CAQ...",
    "function":        "swap",
    "args":            [ ... ],
    "success":         true,
    "subInvocations":  [ /* recursive */ ]
  }
}
nebu.transaction_stats.v1 [ EXAMPLE ]

One event per ledger close, summarizing transaction activity. Emitted by the educational transaction-stats processor.

json · shape 
{
  "_schema":        "nebu.transaction_stats.v1",
  "_nebu_version": "v0.6.7",
  "meta":           { "ledgerSequence": 60200000, "closedAtUnix": "..." },
  "stats": {
    "txTotal":    42,
    "txSuccess":  41,
    "txFailed":   1,
    "opsTotal":   87,
    "feeCharged": "4200000"
  }
}
nebu.ledger_change_stats.v1 [ EXAMPLE ]

One event per ledger close, counting ledger entry changes by entry type.

json · shape 
{
  "_schema": "nebu.ledger_change_stats.v1",
  "meta":    { "ledgerSequence": 60200000 },
  "changes": {
    "accounts":    { "created": 3, "updated": 120, "removed": 0 },
    "trustlines":  { "created": 2, "updated": 40, "removed": 1 },
    "data":        { "created": 0, "updated": 5, "removed": 0 },
    "contractData": { "created": 8, "updated": 23, "removed": 0 }
  }
}

## NAMING

Schema identifiers are three segments joined with dots:

<namespace>.<name>.v<N>

namespace — nebu for reference processors, your org/handle for community ones (e.g. blend, soroswap).

name — snake_case description of the event family. Singular noun preferred.

version — integer after v. Starts at v1. Bump on breaking changes only.

Don't reuse a version for a different payload shape. Downstream consumers use _schema as a cache key.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OBSRVR NEBU(7)