MPP.Session.Channel (mpp v0.17.0)

State and identity for an MPP payment channel.

Tempo TIP-1034 channel IDs are keccak256 of the ABI-encoded identity descriptor. XRPL PayChannel IDs are SHA-512Half of the 0x0078 space key, source AccountID, destination AccountID and create Sequence (or TicketSequence), per the PayChannel ledger-entry ID format. new/1 accepts EVM addresses or XRPL classic addresses; token may be an EVM address or "XRP".

Channel lifecycle is deliberately small: a new channel is :open, may be activated once, and an active channel may be closed once.

proof holds the highest accepted method-specific settlement material (for XRPL: cumulative drops, claim signature, and ledger PublicKey). Tempo leaves it nil.

Summary

Types

action()

id_params()

proof()

status()

t()

Functions

action_from_wire(arg1)

Parse a session credential action JSON value into its Elixir atom.

action_to_wire(atom)

Return the camelCase JSON value for a session credential action atom.

activate(channel)

Move an open channel to the active state.

apply_spend(channel, amount)

Deduct a per-request spend from the authorized voucher balance.

apply_top_up(channel, amount)

Increase the channel deposit by a positive additional amount.

apply_voucher(channel, amount, proof \\ nil)

Raise the accepted cumulative voucher amount. Equal amounts are idempotent.

available_balance(channel)

Authorized-but-unspent voucher balance (cumulative_amount - spent).

close(channel)

Move an active channel to the closed state.

compute_id(params)

Compute the TIP-1034 channel ID from its complete identity descriptor.

compute_id!(params)

Compute a channel ID, raising ArgumentError on invalid input.

compute_xrpl_id(account, destination, sequence)

Compute an XRPL PayChannel ID from funder, destination and create sequence.

new(opts)

Create validated channel state in the :open status.

new!(opts)

Create validated channel state, raising ArgumentError on invalid input.

new_proof(amount, signature, public_key)

Build the method-specific settlement proof retained for a claim.

normalize_id(channel_id)

Normalize a 32-byte channel ID to lowercase, 0x-prefixed hex.

remaining_deposit(channel)

Unvouchered remainder of the on-channel deposit (deposit - cumulative_amount).

to_xrpl_id(channel_id)

Return the 64-character uppercase hex form used on the XRPL wire.

Types

action()

@type action() :: :open | :top_up | :voucher | :close

id_params()

@type id_params() :: %{
  payer: String.t(),
  payee: String.t(),
  operator: String.t(),
  token: String.t(),
  salt: String.t(),
  authorized_signer: String.t(),
  expiring_nonce_hash: String.t(),
  escrow_contract: String.t(),
  chain_id: non_neg_integer()
}

proof()

@type proof() :: %{
  amount: non_neg_integer(),
  signature: String.t(),
  public_key: String.t()
}

status()

@type status() :: :open | :active | :closed

t()

@type t() :: %MPP.Session.Channel{
  channel_id: String.t(),
  cumulative_amount: non_neg_integer(),
  deposit: non_neg_integer(),
  payer: String.t(),
  proof: proof() | nil,
  recipient: String.t(),
  spent: non_neg_integer(),
  status: status(),
  token: String.t(),
  units: non_neg_integer()
}

Functions

action_from_wire(arg1)

@spec action_from_wire(term()) :: {:ok, action()} | {:error, :invalid_action}

Parse a session credential action JSON value into its Elixir atom.

action_to_wire(atom)

@spec action_to_wire(action()) :: String.t()

Return the camelCase JSON value for a session credential action atom.

activate(channel)

@spec activate(t()) :: {:ok, t()} | {:error, {:invalid_transition, status(), :active}}

Move an open channel to the active state.

apply_spend(channel, amount)

@spec apply_spend(t(), non_neg_integer()) :: {:ok, t()} | {:error, term()}

Deduct a per-request spend from the authorized voucher balance.

apply_top_up(channel, amount)

@spec apply_top_up(t(), pos_integer()) :: {:ok, t()} | {:error, term()}

Increase the channel deposit by a positive additional amount.

apply_voucher(channel, amount, proof \\ nil)

@spec apply_voucher(t(), non_neg_integer(), proof() | nil) ::
  {:ok, t()} | {:error, term()}

Raise the accepted cumulative voucher amount. Equal amounts are idempotent.

available_balance(channel)

@spec available_balance(t()) :: non_neg_integer()

Authorized-but-unspent voucher balance (cumulative_amount - spent).

close(channel)

@spec close(t()) :: {:ok, t()} | {:error, {:invalid_transition, status(), :closed}}

Move an active channel to the closed state.

compute_id(params)

@spec compute_id(id_params() | keyword()) :: {:ok, String.t()} | {:error, term()}

Compute the TIP-1034 channel ID from its complete identity descriptor.

compute_id!(params)

@spec compute_id!(id_params() | keyword()) :: String.t()

Compute a channel ID, raising ArgumentError on invalid input.

compute_xrpl_id(account, destination, sequence)

@spec compute_xrpl_id(String.t(), String.t(), non_neg_integer()) ::
  {:ok, String.t()} | {:error, term()}

Compute an XRPL PayChannel ID from funder, destination and create sequence.

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, term()}

Create validated channel state in the :open status.

new!(opts)

@spec new!(keyword()) :: t()

Create validated channel state, raising ArgumentError on invalid input.

new_proof(amount, signature, public_key)

@spec new_proof(non_neg_integer(), String.t(), String.t()) :: proof()

Build the method-specific settlement proof retained for a claim.

normalize_id(channel_id)

@spec normalize_id(term()) ::
  {:ok, String.t()} | {:error, {:invalid_channel_id, term()}}

Normalize a 32-byte channel ID to lowercase, 0x-prefixed hex.

remaining_deposit(channel)

@spec remaining_deposit(t()) :: non_neg_integer()

Unvouchered remainder of the on-channel deposit (deposit - cumulative_amount).

to_xrpl_id(channel_id)

@spec to_xrpl_id(term()) ::
  {:ok, String.t()} | {:error, {:invalid_channel_id, term()}}

Return the 64-character uppercase hex form used on the XRPL wire.