fix(subscan): a lock nobody could read is not a lock of zero

The token parser landed an hour ago reading a lock with the helper that
returns zero on failure, and asking whether the lock was zero to decide the
position was liquid. So an unreadable lock arrived as "nothing frozen" — a
claim about spendable money made out of a string that was never parsed, in the
one direction the function's own comment forbids.

Absent and unreadable are now separate, because absent is genuinely zero and
that is measured, not assumed: in one live Polkadot Asset Hub response DED
carries "lock": "0" while MYTH carries no lock field at all, which is Subscan
omitting a component the account does not use. A present lock that will not
parse leaves the liquidity unstated and is named in the sync errors, so the
withholding leaves a trace — the half of personal-feb.13 that reaches this
path.

Refs: personal-feb.10, personal-feb.13

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018E1gTMsMxVGcjkvFp4wwgr

Author: foxcool

internal/adapter/subscan/client.go

@@ -108,6 +108,13 @@ type Token struct {
 	// Lock is the frozen part of Balance where the entry reports one. It is a
 	// subset of Balance, never an addition — same model as the native coin.
 	Lock decimal.Decimal
+	// LockKnown is false when the entry carried a lock this parser could not
+	// read. Absent is not unknown: Subscan omits a component an account does
+	// not use, so a missing lock is a zero one. An UNREADABLE lock is the
+	// third state, and it must not collapse into the zero — a zero lock is
+	// read as "nothing frozen", which is a claim about spendable money made
+	// out of a string nobody could parse.
+	LockKnown bool
 	// UniqueID is Subscan's identity for this asset ON THIS CHAIN
 	// ("standard_assets/30", "standard_foreign_assets/6212dc…"). It is what an
 	// asset_external_ref is keyed by, so a second asset claiming the same
@@ -212,9 +219,9 @@ func (d tokensData) tokens(chain string) ([]Token, []string) {
 				skipped = append(skipped, fmt.Sprintf("%s: token %s (%s) reports no decimals", chain, e.Symbol, id))
 				continue
 			}
-			balance, err := parseAmount(chain, "token balance", e.Balance)
-			if err != nil {
-				skipped = append(skipped, err.Error())
+			balance, berr := parseAmount(chain, "token balance", e.Balance)
+			if berr != nil {
+				skipped = append(skipped, berr.Error())
 				continue
 			}
 			seen[id] = true
@@ -223,12 +230,23 @@ func (d tokensData) tokens(chain string) ([]Token, []string) {
 				// response at zero. It is not a position.
 				continue
 			}
+			lock, lerr := parseAmount(chain, "token lock", e.Lock)
+			lockKnown := lerr == nil
+			if !lockKnown {
+				// The position is still real and still reported; only its
+				// partition is withheld. Named here so the withholding leaves
+				// a trace, which is the half of personal-feb.13 that applies.
+				skipped = append(skipped, fmt.Sprintf(
+					"%s: token %s (%s) has an unreadable lock %q; its liquidity is left unstated",
+					chain, e.Symbol, id, e.Lock))
+			}
 			out = append(out, Token{
-				Symbol:   e.Symbol,
-				Decimals: *e.Decimals,
-				Balance:  balance,
-				Lock:     optionalAmount(e.Lock),
-				UniqueID: id,
+				Symbol:    e.Symbol,
+				Decimals:  *e.Decimals,
+				Balance:   balance,
+				Lock:      lock,
+				LockKnown: lockKnown,
+				UniqueID:  id,
 			})
 		}
 	}

internal/adapter/subscan/syncer.go

@@ -158,15 +158,20 @@ func splitLiquidity(a Account, row func(decimal.Decimal, entity.Liquidity) entit
 // it becomes an asset_external_ref under "onchain:<chain>", so an unconfirmed
 // asset lands in its own market instead of on top of the ticker it claims.
 //
-// LIQUIDITY IS STATED ONLY WHERE IT IS KNOWN. A zero lock is a position with
-// nothing frozen, which is exactly "liquid". A non-zero lock is left
-// unpartitioned: no captured response has ever carried one, so whether it is a
-// subset of balance (as the native coin's is) or something beside it has not
-// been measured — and the two answers differ in the direction that overstates
-// spendable money. An unknown liquidity is a gap; a wrong one is a false claim.
+// LIQUIDITY IS STATED ONLY WHERE IT IS KNOWN, and "known" is three states, not
+// two. A lock the entry reports as zero — or omits, which is how Subscan
+// reports a component an account does not use — is a position with nothing
+// frozen, exactly "liquid". A non-zero lock is left unpartitioned: no captured
+// response has ever carried one, so whether it is a subset of balance (as the
+// native coin's is) or something beside it has not been measured. A lock that
+// is present and UNREADABLE is left unpartitioned too, and that third state is
+// the reason this is not a bare IsZero: a zero standing in for an unparsed
+// string would state "nothing frozen" on the strength of a number nobody read,
+// and it would state it in the direction that overstates spendable money. An
+// unknown liquidity is a gap; a wrong one is a false claim.
 func tokenBalance(chain string, net network, t Token) entity.WalletBalance {
 	liquidity := entity.LiquidityUnknown
-	if t.Lock.IsZero() {
+	if t.LockKnown && t.Lock.IsZero() {
 		liquidity = entity.LiquidityLiquid
 	}
 	return entity.WalletBalance{

internal/adapter/subscan/syncer_test.go

@@ -702,3 +702,54 @@ func TestSyncWallet_ALockedTokenIsNotClaimedSpendable(t *testing.T) {
 	assert.Equal(t, "895736192688", balances[0].Amount)
 	assert.Equal(t, entity.LiquidityUnknown, balances[0].Liquidity)
 }
+
+// TestSyncWallet_AnUnreadableLockIsNotAZeroLock closes the hole the adjacent
+// personal-feb.13 pointed at, one layer over from where that ticket looks.
+//
+// A lock is read with the parser that returns zero on failure, and the liquidity
+// rule asked whether the lock was zero. So a lock nobody could parse arrived as
+// "nothing frozen" — a claim about spendable money made out of a string that was
+// never read, and made in the one direction that overstates it. The entry is
+// still a position; only its partition is withheld, and the withholding is named.
+func TestSyncWallet_AnUnreadableLockIsNotAZeroLock(t *testing.T) {
+	syncer := newTestSyncer(t, respondJSON(`{
+		"code": 0, "message": "Success",
+		"data": {
+			"native": [],
+			"assets": [
+				{"symbol": "DED", "unique_id": "standard_assets/30", "decimals": 10,
+				 "balance": "895736192688", "lock": "not-a-number"}
+			]
+		}
+	}`))
+
+	balances, err := syncer.SyncWallet(context.Background(), "5Dsvsa", []string{"assethub-polkadot"})
+	require.ErrorContains(t, err, "unreadable lock")
+	require.Len(t, balances, 1, "the position is reported; only its partition is withheld")
+	assert.Equal(t, "895736192688", balances[0].Amount)
+	assert.Equal(t, entity.LiquidityUnknown, balances[0].Liquidity)
+}
+
+// TestSyncWallet_AnAbsentLockIsAZeroLock is the other side of that line, and it
+// is measured rather than assumed: in one live Polkadot Asset Hub response DED
+// carries "lock": "0" and MYTH carries no lock field at all. Subscan omits a
+// component an account does not use, so absent is zero — and reading it as
+// unknown would drop every token into an unstated liquidity.
+func TestSyncWallet_AnAbsentLockIsAZeroLock(t *testing.T) {
+	syncer := newTestSyncer(t, respondJSON(`{
+		"code": 0, "message": "Success",
+		"data": {
+			"native": [],
+			"assets": [
+				{"symbol": "MYTH",
+				 "unique_id": "standard_foreign_assets/6212dc295daf309533f0f5873ec3f3e62d9dba33",
+				 "decimals": 18, "balance": "57000000000000000000"}
+			]
+		}
+	}`))
+
+	balances, err := syncer.SyncWallet(context.Background(), "5Dsvsa", []string{"assethub-polkadot"})
+	require.NoError(t, err)
+	require.Len(t, balances, 1)
+	assert.Equal(t, entity.LiquidityLiquid, balances[0].Liquidity)
+}