Create XCM Observability Guide (#873) #980

dawnkelly09 · 2025-09-15T19:21:40Z

Applies formatting suggestions to content contributed for XCM Observability (concept page and tutorial). @nhussein11 please take another look to make the suggested changes in language don't break the technical accuracy of the information. Would you also please see if you can add a little more in the places where there are long scripts? Like more comments explaining what's happening or a summary at the end of the snippet like "This code does the following...." or something. This feels complete but kind of abrupt and not super smooth if that makes sense.

Pulling in external contributions for formatting review. * Copy XCM Observability * Apply the new format * Update Induction * Update Prerequisites * Update Where to Go Next * Add Understanding the Basics * Add scripts * Add result * Update Failure Event Handling * Add forwardIdFor * Update Workaround for Older Runtimes * Update Where to Go Next * Update Prerequisites * Remove Where to Go Next * Reorder the content * Change to Hydration * Update script * Update script * Check if PolkadotXcm.Sent exists * Add Define a Scenario: Multi-Hop XCM with Manual `SetTopic` * Add multi-hop-with-set-topic.ts * Add results * Update the order * Check grammar * Update Prerequisites * Update scripts * Add Set Up Your Project * Update script name * Update header * Update limited-reserve-transfer-assets.ts * Update scripts * Update deposit-reserve-asset-with-set-topic.ts * Update initiate-reserve-withdraw-with-set-topic.ts * Add forwarded-xcm-remote-topic.html * Update XCM Transfer with Manual `SetTopic` * Fix typos * Add Multi-hop XCM Transfer with Manual `SetTopic` * Update fully * Update partially * Update flowchart * Update flowchart * Update flowchart * Break into two lines * Break into two lines * Use TD * Update flowchart * Update limited_reserve_transfer_assets * Update DepositReserveAsset * Update InitiateReserveWithdraw * Update scripts * Update MAX_RETRIES * Fix fmt * Fix fmt * Update Prerequisites * Update to Polkadot Hub * Update to Polkadot Hub * Add Observability Features * Update wordings * Update Observability Features * Update Automatic vs Manual `SetTopic` * Update Summary * Fix output files * Change the exchange rate * Fix conflicts * Fix conflicts * Revert changes * Revert changes * Revert changes * Revert changes * Revert changes * Revert changes * Revert changes * Change Setting Up Your Workspace * Add links to Rust docs * Update limited-reserve-transfer-assets.ts * Update deposit-reserve-asset-with-set-topic.ts * Update initiate-reserve-withdraw-with-set-topic.ts * Fix imports * Fix typos * Add Troubleshooting on Running Scripts * Revert unrelated changes * Revert unrelated changes * Use 1.6.0 or later * Fix merge conflicts * Update tutorials/interoperability/xcm-observability.md Co-authored-by: Nicolás Hussein <80422357+nhussein11@users.noreply.github.com> * Add XCM Observability in Action * Update XCM Observability in Action * Update XCM Observability * Fix execution-with-error.html * Move Workaround for Older Runtimes * Use blake2b instead of blake2AsU8a * Use blake2b instead of blake2AsU8a * Add WithUniqueTopic * Add on system chains * Add on system chains --------- Co-authored-by: Nicolás Hussein <80422357+nhussein11@users.noreply.github.com>

Copilot

Pull Request Overview

This PR creates comprehensive documentation for XCM observability capabilities in Polkadot, providing both conceptual understanding and hands-on guidance. The addition introduces tracing, correlation, and debugging features for cross-chain messages through SetTopic instructions and message ID tracking.

Adds conceptual documentation explaining XCM observability features in modern runtimes
Creates a practical tutorial with three scenarios demonstrating message tracing techniques
Provides troubleshooting guidance and code examples for implementing observability workflows

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tutorials/interoperability/xcm-observability-in-action.md	Complete hands-on tutorial with three XCM scenarios and troubleshooting
develop/interoperability/xcm-observability.md	Conceptual overview of XCM observability features and best practices
tutorials/interoperability/.nav.yml	Navigation update to include new tutorial
develop/interoperability/.nav.yml	Navigation update to include new concept page
llms.txt & llms-full.txt	Documentation index updates for AI systems
.snippets/code/*	TypeScript code examples and HTML output samples

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

tutorials/interoperability/xcm-observability-in-action.md

Copilot · 2025-09-15T19:22:44Z

tutorials/interoperability/xcm-observability-in-action.md

+> ⚠️ PolkadotXcm.Sent is only available in runtimes built from stable2503-5 or later.
+
+This error usually means that your runtime needs to be updated. Ensure that `wasm-override` is updated to runtime version 1.6.0+, or to any runtime built from `stable2503-5` or later.
+


The error handling section references updating the wasm-override but doesn't explain how to do this. Consider adding a brief instruction or linking to more detailed update procedures.

Suggested change

To update your `wasm-override`, download the latest runtime `.wasm` file for your chain and specify its path using the `--wasm-override` flag in your Chopsticks command or configuration. For a step-by-step guide, see [How to Override the Runtime Wasm](https://github.com/paritytech/chopsticks#runtime-wasm-override){target=_blank}.

@nhussein11 thoughts on this suggestion? I don't know if it's needed??

It won't work. It requires to change the config file: wasm-override: wasms/asset-hub-polkadot_v1.6.0.wasm.

develop/interoperability/xcm-observability.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

eshaben

I think we can make the material easier to digest.

The tutorial doesn't feel like a tutorial right now. It mostly has example code without context, which makes it feel more like a reference than a learning experience.

The guide needs to be more clear in the way we're laying out the information. In it's current format, it's not the easiest to read, so I left some comments on how we can improve this.

eshaben · 2025-09-15T22:03:41Z

.snippets/code/develop/interoperability/xcm-observability/forward-id-for.ts

This file needs to be formatted, please

eshaben · 2025-09-15T22:18:32Z

...nteroperability/xcm-observability-in-action/deposit-reserve-asset-with-set-topic-result.html

@@ -0,0 +1,10 @@
+<div class="termynal" data-termynal>
+  <span data-ty="input">npx tsx limited-reserve-transfer-assets.ts</span>


This is missing the file path span

eshaben · 2025-09-15T22:18:41Z

...torials/interoperability/xcm-observability-in-action/deposit-reserve-asset-with-set-topic.ts

Please format

eshaben · 2025-09-15T22:18:51Z

...torials/interoperability/xcm-observability-in-action/deposit-reserve-asset-with-set-topic.ts

+} from "@polkadot-labs/hdkd-helpers";
+
+const XCM_VERSION = 5;
+const MAX_RETRIES = 8; // Number of attempts to wait for block finalisation


Suggested change

const MAX_RETRIES = 8; // Number of attempts to wait for block finalisation

const MAX_RETRIES = 8; // Number of attempts to wait for block finalization

eshaben · 2025-09-15T22:20:25Z

tutorials/interoperability/xcm-observability-in-action.md

+
+### Forwarded XCM Example
+
+The following example illustrates the runtime adding a `SetTopic` to the forwarded XCM automatically:


@nhussein11 @brunopgalvao Is this section helpful? Like what produces the output in the terminal?

This goes for all the Forwarded XCM Example sections. I'm confused by them

eshaben · 2025-09-15T22:54:45Z

develop/interoperability/xcm-observability.md

+
+When an XCM fails, the transaction rolls back and no explicit failure event is emitted on-chain. The following are some ways to check for XCM failure:
+
+1. **View nested dispatch errors via indexers**: Most indexers display nested errors indicating why an XCM failed, e.g.:


Suggested change

1. **View nested dispatch errors via indexers**: Most indexers display nested errors indicating why an XCM failed, e.g.:

1. **View nested dispatch errors via indexers**: Most indexers display nested errors indicating why an XCM failed. For example:

eshaben · 2025-09-15T22:55:38Z

develop/interoperability/xcm-observability.md

+
+   Common errors include missing assets, exceeded execution limits, or invalid asset locations. This nested error reporting, introduced in runtimes from `stable2506` onward, usually suffices to diagnose typical issues.
+
+2. **Replay using Chopsticks for full logs**: For detailed troubleshooting, try the following steps:


Should this even be a set of steps? These are two totally different things that don't seem sequential. Probably should be an unordered list instead.

eshaben · 2025-09-15T22:56:06Z

develop/interoperability/xcm-observability.md

+    - See exactly which instruction failed and why.
+    - View complete error chains like `FailedToTransactAsset` or `AssetNotFound`.
+
+    This approach is invaluable for multi-hop flows and complex custom XCMs.


This seems unnecessary unless we're going to explain why.

eshaben · 2025-09-15T22:56:53Z

develop/interoperability/xcm-observability.md

+1. Start with indexer or API error output.
+2. If unclear, use Chopsticks to replay the exact transaction.


Repetitive of steps above. Maybe we should consider the order of these sections. Makes more sense to briefly introduce then do a deeper dive than to do a deep dive and then mention it again

eshaben · 2025-09-15T23:00:00Z

develop/interoperability/xcm-observability.md

+!!! note
+    When using [`WithUniqueTopic`](https://paritytech.github.io/polkadot-sdk/master/staging_xcm_builder/struct.WithUniqueTopic.html){target=\_blank}, the topic ID is guaranteed to be unique if `WithUniqueTopic` automatically appends the `SetTopic` instruction. However, if the message already includes a `SetTopic` instruction, the uniqueness of the ID depends on the message creator and is not guaranteed.
+
+## Observability Features


I'm not really a fan of this section. Like we introduce PolkadotXcm.Sent and MessageQueue.Porcessed in the list then we have a table. I feel like why are we providing some info in a list and some of it in a table? Actually makes it harder to read because you have to piece it together.

* Update wording for custom SetTopic * Update wording for custom SetTopic * Update wording for custom SetTopic

nhussein11 · 2025-09-30T11:40:30Z

@raymondkfcheung I truly appreciate this contribution! We're currently undertaking a major migration to a new documentation architecture. For this reason, I'm going to hold off on merging this PR for now. Once the XCM content is settled in the new structure, we will use your work to ensure it aligns with our updated, user-journey-focused guide standards. Thank you for your patience and excellent contribution!

raymondkfcheung · 2025-09-30T16:31:58Z

tutorials/interoperability/xcm-observability-in-action.md

+    ```yaml title="configs/polkadot-hub-override.yaml"
+    ...
+    db: ./db.sqlite
+    wasm-override: wasms/asset-hub-polkadot_v1.6.0.wasm


#980 (comment)

@nhussein11 @dawnkelly09

raymondkfcheung and others added 3 commits September 15, 2025 12:59

formatting updates, correct nav filepath to fix 404

ffede2e

update navs, formatting updates, etc.

58fcc29

dawnkelly09 marked this pull request as ready for review September 15, 2025 19:21

dawnkelly09 requested a review from a team as a code owner September 15, 2025 19:21

Copilot AI review requested due to automatic review settings September 15, 2025 19:21

Copilot AI reviewed Sep 15, 2025

View reviewed changes

dawnkelly09 added B0 - Needs Review Pull request is ready for review A0 - New Content Pull request contains new content pages labels Sep 15, 2025

dawnkelly09 and others added 2 commits September 15, 2025 15:26

fresh llms

57bf86b

Apply suggestions from code review

5551dd3

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

eshaben reviewed Sep 15, 2025

View reviewed changes

kapetan3sid requested a review from nhussein11 September 29, 2025 14:01

Update wording on manual SetTopic (#1002)

ef9329b

* Update wording for custom SetTopic * Update wording for custom SetTopic * Update wording for custom SetTopic

nhussein11 added C1 - Medium Medium priority task B2 - Blocked Pull request is blocked and should not be merged and removed B0 - Needs Review Pull request is ready for review labels Sep 30, 2025

raymondkfcheung mentioned this pull request Sep 30, 2025

Create XCM Observability Guide paritytech/polkadot-sdk#9412

Open

raymondkfcheung reviewed Sep 30, 2025

View reviewed changes

		> ⚠️ PolkadotXcm.Sent is only available in runtimes built from stable2503-5 or later.

		This error usually means that your runtime needs to be updated. Ensure that `wasm-override` is updated to runtime version 1.6.0+, or to any runtime built from `stable2503-5` or later.



	To update your `wasm-override`, download the latest runtime `.wasm` file for your chain and specify its path using the `--wasm-override` flag in your Chopsticks command or configuration. For a step-by-step guide, see [How to Override the Runtime Wasm](https://github.com/paritytech/chopsticks#runtime-wasm-override){target=_blank}.

		@@ -0,0 +1,10 @@
		<div class="termynal" data-termynal>
		<span data-ty="input">npx tsx limited-reserve-transfer-assets.ts</span>

	const MAX_RETRIES = 8; // Number of attempts to wait for block finalisation
	const MAX_RETRIES = 8; // Number of attempts to wait for block finalization


		### Forwarded XCM Example

		The following example illustrates the runtime adding a `SetTopic` to the forwarded XCM automatically:


		When an XCM fails, the transaction rolls back and no explicit failure event is emitted on-chain. The following are some ways to check for XCM failure:

		1. View nested dispatch errors via indexers: Most indexers display nested errors indicating why an XCM failed, e.g.:


		Common errors include missing assets, exceeded execution limits, or invalid asset locations. This nested error reporting, introduced in runtimes from `stable2506` onward, usually suffices to diagnose typical issues.

		2. Replay using Chopsticks for full logs: For detailed troubleshooting, try the following steps:

		1. Start with indexer or API error output.
		2. If unclear, use Chopsticks to replay the exact transaction.

Create XCM Observability Guide (#873) #980

Are you sure you want to change the base?

Create XCM Observability Guide (#873) #980

Uh oh!

Conversation

dawnkelly09 commented Sep 15, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

eshaben left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhussein11 commented Sep 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants