Implement a secure Stellar memo parser and canonicalisation module

[Lakes41]

Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): stellar, backend, type-safety, advanced

Background

Stellar transactions support multiple memo types. GuildPass may eventually need to construct, inspect or validate transaction memos for integrations without each module implementing memo parsing differently.

This issue introduces a standalone memo parser and formatter only. It does not perform transaction submission or network access.

Problem

There is currently no Core utility that provides a strongly typed, canonical representation of supported Stellar memo values with explicit validation rules.

Loose string handling can cause ambiguity between memo types and can allow invalid values to reach later transaction-building code.

Expected Outcome

Build a deterministic Stellar memo module that parses supported memo representations into a discriminated union and formats them back into one canonical representation.

Suggested Implementation

Support Stellar memo concepts such as:

type StellarMemo =
  | { type: "none" }
  | { type: "text"; value: string }
  | { type: "id"; value: bigint }
  | { type: "hash"; value: Uint8Array }
  | { type: "return"; value: Uint8Array };

The implementation should:

• validate memo-text byte limits using UTF-8 bytes rather than character count;
• support the valid range for memo IDs;
• validate exact byte length for hash and return-hash memos;
• define canonical string or structured input forms;
• expose a formatter that round-trips supported values;
• reject malformed hexadecimal or encoded hash values;
• avoid implicit lossy conversions;
• support Unicode text correctly;
• perform no network requests;
• remain independent of transaction-building code.

Acceptance Criteria

• none, text, ID, hash and return-hash memo types have explicit typed representations.
• Valid text memos are accepted.
• Text limits are enforced using UTF-8 byte length.
• Valid memo IDs parse safely without precision loss.
• Out-of-range IDs are rejected.
• Hash-based memo values enforce exact required length.
• Malformed hash encodings are rejected.
• Parse/format round trips are covered by tests.
• Unicode boundary cases are tested.
• No network or Stellar RPC access occurs.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No transaction submission or persistence functionality is included.

Likely Affected Files/Directories

packages/stellar-memo/ or equivalent isolated package
unit tests

Independence Requirement

This issue must not depend on the Stellar asset parser, wallet validator or any transaction-building issue.

[Santia2004]

Hi team! I’d love to take on this issue. I’ve previously contributed and had multiple PRs successfully merged in this repository, so I’m already well-familiar with the codebase, architecture, and workflow. Could you please assign this to me? Thanks!

[LeoRicch]

I have 5+ years of software development experience with strong skills in TypeScript, backend development, type-safe validation, and testing.

I can implement the secure Stellar memo parser with typed representations, UTF-8 byte validation, bigint-safe IDs, strict hash validation, canonical formatting, and reliable parse/format round trips.

I’ll keep the module standalone and network-independent, with comprehensive Unicode and boundary-case tests.

I’m ready to take ownership of this issue. Please assign it to me.

[grantfox-oss]

🦊 GrantFox — @LeoRicch has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #376)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.