Decide canonical serialization format for near-gas-rs

[r-near]

Context

There's a serialization discrepancy:

• nearcore: Serializes gas (u64) as JSON numbers
• near-gas-rs: Serializes gas as JSON strings
• Both can deserialize from either format

Action

• Decide on the canonical format going forward
• Document the decision
• Plan migration path if enforcement is desired
• Determine if perpetual dual-format support is acceptable technical debt

Considerations

• Breaking change implications for existing consumers
• JSON number precision limits (u64 exceeds JS safe integer range)
• Consistency with other NEAR type serialization patterns

Reference

• Slack thread: https://nearone.slack.com/archives/C0A64SAMDNG/p1767726931086969
• PR: Add NEAR Rust DevTools 2025 status update docs#2929

Priority: Medium

[vsavchyn-dev]

Canonical Gas Serialization Format Decision

Context

There's a serialization discrepancy:

• nearcore: Serializes gas (u64) as JSON numbers
• near-gas-rs: Serializes gas as JSON strings
• Both can deserialize from either format

Decision

It makes sense to maintain the current dual-format approach. Additionally, dual-format support is a reasonable technical debt.

Rationale

1. Performance tradeoff is acceptable

   • Serialization: String format is ~1.76x slower (but we're talking nanoseconds)
   • Deserialization: Almost identical performance (~1.0x ratio)
   • Internal nearcore communication benefits from faster u64 and borsh serializations

2. Ecosystem compatibility

   • Teams might already rely on multiple serialization formats (Json via schemars or serde, BSON, Borsh)
   • Enforcing a single format would be a breaking change with limited benefit

3. JS precision safety

   • String format outside nearcore protects against JS safe integer limits
   • u64 max exceeds Number.MAX_SAFE_INTEGER (2^53 - 1)
   • Despite that, 1PetaGas (approx 2^50) should fit into the JS Number.MAX_SAFE_INTEGER (2^53 - 1) and u64::MAX (2^64 - 1)

4. Low migration burden

   • No migration path needed
   • No breaking changes for existing consumers

What This Means

Component	Serialization Format	Rationale
nearcore (internal)	u64 number (or borsh)	Performance for node communication
near-gas-rs (external)	String	JS safety, ecosystem compatibility
Consumer code	Either (deserialize both)	Maximum flexibility

---

Appendix: Supporting Data

Serialization Methods in Use

Method	Use Case
Borsh	Contracts & nearcore internal
Serde	String serialization
Schemars 0.8/1.0	String serialization
BSON	Rainbow-bridge stores gas in MongoDB

Benchmark Results (M2 Mac Air)

Serialization ({"gas": "1_000"} vs {"gas": 1_000})

Case	NearGas (str)	Raw u64	Ratio
small_1	39.59 ns	24.93 ns	1.58x
small_100	42.31 ns	27.81 ns	1.52x
kilogas	51.97 ns	25.99 ns	1.99x
megagas	48.03 ns	27.32 ns	1.75x
gigagas	48.64 ns	26.15 ns	1.86x
typical_300tgas	55.02 ns	29.06 ns	1.89x
u64_max	54.70 ns	29.52 ns	1.85x

Deserialization

Case	String	Raw u64	Ratio
small_1	20.13 ns	20.17 ns	0.99x
small_100	19.91 ns	19.83 ns	1.00x
kilogas	20.47 ns	20.56 ns	0.99x
megagas	21.94 ns	21.88 ns	1.00x
gigagas	22.81 ns	22.82 ns	0.99x
typical_300tgas	25.99 ns	25.31 ns	1.02x
u64_max	30.25 ns	31.51 ns	0.95x