Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them
Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here’s what that means for your queries.
Blockchains do not always agree on the most recent blocks. For a short window near the tip, the network can
reorganize: a block that looked final gets replaced by a competing block at the same height, and anything
only in the replaced block is no longer part of the canonical chain. Data Feeds handle this for you, but it
shapes one thing you must get right: how you read the most recent rows.
Each block carries its position (the block number) and its block hash, and the feed tracks the link
back to the parent block. When the sink sees that a block at a given position has been replaced by a
different hash, it knows the earlier block’s rows are no longer canonical.Rather than silently deleting them, the sink writes a correction. The original rows were written with a
+1 marker; the reorg emits matching -1 rows for the same data. The pair cancels out, and the rows from
the new, canonical block are written in their place. Your table converges on the true chain without you
re-running anything.
The correction rows are how reorgs stay safe, but they mean a naive SELECT * over a ClickHouse fact table
can briefly show both the original and its -1 cancel. You apply the corrections at read time:
On ClickHouse fact tables, read with FINAL (or use sign-aware sums). That applies reorg corrections and
gives you the canonical result.
-- Correct: FINAL applies the collapseSELECT block_number, from_address, to_address, amountFROM recipe_token_transfers.fact_token_transfers FINALWHERE chain_id = 1 AND token_address = lower('0x...')ORDER BY block_number DESC LIMIT 50;-- For aggregates, sign-aware sums are cheaper than FINAL and equally correct:SELECT sum(toFloat64OrZero(amount) * sign) AS netFROM recipe_token_transfers.fact_token_transfersWHERE chain_id = 1 AND token_address = lower('0x...');
The template’s own example queries already follow this rule, so if you start from those you get it automatically.
Postgres and MySQL template variants are intended for historical backfill of settled blocks, where reorgs do
not apply, which is why the live reorg path is a ClickHouse strength (see Destinations).
Reorgs only affect the most recent blocks. Once a block is buried under enough confirmations it is
settled and will not change. So:
Historical and settled data is stable. A backfill of last month’s swaps will not be revised.
Near-tip data is provisional for a short window. A row for a block from a few seconds ago may be
corrected if that block reorganizes. This is normal and expected, not data loss.
Do not treat a brand-new tip block as final. If your product acts on the very latest blocks (live
balances, instant alerts), expect occasional corrections in that tip window and read with FINAL so a
reorged row is collapsed away rather than double-counted. For settled history, no special handling is needed.
The block array for where position and the block hash live on each row.
Destinations for why ClickHouse is the home for live, reorg-correcting workloads.
Modes for choosing realtime or hybrid, the modes where reorg handling matters.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Moralis","colors":{"primary":"#0f7fff","light":"#0f7fff","dark":"#0f7fff"},"logo":{"light":"https://mintcdn.com/moralis/GWFD1O4mIZzaStPO/logo/light.png?fit=max\u0026auto=format\u0026n=GWFD1O4mIZzaStPO\u0026q=85\u0026s=66e6da0d81943c4679e0ba921850201d","dark":"https://mintcdn.com/moralis/GWFD1O4mIZzaStPO/logo/dark.png?fit=max\u0026auto=format\u0026n=GWFD1O4mIZzaStPO\u0026q=85\u0026s=39f72ccb7cd088ee041f49d8b76acc8c"},"favicon":"https://mintcdn.com/moralis/UBURjGZyEKeu353P/favicon.png?fit=max\u0026auto=format\u0026n=UBURjGZyEKeu353P\u0026q=85\u0026s=cd5557efb5310bf231b9dede4be7ca4d","appearance":{"default":"light"},"background":{"color":{"dark":"#191B19"}},"navbar":{"links":[{"href":"https://moralis.com/enterprise/","label":"Enterprise"},{"href":"https://status.moralis.io/","label":"Status"}],"primary":{"type":"button","label":"Try Now","href":"https://admin.moralis.com/register"}},"footer":{"socials":{"youtube":"https://www.youtube.com/channel/UCgWS9Q3P5AxCWyQLT2kQhBw","x":"https://x.com/moralisdevs","linkedin":"https://www.linkedin.com/company/moralisweb3","discord":"https://discord.gg/s3UfDvXQTc","website":"https://moralis.com/"},"links":[{"header":"AI","items":[{"label":"LLMs.txt","href":"https://docs.moralis.com/llms.txt"},{"label":"Full LLMs.txt","href":"https://docs.moralis.com/llms-full.txt"}]}]},"fonts":{"family":"sw","source":"https://mintlify-assets.b-cdn.net/fonts/sw.woff2","format":"woff2"},"contextual":{"options":["chatgpt","claude","copy","view"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"moralis","hasAudioNarration":false,"actualSubdomain":"moralis","customDomains":["docs.moralis.com"],"gitSource":{"type":"github","owner":"novnski","repo":"docs-v2","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6aec67aca93f970ede8ce627","clientVersion":"0.0.4111","searchFilterCounts":[{"language":"default","tag":"RPC Nodes","count":560},{"language":"default","tag":"Data API","count":204},{"language":"default","tag":"EVM API","count":96},{"language":"default","tag":"Streams","count":96},{"language":"default","tag":"Get Started","count":67},{"language":"default","tag":"Tutorials \u0026 Guides","count":62},{"language":"default","tag":"Data Feeds","count":50},{"language":"default","tag":"Token API","count":49},{"language":"default","tag":"Wallet API","count":43},{"language":"default","tag":"Solana API","count":32}]},"assistantConfig":{"enableStarterQuestions":false},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"data-feeds/concepts/reorgs","slug":"/data-feeds/concepts/reorgs","pageMetadata":{"title":"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them","description":"Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here's what that means for your queries.","href":"/data-feeds/concepts/reorgs"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here’s what that means for your queries.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,blockquote:`blockquote`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`1`,id:`reorgs`,children:`Reorgs`}),`\n`,_jsxs(_components.p,{children:[`Blockchains do not always agree on the most recent blocks. For a short window near the tip, the network can\n`,_jsx(_components.strong,{children:`reorganize`}),`: a block that looked final gets replaced by a competing block at the same height, and anything\nonly in the replaced block is no longer part of the canonical chain. Data Feeds handle this for you, but it\nshapes one thing you must get right: `,_jsx(_components.strong,{children:`how you read the most recent rows.`})]}),`\n`,_jsx(Heading,{level:`2`,id:`how-a-reorg-surfaces`,children:`How a reorg surfaces`}),`\n`,_jsxs(_components.p,{children:[`Each block carries its `,_jsx(_components.strong,{children:`position`}),` (the block number) and its `,_jsx(_components.strong,{children:`block hash`}),`, and the feed tracks the link\nback to the parent block. When the sink sees that a block at a given position has been replaced by a\ndifferent hash, it knows the earlier block’s rows are no longer canonical.`]}),`\n`,_jsxs(_components.p,{children:[`Rather than silently deleting them, the sink writes a `,_jsx(_components.strong,{children:`correction`}),`. The original rows were written with a\n`,_jsx(_components.code,{children:`+1`}),` marker; the reorg emits matching `,_jsx(_components.code,{children:`-1`}),` rows for the same data. The pair cancels out, and the rows from\nthe new, canonical block are written in their place. Your table converges on the true chain without you\nre-running anything.`]}),`\n`,_jsx(Heading,{level:`2`,id:`what-this-means-for-your-queries`,children:`What this means for your queries`}),`\n`,_jsxs(_components.p,{children:[`The correction rows are how reorgs stay safe, but they mean a naive `,_jsx(_components.code,{children:`SELECT *`}),` over a ClickHouse fact table\ncan briefly show both the original and its `,_jsx(_components.code,{children:`-1`}),` cancel. You apply the corrections at read time:`]}),`\n`,_jsxs(_components.blockquote,{children:[`\n`,_jsx(_components.p,{children:_jsxs(_components.strong,{children:[`On ClickHouse fact tables, read with `,_jsx(_components.code,{children:`FINAL`}),` (or use sign-aware sums). That applies reorg corrections and\ngives you the canonical result.`]})}),`\n`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`10`,language:`sql`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`sql`,children:_jsxs(_components.code,{language:`sql`,numberOfLines:`10`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`-- Correct: FINAL applies the collapse`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`SELECT`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` block_number, from_address, to_address, amount`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`FROM`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#D4D4D4`},children:` recipe_token_transfers`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#D4D4D4`},children:`fact_token_transfers`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` FINAL`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`WHERE`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` chain_id `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 1`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` AND`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` token_address `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:` lower`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'0x...'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`ORDER BY`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` block_number `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`DESC`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` LIMIT`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 50`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`-- For aggregates, sign-aware sums are cheaper than FINAL and equally correct:`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`SELECT`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:` sum`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(toFloat64OrZero(amount) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`*`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` sign) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`AS`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` net`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`FROM`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#D4D4D4`},children:` recipe_token_transfers`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#D4D4D4`},children:`fact_token_transfers`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`WHERE`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` chain_id `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 1`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` AND`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` token_address `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:` lower`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'0x...'`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The template’s own example queries already follow this rule, so if you start from those you get it automatically.\nPostgres and MySQL template variants are intended for `,_jsx(_components.code,{children:`historical`}),` backfill of settled blocks, where reorgs do\nnot apply, which is why the live reorg path is a ClickHouse strength (see `,_jsx(_components.a,{href:`/data-feeds/concepts/destinations`,children:`Destinations`}),`).`]}),`\n`,_jsx(Heading,{level:`2`,id:`only-the-tip-is-provisional`,children:`Only the tip is provisional`}),`\n`,_jsxs(_components.p,{children:[`Reorgs only affect the `,_jsx(_components.strong,{children:`most recent`}),` blocks. Once a block is buried under enough confirmations it is\nsettled and will not change. So:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Historical and settled data is stable.`}),` A backfill of last month’s swaps will not be revised.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Near-tip data is provisional for a short window.`}),` A row for a block from a few seconds ago may be\ncorrected if that block reorganizes. This is normal and expected, not data loss.`]}),`\n`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Do not treat a brand-new tip block as final.`}),` If your product acts on the very latest blocks (live\nbalances, instant alerts), expect occasional corrections in that tip window and read with `,_jsx(_components.code,{children:`FINAL`}),` so a\nreorged row is collapsed away rather than double-counted. For settled history, no special handling is needed.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`related`,children:`Related`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsxs(_components.a,{href:`/data-feeds/concepts/the-block-array`,children:[`The `,_jsx(_components.code,{children:`block`}),` array`]}),` for where `,_jsx(_components.code,{children:`position`}),` and the block hash live on each row.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/data-feeds/concepts/destinations`,children:`Destinations`}),` for why ClickHouse is the home for live, reorg-correcting workloads.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/data-feeds/concepts/modes`,children:`Modes`}),` for choosing realtime or hybrid, the modes where reorg handling matters.`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them","description":"Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here's what that means for your queries.","href":"/data-feeds/concepts/reorgs"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Reorgs","slug":"reorgs","depth":1,"children":[]},{"title":"How a reorg surfaces","slug":"how-a-reorg-surfaces","depth":2,"children":[]},{"title":"What this means for your queries","slug":"what-this-means-for-your-queries","depth":2,"children":[]},{"title":"Only the tip is provisional","slug":"only-the-tip-is-provisional","depth":2,"children":[]},{"title":"Related","slug":"related","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"moralis","siteName":"Moralis","title":"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them - Moralis","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-31T15:01:06.889Z","originalFileLocation":"data-feeds/concepts/reorgs.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"light\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here\u0026#x27;s what that means for your queries.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Moralis\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them - Moralis\">\u003cmeta data-mint-head property=\"og:description\" content=\"Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here\u0026#x27;s what that means for your queries.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Moralis\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.moralis.com/data-feeds/concepts/reorgs\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://moralis.mintlify.site/_mintlify/api/og/v2?division=Concepts\u0026amp;title=Reorgs%3A+How+Chain+Reorganizations+Surface%2C+and+How+Templates+Correct+Them\u0026amp;description=Near+the+chain+tip%2C+a+block+can+be+replaced+by+another.+Data+Feeds+detect+this+and+emit+a+correction%2C+so+your+table+converges+on+the+canonical+chain.+Here%27s+wha\u0026amp;theme=3021c0945ade0560af7b28a8\u0026amp;signature=145899bdfd48479b384c8f5089b2daf789964ec652763138a8300e0e0d9460cd\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them - Moralis\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here\u0026#x27;s what that means for your queries.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://moralis.mintlify.site/_mintlify/api/og/v2?division=Concepts\u0026amp;title=Reorgs%3A+How+Chain+Reorganizations+Surface%2C+and+How+Templates+Correct+Them\u0026amp;description=Near+the+chain+tip%2C+a+block+can+be+replaced+by+another.+Data+Feeds+detect+this+and+emit+a+correction%2C+so+your+table+converges+on+the+canonical+chain.+Here%27s+wha\u0026amp;theme=3021c0945ade0560af7b28a8\u0026amp;signature=145899bdfd48479b384c8f5089b2daf789964ec652763138a8300e0e0d9460cd\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/moralis/QJZhcjaKxGIsqpqo/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Moralis\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0f7fff\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.moralis.com/data-feeds/concepts/reorgs\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/data-feeds/concepts/reorgs.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.moralis.com/#organization\",\"name\":\"Moralis\",\"url\":\"https://docs.moralis.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/moralis/GWFD1O4mIZzaStPO/logo/light.png?fit=max\u0026auto=format\u0026n=GWFD1O4mIZzaStPO\u0026q=85\u0026s=66e6da0d81943c4679e0ba921850201d\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.moralis.com#website\",\"name\":\"Moralis\",\"url\":\"https://docs.moralis.com\",\"publisher\":{\"@id\":\"https://docs.moralis.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.moralis.com/data-feeds/concepts/reorgs#webpage\",\"url\":\"https://docs.moralis.com/data-feeds/concepts/reorgs\",\"name\":\"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them\",\"description\":\"Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here's what that means for your queries.\",\"dateModified\":\"2026-08-31T15:01:06.889Z\",\"isPartOf\":{\"@id\":\"https://docs.moralis.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.moralis.com/data-feeds/concepts/reorgs#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.moralis.com/data-feeds/concepts/reorgs#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Concepts\",\"item\":\"https://docs.moralis.com/data-feeds/concepts/data-feeds-vs-the-rest-api\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them\",\"item\":\"https://docs.moralis.com/data-feeds/concepts/reorgs\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.moralis.com/data-feeds/concepts/reorgs#article\",\"headline\":\"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them\",\"name\":\"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them\",\"description\":\"Near the chain tip, a block can be replaced by another. Data Feeds detect this and emit a correction, so your table converges on the canonical chain. Here's what that means for your queries.\",\"url\":\"https://docs.moralis.com/data-feeds/concepts/reorgs\",\"mainEntityOfPage\":{\"@id\":\"https://docs.moralis.com/data-feeds/concepts/reorgs#webpage\"},\"dateModified\":\"2026-08-31T15:01:06.889Z\",\"publisher\":{\"@id\":\"https://docs.moralis.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.moralis.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Moralis\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Moralis\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/data-feeds/concepts/reorgs.md","siteName":"Moralis","nav":{"global":null,"tabs":[{"tab":"Get Started","pages":[{"title":"Get Started","href":""}]},{"tab":"Data API","pages":[{"title":"Data API","href":"/data-api/overview"}]},{"tab":"Streams","pages":[{"title":"Streams","href":"/streams/overview"}]},{"tab":"Data Feeds","pages":[{"group":"Getting Started","pages":[{"title":"Data Feeds","href":"/data-feeds/overview"},{"title":"What Are Data Feeds?","href":"/data-feeds/concepts/what-are-data-feeds"},{"title":"Data Feeds Features","sidebarTitle":"Features","href":"/data-feeds/features"},{"title":"How Data Feeds Works","sidebarTitle":"How It Works","href":"/data-feeds/how-it-works"},{"title":"Quickstart: Run Your First Sink","href":"/data-feeds/migration/quickstart"}]},{"group":"Access Methods","pages":[{"title":"Access Methods: Databases, Streams, and Direct Reads","sidebarTitle":"Overview","href":"/data-feeds/access-methods/overview"},{"title":"Database Sinks: ClickHouse, Postgres, and MySQL","sidebarTitle":"Database Sinks: ClickHouse, Postgres \u0026 MySQL","href":"/data-feeds/concepts/destinations"},{"title":"Streaming Data Feeds: Kafka, RabbitMQ, and SQS","sidebarTitle":"Streaming: Kafka, RabbitMQ \u0026 SQS","href":"/data-feeds/access-methods/streaming"},{"title":"Direct Reads: REST/HTTP and Arrow Flight","sidebarTitle":"Direct Reads: REST \u0026 Arrow Flight","href":"/data-feeds/access-methods/direct-reads"}]},{"group":"Data APIs \u0026 Migration Guides","pages":[{"title":"Data Feed Templates","sidebarTitle":"Overview - Data Feed Templates","href":"/data-feeds/templates/overview"},{"title":"Migrating from the Moralis REST API","href":"/data-feeds/migration/overview"},{"title":"Map Endpoints to Templates","href":"/data-feeds/migration/endpoints"},{"group":"Wallet API","pages":[{"title":"Wallet History","href":"/data-feeds/templates/wallet/wallet-history"},{"title":"Token Balances by Wallet","href":"/data-feeds/templates/wallet/token-balances-by-wallet"},{"title":"Native Balances","href":"/data-feeds/templates/wallet/native-balances"},{"title":"NFTs by Wallet","href":"/data-feeds/templates/wallet/nfts-by-wallet"},{"title":"Token Approvals","href":"/data-feeds/templates/wallet/token-approvals"}]},{"group":"Token API","pages":[{"title":"Token Holders","href":"/data-feeds/templates/token/token-holders"},{"title":"Historical Balances","href":"/data-feeds/templates/token/historical-balances"},{"title":"Token Balances by Token","href":"/data-feeds/templates/token/token-balances-by-token"},{"title":"Token Transfers","href":"/data-feeds/templates/token/token-transfers"},{"title":"Token Stats","href":"/data-feeds/templates/token/token-stats"},{"title":"Token Metadata","href":"/data-feeds/templates/token/token-metadata"},{"title":"Token Bonding Status (Solana Launchpads)","href":"/data-feeds/templates/token/token-bonding-status"}]},{"group":"Price API","pages":[{"title":"Token Prices","href":"/data-feeds/templates/token/token-prices"},{"title":"Pair OHLCV","href":"/data-feeds/templates/markets/pair-ohlcv"}]},{"group":"DeFi API","pages":[{"title":"Swaps by Wallet","href":"/data-feeds/templates/markets/swaps-by-wallet"},{"title":"Swaps by Token","href":"/data-feeds/templates/markets/swaps-by-token"},{"title":"Swaps by Pair","href":"/data-feeds/templates/markets/swaps-by-pair"},{"title":"Pair Reserves","href":"/data-feeds/templates/markets/pair-reserves"}]},{"group":"NFT API","pages":[{"title":"NFT Transfers","href":"/data-feeds/templates/nft/nft-transfers"},{"title":"NFT Trades","href":"/data-feeds/templates/nft/nft-trades"},{"title":"NFT Owners by Contract","href":"/data-feeds/templates/nft/nft-owners-by-contract"},{"title":"NFT Collection Metadata","href":"/data-feeds/templates/nft/nft-collection-metadata"}]},{"group":"Blockchain API","pages":[{"title":"Contract Logs","href":"/data-feeds/templates/logs/contract-logs"},{"title":"Logs by Event Signature","sidebarTitle":"Logs by Event Signature","href":"/data-feeds/templates/logs/logs-by-topic0"}]}]},{"group":"Streams","pages":[{"title":"Migrating from Moralis Streams","href":"/data-feeds/migration/streams-overview"}]},{"group":"Gotchas \u0026 Troubleshooting","pages":[{"title":"Gotchas \u0026 Troubleshooting","href":"/data-feeds/migration/troubleshooting"}]},{"group":"Concepts","pages":[{"title":"Data Feeds vs. the REST API","href":"/data-feeds/concepts/data-feeds-vs-the-rest-api"},{"title":"The `block` Array: How Transactions and Logs Are Laid Out","href":"/data-feeds/concepts/the-block-array"},{"title":"History \u0026 Backfill: How Far Back Do You Need to Index?","href":"/data-feeds/concepts/history-and-backfill"},{"title":"Modes: Historical, Realtime, and Hybrid","description":"A template runs in one of three modes. The mode decides whether the sink backfills past history, tails live blocks, or does both. Here's how to pick.","href":"/data-feeds/concepts/modes"},{"title":"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them","href":"/data-feeds/concepts/reorgs"}]},{"group":"Use Cases","pages":[{"title":"Accounting \u0026 Tax","description":"A Data Feeds template bundle for accounting, tax, and treasury tools: a wallet's full event feed plus per-asset transfer ledgers, valued in USD at block time, synced into your own database.","href":"/data-feeds/use-cases/accounting"},{"title":"Portfolio Tracking","href":"/data-feeds/use-cases/portfolio-tracking"},{"title":"Token Analytics","href":"/data-feeds/use-cases/token-analytics"},{"title":"Trading \u0026 Charting","href":"/data-feeds/use-cases/trading-charting"},{"title":"NFT Marketplace","href":"/data-feeds/use-cases/nft-marketplace"},{"title":"Compliance \u0026 AML","href":"/data-feeds/use-cases/compliance-aml"},{"title":"Onchain Event Indexing","href":"/data-feeds/use-cases/event-indexing"}]}]},{"tab":"RPC Nodes","pages":[{"title":"RPC Nodes","href":"/rpc-nodes/overview"}]},{"tab":"Auth API","pages":[{"title":"Auth API","href":"/auth-api/overview"}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Reorgs: How Chain Reorganizations Surface, and How Templates Correct Them - Moralis","buildId":"dpl_DqYu5MPb49gWBBbUGgpHQUmCHY3P","deploymentId":"dpl_DqYu5MPb49gWBBbUGgpHQUmCHY3P","dynamics":[],"chunks":[]}
