Nodes, edges, and the shape of the risk graph

In Lesson 1 you learned the graph is the output: events in, edges out. Now we open the box. By the end you'll know what a node actually is, the eight families the edges fall into, and the three node properties every contributor must respect — get one wrong and your query silently returns garbage or scans the whole DB.

1 · A node is an :Entity

Here's the first surprising thing. Almost every node in the graph carries the same primary label: :Entity. The kind of thing it is (token, vault, multisig…) lives in a property, and is also mirrored as a secondary label.

The node's identity is its address (id). There are 19 node types — the full list is in pkg/types/schema.go as NodeType constants and lives in your glossary. A few you'll meet constantly:

Source: pkg/types/schema.go — NodeType constants + NodeTypeToLabel map.

2 · The three properties that will bite you

① graph_id — the partition key

One Memgraph instance holds multiple independent graphs side by side, separated only by the graph_id property on every node and every edge. The live one might be risk-graph-rt; a shadow/test one might be test_carlos. They share the database but must never mix in a query.

② category / subcategory — with a legacy trap

Current code stores a node's kind in category + subcategory. But older nodes carry type + subtype instead. The repo's own CLAUDE.md mandates the defensive read:

// Reading a node's kind safely across old + new nodes (from CLAUDE.md):
coalesce(n.type, n.subcategory, n.category)

Source: risk-graph-indexer/CLAUDE.md § Sanity checks. coalesce returns the first non-null — so it works whether the node is legacy (type) or current (category).

③ pending_enrichment — the lifecycle flag

From Lesson 1: the indexer creates bare nodes with pending_enrichment=true, and the enrichment-worker flips it to false once it's classified. So this boolean tells you whether a node's metadata (symbol, decimals, labels) can be trusted yet.

3 · Edges roll up into eight categories

There are ~19+ edge types, but you don't memorise them flat — they group into eight parent categories (the EdgeCategory map in schema.go). Learn the categories and the types slot in underneath:

Source: pkg/types/schema.go — the EdgeCategory map. The full edge list with directions + properties lives in your glossary.

4 · Reading your first Cypher

Cypher is "ASCII-art SQL for graphs." Nodes are (parens), edges are -[brackets]-> with a direction. Here's a real-shaped read — "what tokens does this wallet hold?":

MATCH (w:Entity {id: $wallet, graph_id: $g})-[r:HOLDS]->(t:Entity {graph_id: $g})
RETURN t.symbol, r.quantity_raw, t.usd_price

Read it left to right: start at the wallet node w (anchored by its id), follow an outgoing HOLDS edge r, to a token node t. Return the token's symbol, the raw balance on the edge, and its price.

Notice three things, all of which are rules, not style:

• Both nodes are :Entity and both carry graph_id: $g — partition-scoped, per Rule #1.
• It's anchored at a known id — it starts from one node, not the whole graph.
• The edge has a direction (->). HOLDS goes wallet→token.

Source: risk-graph-indexer/CLAUDE.md § "Graph DB queries — no brute-force" and § "Before writing code". Real query shapes verified against pkg/ (e.g. the :HOLDS reads in the graphwrite/risk packages).

Check yourself

Instant feedback — these target the exact things that trip up new contributors.

What you can now do

• Describe a node: an :Entity keyed by address id, scoped by graph_id.
• Name the three properties that bite — graph_id, category/type, pending_enrichment — and the coalesce read.
• Place any edge into one of the eight categories, and tell architectural from analytical.
• Read a simple anchored, partition-scoped Cypher MATCH, and recite the three query rules.