timo-schmid / fedimint-http-client

fedimint-http: A Fedimint HTTP Client (and Cashu Proxy)

fedimint-http exposes a REST API to interact with the Fedimint client.

Fedimint Client Endpoints

The Fedimint client supports the following endpoints:

Admin related commands:

• /fedimint/v2/admin/info: Display wallet info (holdings, tiers).
• /fedimint/v2/admin/backup: Upload the (encrypted) snapshot of mint notes to federation.
• /fedimint/v2/admin/discover-version: Discover the common api version to use to communicate with the federation.
• /fedimint/v2/admin/restore: Restore the previously created backup of mint notes (with backup command).
• /fedimint/v2/admin/list-operations: List operations.
• /fedimint/v2/admin/module: Call a module subcommand.
• /fedimint/v2/admin/config: Returns the client config.

Mint related commands:

• /fedimint/v2/mint/reissue: Reissue notes received from a third party to avoid double spends.
• /fedimint/v2/mint/spend: Prepare notes to send to a third party as a payment.
• /fedimint/v2/mint/validate: Verifies the signatures of e-cash notes, but not if they have been spent already.
• /fedimint/v2/mint/split: Splits a string containing multiple e-cash notes (e.g. from the spend command) into ones that contain exactly one.
• /fedimint/v2/mint/combine: Combines two or more serialized e-cash notes strings.

Lightning network related commands:

• /fedimint/v2/ln/invoice: Create a lightning invoice to receive payment via gateway.
• /fedimint/v2/ln/await-invoice: Wait for incoming invoice to be paid.
• /fedimint/v2/ln/pay: Pay a lightning invoice or lnurl via a gateway.
• /fedimint/v2/ln/await-pay: Wait for a lightning payment to complete.
• /fedimint/v2/ln/list-gateways: List registered gateways.
• /fedimint/v2/ln/switch-gateway: Switch active gateway.

Onchain related commands:

• /fedimint/v2/onchain/deposit-address: Generate a new deposit address, funds sent to it can later be claimed.
• /fedimint/v2/onchain/await-deposit: Wait for deposit on previously generated address.
• /fedimint/v2/onchain/withdraw: Withdraw funds from the federation.

Soon(TM): maps Cashu NUT endpoints to fedimint client.

Supported Cashu NUTs: (Notation, Utilization, and Terminology)

• NUT-00: Notation, Utilization, and Terminology
  • Fedimint ecash does not currently encode the federation endpoint as part of the ecash, just the federation id. Fedimint encourages longer running relationships based off its trust model so doesnt currently support on the fly issuance / reissuance. Can coerce a mapping but doesnt exactly match. returns a federation id instead
• NUT-01: Mint public key exchange
  • /v1/keys: supportable
  • /v1/keys/{keyset-id}: supportable (fedimint only maintains 1 keyset)
  • Fedimint does not currently rotate keysets. Responds with single keyset mapping in Cashu format.
• NUT-02: Keysets and keyset ID
  • /v1/keysets: supportable
• NUT-03: Swap tokens
  • /v1/swap: supportable
  • Equivalent to Fedimint Reissue. Proofs are slightly different but functionally equivalent.
• NUT-04: Mint tokens
  • /v1/mint/quote/{method}: supportable
    • method=bolt11: supportable via lngateway
    • method=onchain: supportable via pegin
  • /v1/mint/quote/{method}/{quote_id}: supportable
  • /v1/mint/{method}: supportable
    • Fedimint client handles these a little differently but can probably coerce the flow, dont get why it requires the 2nd round after status is completed, should just return the notes there.
• NUT-05: Melting tokens
  • /v1/melt/quote/{method}: supportable
    • method=bolt11: supportable via lngateway
    • method=onchain: supportable via pegout
  • /v1/melt/quote/{method}/{quote_id}: supportable
• NUT-06: Mint information
  • /v1/info: supportable