Back to Blog

Manual Transfer Links & Custodial Matching | v1.0.0-beta.12

· 7 min read
Release

Manual transfer links when Clams cannot safely infer them, automatic custodial-to-custodial matching, a CSV mapping inspector, and a Lightning channel close accounting overhaul.

Most transfers between your connections are correlated automatically. Some cannot be: a withdrawal from one wallet and a deposit in another with nothing on-chain or in the payment to prove they are the same movement. Until now those stayed as two separate postings.

You can now link them by hand:

clams journals transfers link \
  --from-kind withdrawal --from-event-id <withdrawal-event-id> \
  --to-kind deposit --to-event-id <deposit-event-id>
clams journals transfers list
clams journals transfers show --link-id <link-id>
clams journals transfers delete --link-id <link-id>

Links are profile-scoped, work over remote HTTP backends, paginate cleanly in the CLI, and use deterministic link IDs that stay stable even when event identifiers contain delimiter-like text.

The linking is deliberately strict so a manual override cannot quietly corrupt your books. BTC withdrawal -> transaction links reject or prune selected outputs that are not wallet-owned, and report racy endpoint claims as conflicts rather than internal errors. BTC transaction -> deposit links reject wallet-owned outputs, so change and receive outputs can never be claimed as a custodial deposit. Lightning pay -> deposit and withdrawal -> invoice links use canonical event IDs, preserve an explicit withdrawal-to-invoice link even when payment hashes also appear in pay records, avoid double-posting destination deposit fees, and report duplicate endpoints as conflicts.

Automatic Custodial Matching

Direct custodian-to-custodian transfers now link on their own when a withdrawal and a deposit share a strong identity, either an on-chain txid/vout or a Lightning payment hash, with an exact amount match. That removes a class of orphaned external income and expense postings you previously had to reconcile yourself.

Where the identity is only a shared txid and the claim is ambiguous, matching is fail-closed: Clams keeps the records standalone rather than guess. A standalone custodial record is also preserved when the on-chain transaction it references is quarantined.

Inspect a CSV Mapping

Custom connections store a CSV mapping that tells Clams how to read your file. You can now read it back:

clams connections csv-mapping --label <connection-label>
clams connections csv-mapping --label <connection-label> --raw

It is read-only, available as a JSON or YAML envelope, and --raw prints the stored mapping object directly. Use it to confirm what a connection is actually configured with, send a mapping to support@clams.tech for diagnosis, or share a solid mapping for us to fold into Clams.

Lightning Journal Correctness

Channel closes now post the right numbers. Protocol closes were previously misclassified as breach penalties, inflating penalty income; that is now fixed. Anchors are no longer counted as close or HTLC principal, close-to-custodian outputs bridge to the matching deposit instead of inflating on-chain fees, and anything ambiguous or unsafe is quarantined instead of guessed.

If you tracked Lightning closes on an earlier version, re-sync those connections and run clams journals process again, then regenerate any exported reports.

The full set of close, breach-close, anchor-spend, and Core Lightning sync fixes is in the changelog below.

Full changelog

Manual transfer links

  • Added clams journals transfers link|show|list|delete for profile-scoped manual transfer links between supported canonical event pairs when automatic inference cannot safely correlate the events.
  • Manual transfer links now support remote HTTP backends, full CLI listing pagination, and deterministic link IDs for event identifiers containing delimiter-like text.
  • BTC withdrawal -> transaction links reject or prune selected outputs that are not wallet-owned, and report racy endpoint claims as transfer conflicts instead of internal errors.
  • BTC transaction -> deposit links reject or prune wallet-owned outputs so change and receive outputs cannot be claimed as custodial deposits.
  • Lightning pay -> deposit and withdrawal -> invoice links use canonical event IDs, emit transfer tag hints even when source-import correlation IDs differ, preserve explicit withdrawal-to-invoice links when payment hashes also appear in pay records, avoid double-posting destination deposit fees for source-owned bridges, and report duplicate endpoints as conflicts.

Lightning close, breach-close, and anchor journals

  • Core Lightning protocol closes no longer imply breach penalties; keyed and shared anchors are not counted as close or HTLC principal.
  • Close-to-custodian outputs bridge to the matching deposit instead of becoming on-chain fee residuals, and match deposit proofs that include only btc_txid and btc_vout.
  • Untrimmed HTLC commitment outputs stay in Lightning instead of becoming close fees.
  • Anchor CPFP transactions consume linked anchor inputs from Lightning value while keeping wallet fee inputs and change in on-chain wallet accounting.
  • Close transactions quarantine unless they spend the channel funding outpoint, unknown owned close outputs no longer imply settlement, and channel opens quarantine when the funding output amount does not match channel capacity.
  • Breach-close penalty income excludes unrelated wallet fee inputs, penalty sweep outputs require channel-linked Lightning evidence, and close-to-address outputs require wallet ownership or a proven custodial deposit before becoming local assets.
  • Anchor-spend classification rejects amount-only candidates, recognizes P2A shared-anchor addresses emitted by wallet adapters, resolves unlinked shared-anchor spends through the spent close transaction id, includes lease-channel anchor value in breach-close local value, and preserves legacy LND and Core Lightning penalty sweeps when the close transaction proves the channel but UTXO origin or channel hints are missing.
  • HTLC-to-custodian bridge outputs that exceed proven HTLC capacity split the Lightning-funded portion from the ordinary wallet remainder instead of treating HTLC principal as a residual fee.
  • Added canonical zero_fee_commitments and shared_anchor enum values so explicit shared-anchor commitments are no longer collapsed into legacy keyed-anchor semantics. P2A shared-anchor evidence is accepted only for zero_fee_commitments channels, and single dual-funded opens without explicit local contribution infer it from owned inputs minus owned change instead of treating it as an on-chain fee residual.

Core Lightning sync and imports

  • Core Lightning sync uses explicit or funding-outpoint-proven close transaction ids plus hydrated close transactions and listfunds evidence to mark unambiguous close-settlement UTXOs; sub-sat close residuals post as fees while ambiguous outputs still quarantine.
  • Core Lightning manual archive imports work regardless of file order for closed-channel, transaction, and UTXO files, without overwriting conflicting existing UTXO metadata.

Custodial matching

  • Direct custodian-to-custodian transfers link when a withdrawal and deposit share a strong on-chain txid/vout or Lightning payment-hash identity and exact amount, avoiding standalone external income and expense postings.
  • Txid-only BTC custodial bridge matching fails closed when duplicate deposit or withdrawal records can claim the same transaction output.
  • Txid-only custodial bridge suppression keeps standalone custodial records when the matching on-chain transaction quarantines during journal application.

Diagnostics

  • Added clams connections csv-mapping as a read-only diagnostic command for inspecting the stored configuration.csv_mapping object on a connection, with JSON or YAML envelope output and --raw mapping-only output.

Update

clams update

Run into issues? Use clams feedback or reach out at support@clams.tech.

Clams Team

Stay in the loop

Get updates on new features and guides delivered to your inbox.