Add XCM V4 Operations Example

[developerfred]

User description

This PR adds a comprehensive XCM V4 operations example to the PAPI Simulator.

Changes

• Created XcmV4Example.ts with latest XCM V4 features
• Demonstrates teleport assets, reserve transfers, limited teleports
• Shows XCM message execution, version negotiation, and force version
• Advanced level example covering XCM cross-chain operations

Features Demonstrated

• Teleport Assets: Direct asset teleportation between chains
• Reserve Transfers: Asset transfers through reserve mechanism
• Limited Operations: Weight-limited XCM operations
• Custom XCM Messages: Executing arbitrary XCM instructions
• Version Management: XCM version negotiation and forcing

This example helps developers understand Polkadot's latest XCM V4 capabilities for cross-chain communication and asset transfers.

Closes #53

---

PR Type

Enhancement

---

Description

• Add four advanced example implementations for Polkadot ecosystem features

• OpenGov example demonstrates referendum submission, voting, and governance operations

• Coretime example showcases core purchasing, renewal, and parachain assignment

• People Chain example covers identity registration, verification, and DID operations

• XCM V4 example demonstrates teleport assets, reserve transfers, and cross-chain messaging

---

Diagram Walkthrough

flowchart LR
  A["Example Registry"] --> B["OpenGovExample"]
  A --> C["CoretimeExample"]
  A --> D["PeopleChainExample"]
  A --> E["XcmV4Example"]
  B -- "Governance operations" --> F["Referenda & Voting"]
  C -- "Coretime operations" --> G["Core Management"]
  D -- "Identity operations" --> H["DID & Verification"]
  E -- "XCM operations" --> I["Cross-chain Transfers"]

Loading

File Walkthrough

	Relevant files
Enhancement	OpenGovExample.ts OpenGov governance operations example                                        src/lib/examples/OpenGovExample.ts Create new OpenGov operations example demonstrating governance features Show referendum submission, voting with conviction, and decision deposits Include whitelisted caller operations and fellowship queries Demonstrate track-based governance and voting mechanisms +169/-0  CoretimeExample.ts Coretime chain operations example                                                src/lib/examples/CoretimeExample.ts Create new Coretime operations example for parachain resource management Demonstrate core purchasing, renewal, partitioning, and assignment Show pool operations and workload queries Include configuration and status queries for coretime management +180/-0  PeopleChainExample.ts People Chain identity management example                                  src/lib/examples/PeopleChainExample.ts Create new People Chain identity operations example Demonstrate identity registration, verification, and sub-account management Show DID operations and username registration Include registrar queries and judgement tracking +210/-0  XcmV4Example.ts XCM V4 cross-chain operations example                                        src/lib/examples/XcmV4Example.ts Create new XCM V4 operations example for cross-chain communication Demonstrate teleport assets, reserve transfers, and limited teleports Show custom XCM message execution and version negotiation Include force XCM version and multilocation handling examples +266/-0
Configuration changes	index.ts Register new advanced examples in registry                              src/lib/examples/index.ts Register four new example classes in the example registry Import OpenGovExample, CoretimeExample, PeopleChainExample, and XcmV4Example Instantiate all new examples for availability in the example system +16/-0

---

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
papi-simulator	Error		Dec 23, 2025 7:47pm

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟡	🎫 #53 🟢 Include an example demonstrating teleporting assets via XCM. Include an example demonstrating reserve-based asset transfers via XCM. Include examples of cross-chain operations between different parachains and relay chains. 🔴 Update and expand XCM examples to include the latest XCM V4 features. ⚪ Validate that the added XCM V4 example compiles and runs in the simulator environment (example registry wiring and SDK compat helper usage) and that the shown V4 structures match the target chains' metadata/descriptors.
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Swallowed exceptions: Multiple catch blocks suppress errors with generic messages (e.g., “not available”) and omit actionable context (operation/inputs), making failures hard to diagnose. Referred Code try { const coretimeConfig = await typedApi.query.Broker.Configuration.getValue(); console.log("Coretime configuration:", coretimeConfig); } catch (error) { console.log("Coretime configuration not available"); } // 2. Query core sales status console.log("\\n🏷️ Querying core sales status:"); try { const saleInfo = await typedApi.query.Broker.SaleInfo.getValue(); console.log("Current sale information:", saleInfo); } catch (error) { console.log("Sale info not available"); } // 3. Query available cores console.log("\\n🔍 Querying available cores:"); try { const cores = await typedApi.query.Broker.CoreSchedules.getEntries(); console.log("Found", cores.length, "cores with schedules"); ... (clipped 11 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Raw error output: The examples directly print caught errors via console.error(..., error) and .catch(console.error), which can expose internal details/stack traces to end users of the simulator UI. Referred Code } catch (error) { console.error("❌ Error in OpenGov operations:", error); } }; demonstrateOpenGovOperations().catch(console.error); Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: PII in logs: The example logs identity records (which may include email/web/social handles) and also hard-codes personal identifiers, increasing the risk of emitting PII in logs. Referred Code const aliceIdentity = await typedApi.query.Identity.IdentityOf.getValue(aliceAddress); console.log("Alice's identity:", aliceIdentity); const bobIdentity = await typedApi.query.Identity.IdentityOf.getValue(bobAddress); console.log("Bob's identity:", bobIdentity); } catch (error) { Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Unstructured demo logs: The new examples use ad-hoc console.log output without consistent audit fields (e.g., user ID, timestamp, outcome), so it is unclear whether required audit trails exist for real critical actions beyond this simulator/demo context. Referred Code const demonstrateXcmV4Operations = async () => { try { console.log("🌐 Starting XCM V4 operations demonstration..."); // 1. Query XCM version console.log("\\n🔍 Querying XCM version and capabilities:"); try { const version = await typedApi.query.PolkadotXcm.VersionNotifiers.getValue(); console.log("XCM version notifiers:", version); } catch (error) { console.log("Version notifiers not available"); } Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: No input validation: The example constructs and uses external/network-derived values (e.g., network.endpoint, multilocations, account IDs) without validation/sanitization, which may be acceptable for demos but needs confirmation against production/security requirements. Referred Code generateCode(network: Network): string { return `// XCM V4 Operations Example on ${network.name} ${this.getImports(network, true)} // Connect to ${network.name} const client = createClient( withPoladotSdkCompat( getWsProvider("${network.endpoint}") ) ); // Get the typed API using the descriptors const typedApi = client.getTypedApi(${network.descriptorKey}); Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Correct example registration placement Move the new example instantiations from the top-level scope into the exampleRegistry.register() call to ensure they are correctly registered. src/lib/examples/index.ts [19-28] -new XcmV4Example(), -new PeopleChainExample(), -new CoretimeExample(), -new OpenGovExample(), +exampleRegistry.register( + // ... other examples + new XcmV4Example(), + new PeopleChainExample(), + new CoretimeExample(), + new OpenGovExample(), + // ... remaining examples +); Apply / Chat Suggestion importance[1-10]: 10 __ Why: The suggestion correctly identifies that the new examples are instantiated but never registered, making them unavailable to the application. This is a critical logic error that defeats the purpose of the PR.	High
Possible issue	Correct invalid XCM location format Replace the invalid XCM V4 location interior: "Here" with the correct format interior: { Here: null } in asset definitions. src/lib/examples/XcmV4Example.ts [72-77] assets: { V4: [{ - id: { Concrete: { parents: 1, interior: "Here" } }, + id: { Concrete: { parents: 1, interior: { Here: null } } }, fun: { Fungible: 1000000000000n } // 1000 DOT/KSM }] }, Apply / Chat Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies an invalid XCM V4 MultiLocation format, which would cause runtime transaction failures. This is a critical bug in the example code.	High
	Fix incorrect XCM beneficiary format Correct the beneficiary format in the XCM DepositAsset instruction by wrapping it in a valid MultiLocation structure. src/lib/examples/XcmV4Example.ts [172-178] DepositAsset: { assets: { Wild: { AllCounted: 1 } }, beneficiary: { - AccountId32: { id: "${this.getTestAccount("bob")}" } + parents: 0, + interior: { + X1: { AccountId32: { id: "${this.getTestAccount("bob")}" } } + } } } Apply / Chat Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies an invalid structure for the beneficiary field in an XCM DepositAsset instruction, which would cause the transaction to fail at runtime.	High
	Fix compatibility helper typo Fix the typo in the function name from withPoladotSdkCompat to withPolkadotSdkCompat. src/lib/examples/XcmV4Example.ts [21-23] -withPoladotSdkCompat( +withPolkadotSdkCompat( getWsProvider("${network.endpoint}") ) Apply / Chat Suggestion importance[1-10]: 9 __ Why: This suggestion correctly identifies a typo (withPoladotSdkCompat) that would cause a ReferenceError at runtime, preventing the example code from executing.	High
More