@kaspacom/mpp-payer

Client-side helpers for wallets and API clients.

Current starter surface:

• read provider pricing
• fetch and verify signed provider manifests
• fetch provider contract artifacts and verify their hash
• open an ApiPaymentChannel from a prepared contract script
• call paid API routes with signed channel vouchers
• request channel close/finalization with a payer-signed close request
• build payer-signed settlement artifacts for the provider close/finalize path
• build and submit expired channel refunds

Channel Open

openApiPaymentChannel() builds the genesis covenant channel-open transaction from an already prepared ApiPaymentChannel contract script. The package does not shell out to silverc; wallets or build tooling should provide the script artifact that matches the channel constructor values.

The helper validates deposit/reserve/max-spend sizing, builds the indexer payload, populates the genesis covenant group, and returns the channel-open artifact with the canonical covenant id when the Kaspa runtime supplies it. providerPayoutPubkey is optional and defaults to providerPubkey; set it to a colder receiver pubkey when the provider wants the settlement signer to be a hot operational key but settled funds to land on a different key.

openApiPaymentChannelFromManifest() is the wallet bootstrap path. It consumes the signed provider manifest, applies provider policy defaults, and calls the same lower-level open helper:

import {
  fetchProviderContractArtifact,
  fetchProviderManifest,
  openApiPaymentChannelFromManifest,
  syncOpenedChannelFromManifest,
} from "@kaspacom/mpp-payer";

const manifest = await fetchProviderManifest("https://api.example.test", {
  expectedNetworkId: "testnet-10",
});
const artifact = await fetchProviderContractArtifact(manifest);
const open = await openApiPaymentChannelFromManifest({
  manifest,
  contractArtifact: artifact,
  kaspa,
  payerPrivateKey,
  payerPubkey,
  fundingEntry,
  submit: true,
});
await syncOpenedChannelFromManifest({ manifest, openArtifact: open });

The helper rejects expired or tampered manifests, artifact hash mismatches, deposits below provider minimum, and refund windows outside provider policy. If the payer needs more capacity, call buildChannelContinueTransaction() with the live channel state. The helper preserves channelId, spends currentTxid/currentVout when present, increases channel value/max spend, and renews refundAfterMs. By default it rejects top-ups inside the refund safety window; use allowUnsafeRefundWindowTopUp only for controlled recovery or negative-proof tests.

Settlement Artifacts

buildSettlementArtifact() promotes the wallet-side close-on-settle signing path into the payer package. It resolves the current channel UTXO from an injected UTXO, callback, or Kaspa wRPC endpoint, builds the unsigned settlement transaction template, signs input 0 with the payer key, and returns the ApiPaymentChannel artifact that a provider can store and later redeem.

The helper enforces:

• the authorization expiry must be before refundAfterMs
• provider/refund outputs must meet the practical minimum unless explicitly overridden for proof tests
• txid, template hash, metadata digest, and payer settlement signature are bound into the returned artifact

Refunds

buildChannelRefundTransaction() and submitChannelRefund() cover the payer escape path after refundAfterMs. They resolve the live channel UTXO, enforce the refund lock time, sign the refund branch, and return the refund artifact.

The package still expects the application to supply the Kaspa runtime, payer key, and node/RPC hooks. It does not own wallet material or node access.