Stablecoin Accounting & Holding Period Terms | v1.0.0-beta.13

TL;DR: First-class USDT and USDC accounting, Custom CSV transfer links for custodial movements, capital gains holding period terms, a per-connection breakdown in the capital gains report, Lightning proof diagnostics, and another round of Lightning on-chain accounting correctness fixes.

Stablecoin Accounting

USDT and USDC are now first-class assets in Clams, not unknown tokens you have to work around. Both carry a fixed 1:1 USD valuation and issuer metadata (Tether for USDT, Circle for USDC), matching how Clams already handles USD-pegged assets.

This matters most when stablecoins sit on the other side of a Bitcoin trade. A BTC sale settled in USDT now uses the pegged USDT proceeds for capital gains, instead of falling back to the hourly BTC-fiat market rate for that hour. The number reflects what the trade actually cleared at.

USD-pegged valuation also routes correctly now: assets like USDT resolve through USD before Clams probes for an unsupported direct asset pair, so a provider that quotes USD pairs no longer leaves a stablecoin unvalued.

Transfer Links for Custodial Movements

Script-produced custodial movements that never touch the Bitcoin chain can now be linked as transfers through Custom CSV. A new transfer_ref field on Deposit and Withdrawal imports correlates the two sides of a movement.

Take an example: you hold USDt on Ethereum in a Safe Wallet (formerly Gnosis Safe), and use a swap service such as Chainflip to move it into Bitcoin. That movement can now be tracked without any Ethereum indexing. As long as the data can be massaged into a format Clams can read, the withdrawal and the matching deposit link up as a transfer.

For trades, Custom CSV mappings can supply a network_asset field. When a trade involves an asset that exists on multiple networks, network_asset says which side of the trade the network applies to. If that is ambiguous, Clams refuses the import rather than risk attaching the network to the wrong asset.

Capital Gains Holding Period Terms

Capital gains rows now carry a holding period term, and exports gain a Holding Period Term column alongside the existing Holding Period Days. Each row is classified as short-term or long-term under the report's built-in more-than-one-year rule.

The classification is a fact about each lot's holding period, computed and labeled so it is visible in the structured rows and the CSV. What rate applies to a short-term or long-term lot is a decision for your accountant; Clams gives them the column they need to make it.

Capital Gains by Connection

The capital gains PDF summary now breaks the totals down per connection. Each node, wallet, and exchange gets its own row with disposals, lot selections, quantity, proceeds, cost basis, realized gain/loss, and ROI, so you can see at a glance which sources drove the result instead of reading one aggregate number.

The capital gains PDF summary, generated through the Clams agent skills, with a per-connection breakdown.

The PDF is a summary document. For the complete line-item record, export the report as CSV with clams reports capital-gains --format csv. The Clams agent skills have been updated to produce this summary export, so an agent running your reports can hand you the PDF alongside the underlying data. Install or update the skills with:

clams skills install

Pin a Specific Release

clams update installs the latest public release. You can now install a specific tagged release instead, including customer release candidate (RC) builds, and return to the public channel when you are done:

clams update <version>
clams update stable

Lightning Proof Diagnostics

When a Lightning on-chain event is quarantined, you can now see exactly which proof was missing. Two commands surface it: clams journals quarantined --proof-diagnostics, and clams journals quarantine show in JSON or YAML.

Both now report a structured proof status for each piece of evidence Clams looks for: the channel close txid, the UTXO origin and link, spent-input ownership, and the HTLC witness and script. Instead of a generic "quarantined" flag, you see which check failed.

clams journals quarantined --proof-diagnostics
clams journals quarantine show --format json

CSV output keeps quarantine rows for reason codes that have no Lightning proof diagnostics, rather than dropping them, and the global -v/--verbose flag no longer changes the JSON, YAML, or CSV projections of quarantined output.

Lightning On-Chain Correctness

This release continues the channel-close and HTLC accounting work from v1.0.0-beta.12. HTLC continuation outputs now require explicit canonical or script evidence before they are claimed for a channel, anchor and zero-fee HTLC sweeps stay in Lightning when the spent close output and witness script prove the channel, and anything ambiguous, duplicated, or fee-bearing stays quarantined instead of being assigned by guesswork.

Core Lightning and LND on-chain hydration now use only the configured profile on-chain source for Lightning candidate transactions, leaving evidence absent rather than falling back to an implicit backend.

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 rest of the fixes are below.

Other changes

Install and update

• Fixed no-target clams update for RC-channel installs and explicit RC metadata-channel overrides to fail closed when RC metadata is unavailable, instead of falling back to the public stable installer.

Multi-asset accounting

• Journal snapshots and CLI journal/portfolio text output now preserve imported asset identity for non-BTC assets.
• Fixed Custom CSV asset expansion edge cases: blank trade networks ignore network_asset, trade network_asset columns participate in header preflight, native parse_decimal values preserve leading signs in numeric-only comparisons, duplicate rows use the last network sidecar state in an import, asset-bearing canonical amount/fee fields require decimal_sats storage precision and reject negative evaluated values before upsert, and direct USD-pegged assets do not require rate provider pair metadata.
• Fixed balance-sheet tree text output so non-BTC asset amounts use native asset display precision instead of the fixed BTC sats precision.
• Fixed BTC amount rendering from expanded journal snapshots so fractional-sat balances and entries continue to display millisatoshi precision instead of rounding to whole sats.

Core Lightning connections

• Fixed Core Lightning Commando preflight errors in builds without Commando transport support to report the unsupported operation instead of telling users to change the configured address.
• Fixed Core Lightning Commando getinfo timeout and transport preflight failures to point at config.address with node-health guidance instead of telling users to verify rune authorization; common Commando rune-denial wording such as "Not permitted", "access denied", and "forbidden" now points at config.rune.
• Changed configured Core Lightning Commando connection create, update, and validation flows to verify live reachability and getinfo rune authorization before persistence; unconfigured CoreLN manual-import connections remain supported.

Lightning on-chain journaling

• Fixed untyped Core Lightning selected-source HTLC continuation transactions to use the same close-output and witness proof before wallet residual accounting, post proven HTLC input/output residuals as Lightning-funded on-chain fees, credit matching custodial deposit bridges from proved HTLC capacity, group batched same-channel HTLC inputs before checking continuation output capacity, leave close-sweep-funded remainder outputs in wallet accounting, and avoid spurious journal quarantines when no HTLC transaction type hint is present.
• Fixed external HTLC continuation planning to require explicit continuation evidence, a P2WSH script template, or cached delayed-to-local spender witness on retained outputs, ignoring amount-only non-HTLC remainder outputs instead of treating them as missing-capacity or ambiguous-output quarantines.
• Fixed external HTLC continuation journals to quarantine same-index outputs that already carry canonical or graph evidence for a different channel.
• Fixed external HTLC continuation planning to quarantine generic continuation outputs that match HTLC inputs from multiple proved channels instead of assigning them by channel iteration order.
• Fixed selected-source canonical transaction script evidence to emit raw scriptSig/scriptPubKey bytes instead of consensus-encoded scripts with CompactSize prefixes.
• Fixed Core Lightning pending ONCHAIN channel sync to leave close proof absent instead of aborting when the selected on-chain source cannot complete an outspend lookup.
• Fixed LND close-output UTXO linkage so cooperative close outputs backed by the closed-channel close txid and local receipt amount carry canonical channel proof, and improved HTLC continuation planning to use later delayed-to-local spend witness evidence before quarantining otherwise ambiguous generic P2WSH outputs.

Canonical on-chain evidence

• Added canonical on-chain script evidence fields for transaction inputs, outputs, and UTXOs, with LMDB bincode compatibility for legacy Transaction and UTXO rows.
• Added canonical close metadata for transaction raw version/locktime/sequence proof and split channel settlement receipt/local close fee fields; clams canonical channels JSON/YAML now shows the split close amounts.

Update

clams update

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

Clams Team