Serialize.tryToJSONString does not escape JSON special characters, producing invalid metadata JSON

[janezpodhostnik]

Problem

Serialize.tryToJSONString wraps string values in double quotes without escaping the content:

// cadence/contracts/utils/Serialize.cdc:30
case Type<String>():
    return String.join(["\"", value as! String, "\"" ], separator: "")

", \, and control characters (U+0000–U+001F) pass through unescaped, which violates RFC 8259 §7. The same gap applies to the Type<String?>() (line 32) and Type<Character>() (line 34) cases, and to dictionary keys in dictToJSONString (line 120), which are serialized through the same helper.

Impact

• SerializeMetadata.serializeNFTMetadataAsURI is the fallback tokenURI path for every NFT that does not resolve MetadataViews.EVMBridgedMetadata (see handleDefaultNFTToEVM in FlowEVMBridge.cdc). A single newline, quote, or backslash in a Display description or trait value makes the entire metadata document unparseable — block explorers, wallets, and marketplaces silently render no metadata at all.
• The same serializer derives contractURI during onboarding (FlowEVMBridgeUtils.cdc:414,430). The bridged ERC721 template exposes no setContractURI, so a corrupted contractURI is permanent for that collection. Every newly onboarded collection with such characters in its NFTCollectionDisplay is at risk until this is fixed.
• The unescaped code is present in the currently deployed mainnet Serialize contract.

Example — an NFT description containing a raw line feed serializes to:

data:application/json;utf8,{"name": "Example NFT #42", "description": "Line one
Line two", "image": "https://example.com/42.png"}

A strict parser rejects this: json.JSONDecodeError: Invalid control character at: line 1 column 53 (char 52).

Proposed fix

• Add an escapeJSONString(_ s: String): String helper to Serialize.cdc that escapes \, ", and control characters (\n, \r, \t, \b, \f, and \u00XX for the remaining U+0000–U+001F range).
• Apply it in the String, String?, and Character cases of tryToJSONString and to keys in dictToJSONString.

Because the bridge rewrites tokenURI on every Cadence→EVM bridge, the fix retroactively repairs per-NFT metadata for affected collections on their next bridge round-trip — no project-side changes required. Already-onboarded collections with a corrupted contractURI remain unrecoverable, which is why this should be fixed promptly.

Acceptance criteria

• Escaping helper implemented and applied to all string-producing cases and dictionary keys
• Unit tests in cadence/tests/serialize_tests.cdc covering quotes, backslashes, newlines/CR/tab, and other control characters, validating output against a strict JSON parser
• Regression test in cadence/tests/serialize_metadata_tests.cdc: an NFT with a multi-line description produces a parseable JSON data URI
• Staged contract update of Serialize on testnet and mainnet (tracked separately if preferred)

[janezpodhostnik]

Testnet Verification Receipt — Issue #213 JSON-escaping fix

Date: 2026-06-24 · Network: Flow Testnet
Fix under test: PRs #214 + #215 closing #213
Result: ✅ PASS — bridged NFT metadata now produces strictly-valid JSON.

---

What was tested

Issue #213: Serialize.tryToJSONString did not escape ", \, newlines, or control
characters. The fallback tokenURI path for NFTs that don't resolve
MetadataViews.EVMBridgedMetadata (SerializeMetadata.serializeNFTMetadataAsURI, used by
handleDefaultNFTToEVM) therefore wrote unparseable JSON into bridged ERC721 contracts.

We minted an NFT whose metadata deliberately contains every offending character, then verified
the serialized output is valid JSON — both off-chain (serializer script) and, decisively, in the
tokenURI actually stored in the live ERC721 after bridging to EVM.

Test payload (ExampleNFT — which resolves Display/Traits but not EVMBridgedMetadata):

Field	Value (raw)
name	Example "Special" NFT
description	First line⏎Second line with a⇥tab and "quotes" and a backslash \ end

Contains literal double-quotes, a newline, a tab, and a backslash — the exact failure classes from #213.

---

How — workflow

flowchart TD
    A["Create + fund testnet account<br/>0x957cdd71d5749514"] --> B["Setup COA<br/>deposit.cdc"]
    B --> C["Deploy ExampleNFT"]
    C --> D["setup_collection.cdc"]
    D --> E["mint_nft.cdc<br/>(special-char metadata)"]
    E --> F{"Phase 2:<br/>serialize_nft.cdc"}
    F -->|strict json.loads| G["✅ valid JSON<br/>(off-chain)"]
    E --> H["onboard_by_type_identifier.cdc"]
    H --> I["bridge_nft_to_evm.cdc"]
    I --> J["ERC721 minted on EVM<br/>tokenURI written via serializer"]
    J --> K{"Phase 3:<br/>token_uri.cdc"}
    K -->|strict json.loads| L["✅ valid JSON<br/>(on-chain)"]

Loading

The path the fix repairs:

flowchart LR
    NFT["Cadence NFT<br/>(no EVMBridgedMetadata)"] --> S["SerializeMetadata.<br/>serializeNFTMetadataAsURI"]
    S --> T["Serialize.tryToJSONString<br/>+ escapeJSONString  ← FIX"]
    T --> U["data:application/json;utf8,{…}"]
    U --> M["mustSafeMintERC721<br/>→ ERC721.tokenURI"]

Loading

---

Results

Phase	Check	Outcome
2	serialize_nft.cdc output → json.loads (strict)	✅ parses; round-trips to original values
3	live ERC721 tokenURI → json.loads (strict)	✅ parses; round-trips to original values

On-chain tokenURI returned (excerpt, properly escaped):

{"name": "Example \"Special\" NFT", "description": "First line\nSecond line with a\ttab and \"quotes\" and a backslash \\ end", "image": "https://flow.com/examplenft.jpg", "external_url": "https://example-nft.onflow.org", "attributes": [{"trait_type": "mintedBlock", "value": "328663780"}, {"trait_type": "foo", "value": "bar"}]}

Decoded back: name = Example "Special" NFT, description = the original multi-line string with
real newline/tab/quotes/backslash. Pre-fix, the raw newline alone made this data: URI invalid.

---

Artifacts

Item	Identifier
Cadence account	0x957cdd71d5749514
COA (EVM)	0x00000000000000000000000290377c3e3e046241
Cadence type	A.957cdd71d5749514.ExampleNFT.NFT
Cadence NFT id	229797930427517
Bridged ERC721 (EVM)	0x834085175c4c2419e9483f627d88b62d5930c767

Transactions

Step	Tx ID	Explorer
COA setup + fund	23b8afa2aa5085c6550f83a5dbcc6ea7a8f4fe8349242c3c270a2032428cc8a5	flowscan
Mint NFT (special chars)	bc3aef63894b37554c660a6ac9a9f7af0fbe4cd68a13342c29e3cee8ee65c2f5	flowscan
Onboard type	bc3065f512511136ac0ba3bd7495ec3699a83a827328cef72afd3db73f7445ff	flowscan
Bridge → EVM	c2ebe45ed6cc02ef661c11130e5f4e9f90ae50fafad72286ec6a3e08bfc0361b	flowscan

Where to look on Flowscan

• Test account (Cadence): https://testnet.flowscan.io/account/0x957cdd71d5749514
• Serialize contract under test (bridge account): https://testnet.flowscan.io/account/0xdfc20aee650fcbdf
• Bridged ERC721 (EVM): https://evm-testnet.flowscan.io/address/0x834085175c4c2419e9483f627d88b62d5930c767
• Test COA (EVM): https://evm-testnet.flowscan.io/address/0x00000000000000000000000290377c3e3e046241

---

Reproduce

# Phase 2 — off-chain serializer (free script)
flow scripts execute cadence/scripts/serialize/serialize_nft.cdc \
  0x957cdd71d5749514 cadenceExampleNFTCollection 229797930427517 --network testnet

# Phase 3 — read the on-chain tokenURI
flow scripts execute cadence/scripts/utils/token_uri.cdc \
  834085175c4c2419e9483f627d88b62d5930c767 229797930427517 --network testnet

Validate either output by stripping the data:application/json;utf8, prefix and feeding the
remainder to a strict parser (python3 -c 'import json,sys; json.loads(sys.stdin.read())').