Skip to content

feat: introduce Amount type to standardize msat/sat units across the protocol #151

@portal-wheatley

Description

@portal-wheatley

Problem

Across the codebase, amounts are passed as raw integers (u64, i64, long) with no enforced unit. This leads to ambiguity and potential bugs when different parts of the stack use different conventions — e.g. pay_invoice returning fees in sats vs the protocol defaulting to msat.

Related: the pay_invoice trait was recently updated to return fees in sats (#149), which surfaced this inconsistency.

Proposal

Introduce an Amount type in portal (core crate) that makes the unit explicit:

pub enum Amount {
    Millisats(u64),
    Sats(u64),
}

impl Amount {
    pub fn to_msat(&self) -> u64 { ... }
    pub fn to_sat(&self) -> u64 { ... }
}

All protocol-level structs (payment requests, wallet trait, responses) should use Amount instead of bare integers, eliminating implicit unit assumptions.

Benefits

  • No more silent msat/sat mismatches
  • Easier to audit and refactor payment flows
  • Cleaner FFI/bindings (the type carries its unit)

Scope

  • portal core crate: payment request/response types
  • portal-wallet trait (pay_invoice, get_wallet_info, etc.)
  • portal-rest wire format (serialization stays as msat for protocol compatibility)
  • Bindings (UniFFI): expose Amount as a proper enum

Metadata

Metadata

Assignees

No one assigned

    Labels

    portalportal main crate

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions