fix(activation-service): migrate to @threefold/tfchain_client

[sameh-farouk]

Unblocks the 2.13.0 release (#1100) without needing the lost npm credentials from #1099.

Why

clients/tfchain-client-js cannot be published — the npm credentials for tfgrid-api-client are lost (sole maintainer threefoldtech, last publish 2023-06-21). activation-service has therefore been pinned to 1.29.1 while the in-repo client moved on 24 commits, and the release was waiting on that publish.

activation-service only makes four client calls, and @threefold/tfchain_client (actively published, 2.9.2 on 2025-11-25) covers all of them. Measured against devnet it is also materially more robust on the two paths that matter here:

• Startup. bin/www awaits init() before server.listen(). The old client's ApiPromise.create({provider}) never rejects, so with the chain unreachable the service hung before listening, logged nothing and never became ready — confirmed still pending at 20s. connect() now rejects in ~1s and the existing .catch reports it.
• Transfer outcome. The old transfer resolved on submission, so a failed funding transfer still returned 200. apply() waits for inclusion, detects system.ExtrinsicFailed and rejects.

Balance reads are equivalent between the two clients, so reads are not a reason to migrate; those two are. The #1078/#1101 client fixes are moot here — tfchain_client never injected a static types.json and returns toPrimitive() rather than toJSON() plus a hand-rolled hex2a, so those bug classes cannot arise.

Behaviour changes

• Invalid substrateAccountID returns 400, not 500. httpError(400) was constructed and never thrown, so execution fell through to keyring.address on an undefined variable. The body for this case is now the standard error object rather than a bare string — the frontend shows a fixed string and never renders the body, so there is no UI impact.
• Account ids must decode to a 32 byte public key. 0x1234 used to be accepted and funded as the derived address 25NbUg, which nobody holds the key to. Validation is explicit now: the old check was a side effect of keyring.addFromAddress throwing, and tfchain_client.transfer does not validate the address at all.
• A failed transfer is an error response, not a 200.
• ACTIVATION_AMOUNT is read again, in whole TFT. History: it was configurable as 1e7 * parseInt(env) (whole TFT) from 2021-10-08; 73560aa then dropped the 1e7 *, which made the deployed value of 1 mean one base unit — below the existential deposit, so every activation failed; 67b41f0 hardcoded 1000000 the same day as damage control. This restores the original semantics. The chart default is set to 0.1, the amount actually funded since 2022, so deploying this changes nothing about what is paid out. Amounts below the chain's existential deposit are refused at startup.
• A failed startup exits 1. stopGraceful() exited 0 and the process.exit(1) after it was unreachable, so a failed boot reported success. Latent until now, because init() never used to reject.
• Chain errors map to status by constructor name: ValidationError 400, ConnectionError/TimeoutError 503, otherwise 500.
• Dockerfile moves to node:22 — @polkadot/api 15.x declares engines: node >= 18. Required, not cosmetic.

The commented-out validateActivation is removed: its route went away in #1103 and it called client.verify, which does not exist on the new client.

Tests

The service had no tests (npm test was standard alone) and no CI job. Adds unit tests for the funding branches, the amount config, address validation, error mapping and the fail-fast property, plus an opt-in devnet integration test. Integration targets are derived from the funder (//as-ci//1..5) and swept back with transferAll(keepAlive=false) at both ends of the job, so a run that dies mid-way is reclaimed by the next one.

standard is scoped to the server code. It was failing on the committed build/ bundle (170k errors), which meant npm test was already red on development.

Verification

Executed, not inferred:

• lint + unit: 27/27
• integration against live devnet with a funded account: 4/4, three consecutive clean runs
• sweep confirmed reaping the pool account (free 0, nonce 0, removed from storage) and returning funds; ~0.002 TFT of fees per run
• self-healing confirmed by seeding a pool account to fake a crashed run: reclaimed pool accounts from a previous run: 1, suite still green
• boot against an unreachable chain: exits 1 in ~1s (hangs indefinitely on development)
• ACTIVATION_AMOUNT below the existential deposit, and malformed: both refused at startup with a logged error and exit 1
• docker build + run on node:22: 400 and 500 paths confirmed inside the container
• SIGTERM: exits 0 with running shutdown actions

Rollout

ACTIVATION_SERVICE_CI_MNEMONIC is set and funded (devnet, ~2450 runs of headroom). Confirm the deployed values file before rolling out: if it sets activation_amount explicitly, 0.1 keeps today's amount and 1 would fund ten times more.

Refs #1099

🤖 Generated with Claude Code

https://claude.ai/code/session_011YKJm3zuWdSepriT9KL9zy