Add xgram support

[devvasxbbtstyle]

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Description

none

---

Note

Adds Xgram swap provider and new helpers for denomination/native conversions and contract-address lookups.

• Swap Providers:
  • Xgram (centralized): New plugin in src/swap/central/xgram.ts integrating Xgram API to fetch rates, create orders, enforce min/max limits, handle unsupported pairs, set memos/tags, and build spend actions with expiration handling.
  • Registered xgram in src/index.ts plugins map.
• Utilities (src/util/swapHelpers.ts):
  • Added nativeToDenomination, denominationToNative, getCurrencyMultiplier, and getContractAddresses plus required math imports.
  • Wired helpers into Xgram flow for amount conversions and token/network resolution.

^{Written by Cursor Bugbot for commit 62d8e3f. This will update automatically on new commits. Configure here.}

[paullinator]

Commit title is poor. Should be "Add Xgram swap support"

[paullinator]

Our workflow is to never merge master into a feature branch. Always rebase your commits on top of master.

Please squash this all into one commit for review.

[paullinator]

cursor review verbose=true

[cursor]

Bugbot request id: serverGenReqId_e478b76d-79f0-4afa-828f-74563cb5b902

[paullinator]

cursor review verbose=true

Use all *.md files in the https://github.com/EdgeApp/edge-conventions repo to determine coding and PR commit style. Use any *.md files in each repo to find docs and coding conventions to adhere to when doing reviews. For this repo use this file to determine if the PR adheres to API requirements

https://github.com/EdgeApp/edge-exchange-plugins/blob/paul/apiReq/docs/API_REQUIREMENTS.md

[paullinator]

see all comments. and re-review

https://github.com/EdgeApp/edge-exchange-plugins/blob/paul/apiReq/docs/API_REQUIREMENTS.md

[devvasxbbtstyle]

@paullinator All API requirements have been taken and fixed in the latest commit.

[paullinator]

API Requirements Review

This PR does not yet comply with the API Requirements document. Please address the following before this can be merged:

Section 1: Chain and Token Identification

The current implementation relies on:

1. A separate fetchSupportedAssets() call to list-currency-options endpoint
2. Currency codes/ticker symbols (fromCcy, toCcy) for asset identification

Required changes:

• The API must support quoting using chain identifiers (e.g., 'ethereum', 'polygon') and token identifiers (contract addresses) directly
• Remove the need for a pre-fetch call to list supported assets
• For EVM chains, support chainId parameter for generic EVM chain identification

What's working well

• Error handling (Section 3) appears compliant - errors are returned in a structured array with proper priority handling for REGION_UNSUPPORTED, CURRENCY_UNSUPPORTED, BELOW_LIMIT, and ABOVE_LIMIT

Please refer to the inline comments for specific lines that need attention.

[paullinator]

Required Fixes: Data Validation with Cleaners

All network responses must be validated using cleaners, and the cleaned data must be used throughout the code.

Issues Found:

1. Incomplete cleaner definition - asTemplateQuote is missing ccyAmountFrom and expiresAt fields that are accessed from the API response

2. Raw JSON used instead of cleaned data - The code calls asTemplateQuoteReply() but then accesses fields from the raw orderResponseJson instead of the validated quoteReply result

Why This Matters:

• Unvalidated API responses can cause runtime crashes if the API changes or returns unexpected data
• Type safety is lost when bypassing cleaners
• This is a standard requirement for all Edge plugins

Please update the cleaner to include all accessed fields, and use the cleaned result for all field access.

[devvasxbbtstyle]

@paullinator
API requirements have been taken and fixed in the latest commit.

• A separate fetchSupportedAssets() call to list-currency-options endpoint
• Currency codes/ticker symbols (fromCcy, toCcy) for asset identification
• The API must support quoting using chain identifiers (e.g., 'ethereum', 'polygon') and token identifiers (contract addresses) directly
• Remove the need for a pre-fetch call to list supported assets

[paullinator]

Review Summary

Critical Issues (must fix)

1. BSC mapped to wrong chain — 'BSC' → 'binance' (BEP2) should be 'binancesmartchain' (BSC/BEP20)
2. Missing Zcash transparent address handling — No addressTypeMap for Zcash; shielded addresses will fail on a CEX

Convention Issues (should fix)

3. Plugin registration breaks alphabetical order in src/index.ts
4. Synchronizer should use shared loadMappingFile / getMappingFilePath utilities
5. Cleaners use generic "Template" prefix — rename to asXgram*
6. Import denominationToNative/nativeToDenomination from utils not swapHelpers (per convention)

Cleanup (should fix)

7. Dead code: asOptionalBlank (unused, copy-pasted from changenow)
8. Dead code: FlowType type (only 'fixed' is ever used)
9. Unused affiliateId in init options

API Requirements Compliance (docs/API_REQUIREMENTS.md)

• Sections 1-4: Compliant — chain+contractAddress identification, structured error array, bi-directional quoting, order ID + status page
• EVM chainId gap: API uses string network names, not numeric chainId. Verify with Xgram team whether chainId is supported for automatic new-EVM-chain coverage
• Sections 5-8: Not verifiable from plugin code (API/business requirements)

PR Housekeeping

• CHANGELOG checkbox not checked — should be Yes with entry added: Xgram swap provider
• PR description says "none" — should include a brief description of the integration

See inline comments for specific code locations.

[devvasxbbtstyle]

Our team will review adding support for using a numeric chainId instead of string network names for new EVM chains.

[paullinator]

Re-Review Summary

Great progress — all 10 previous findings (including the 2 critical issues) have been addressed in this commit. The plugin now follows established conventions for chain mappings, synchronizer utilities, cleaner naming, import paths, Zcash address handling, and plugin registration order.

Remaining Issues

1. depositTag: asString will throw on null (Warning) — For non-memo chains, the API may return null. Use asOptionalBlank(asString) like ChangeNow does. See inline comment.
2. Unnecessary optional chaining (Nit) — request?.quoteFor on line 145 still has ?. which is unnecessary.

API Requirements Compliance

• Sections 1-4: Compliant (chain+contractAddress identification, structured error array with correct priority order per CREATING_AN_EXCHANGE_PLUGIN.md, bi-directional quoting, order status page)
• EVM chainId support: Not verifiable from plugin code — verify with Xgram team
• Sections 5-8: Server-side requirements, not verifiable from plugin code

What's Working Well

• Error handling follows documented priority (Region → Currency → Limits)
• Clean use of asMaybe(asXgramLimitError) for limit error extraction
• Proper Zcash transparent address handling via addressTypeMap
• Chain mappings correctly map BSC → binancesmartchain
• Synchronizer uses shared loadMappingFile/getMappingFilePath

See inline comments for specific line references.

[paullinator]

Our team will review adding support for using a numeric chainId instead of string network names for new EVM chains.

We can move forward, but we won't provide any fee advantages until this is implemented.

[devvasxbbtstyle]

Our team will review adding support for using a numeric chainId instead of string network names for new EVM chains.

We can move forward, but we won't provide any fee advantages until this is implemented.

@paullinator Could you please clarify what you mean by “we won't provide any fee advantages”?
Does this mean that this plugin will have higher exchange fees until we implement support for the new EVM networks?

[paullinator]

Our team will review adding support for using a numeric chainId instead of string network names for new EVM chains.

We can move forward, but we won't provide any fee advantages until this is implemented.

@paullinator Could you please clarify what you mean by “we won't provide any fee advantages”? Does this mean that this plugin will have higher exchange fees until we implement support for the new EVM networks?

Not that it will have higher exchange fees. It's just that we will not give a priority advantage over other exchanges.