proxmox/docs/04-configuration/GRU_FX_CURRENCY_ONBOARDING_CHECKLIST.md

GRU FX Currency Onboarding Checklist

Purpose: End-to-end checklist for adding one new FX-related c* currency into the GRU ecosystem so it is not only deployed, but also attached to routing, transport, explorer metadata, reserve policy, and public-chain mirroring where required.

Use with: GRU_STANDARDS_PROFILE.md, GRU_C_STAR_V2_STANDARDS_MATRIX_AND_IMPLEMENTATION_PLAN.md, GRU_TRANSPORT_ACTIVE_JSON.md, gru-standards-profile.json, gru-iso4217-currency-manifest.json, token-mapping-multichain.json, dbis-138.tokenlist.json

---

1. Currency decision

• Pick the ISO code and monetary class.
• Confirm the asset fits the standard profile in gru-standards-profile.json for canonical c*, mirrored cW*, and any x402 target behavior.
• Confirm whether the asset is:
  • fiat coin form (C)
  • fiat token form (T)
  • both
  • commodity-backed (XAU-style)
• Add or update the row in gru-iso4217-currency-manifest.json.

Required decisions:

• code
• name
• type
• minorUnits
• canonical symbol(s)
• wrapped symbol(s)
• target lifecycle state:
  • planned
  • deployed
  • transportActive
  • x402Ready

---

2. Canonical token deployment on Chain 138

• Deploy the canonical token contract on Chain 138.
• If the asset is part of the V2 path, deploy the V2 contract family, not a new V1-style special case.
• Confirm:
  • decimals
  • name
  • symbol
  • permit/auth support if the asset should be x402-capable
  • mint/burn/admin roles

Minimum outputs:

• deployed address
• deploy transaction hash
• verification status

---

3. Registry and GRU attachment

• Register the new asset in GRU / asset registry.
• Add version-aware identity if a V1/V2 coexistence path applies.
• Record:
  • canonical symbol
  • asset family
  • active version
  • forward-canonical version
  • legacy aliases if any

This is the step that makes the token a GRU asset rather than just an ERC-20.

---

4. Explorer and wallet metadata

• Add the token to dbis-138.tokenlist.json.
• Add:
  • logoURI
  • tags
  • extensions.currencyCode
  • extensions.gruVersion
  • extensions.forwardCanonical
  • extensions.x402Ready
• Add versioned Blockscout label rows in config/dbis-institutional/registry/ if the asset is staged or coexists with another version.
• Sync labels using:
  • bash scripts/verify/sync-blockscout-address-labels-from-registry.sh --apply --mode=db --from-dir config/dbis-institutional/registry

Acceptance:

• token list validates
• explorer resolves address metadata
• wallet surfaces can consume token metadata cleanly

---

5. GRU transport and cW attachment

• Add the canonical-to-wrapped mapping in token-mapping-multichain.json.
• Add or update the asset in gru-transport-active.json.
• Set:
  • currencyCode
  • mirroredSymbol
  • active version
  • x402-preferred version if applicable
  • cutover metadata

If public-chain transport is required:

• deploy or confirm cW*
• wire peer bridges
• configure maxOutstanding
• wire reserve verifier references

Acceptance:

• /api/v1/token-mapping/resolve returns the correct GRU canonical metadata
• bridge preflight reports the pair as eligible and runtime-ready when enabled

---

6. Liquidity and FX rails

• Decide whether the asset needs:
  • direct local PMM pools on Chain 138
  • public-chain local edge pools
  • both
• Add pairs only after canonical asset identity is stable.
• If the asset is for FX settlement, define:
  • quote currency
  • treasury route
  • settlement path
  • reserve source

Examples:

• cSGDC/cUSDC
• cNZDC/cUSDC
• cMXNC/cUSDT

Acceptance:

• token-aggregation resolves the asset
• approved routes are discoverable
• pool exposure follows GRU overlay policy

---

7. Accounting and ISO-20022 attachment

• Add the currency into the operational accounting and ISO mapping set.
• Ensure the same asset identity is used in:
  • settlement events
  • OMNL/Fineract postings
  • DBIS Core references
  • ISO-20022 message correlation

Acceptance:

• currency appears in the canonical settlement/event model
• accounting and chain records share the same currency identity

---

8. x402 readiness

Only apply this if the asset is intended for machine-payments or signature-based UX.

• confirm ERC-2612 or ERC-3009 support
• confirm public RPC and explorer health
• confirm token address is included in the readiness script inputs

Verification:

• bash scripts/verify/check-chain138-token-permit-support.sh ...
• bash scripts/verify/check-chain138-x402-readiness.sh --token SYMBOL=ADDRESS

---

9. Final acceptance

An FX-related c* is only fully integrated when all of the following are true:

• token deployed on Chain 138
• GRU/registry attached
• token-list metadata added
• Blockscout labeling added when needed
• currency manifest updated
• token-mapping updated
• GRU transport overlay updated
• reserve/bridge policy wired if transport is enabled
• token-aggregation resolves it
• explorer surfaces it correctly
• FX/accounting/ISO references use the same currency identity

If any of these are missing, the asset is only partially integrated.