Package com.tnsai.payment.x402

Class EnvKeystoreWallet

java.lang.Object

com.tnsai.payment.x402.EnvKeystoreWallet

public final class EnvKeystoreWallet
extends Object

Builds a Web3jWallet from an EVM private key resolved from environment variables.

Operator setup is one env var per prefix:

 <PREFIX>_PRIVATE_KEY   — 32-byte hex (with or without 0x prefix)
 

So EnvKeystoreWallet.fromEnv("X402_WALLET", Network.BASE_SEPOLIA) reads X402_WALLET_PRIVATE_KEY and produces a signing wallet bound to Base Sepolia.

Why env-var-only in P4

Encrypted JSON keystore decryption (the Geth / MetaMask-export format) needs scrypt + AES primitives. web3j-crypto ships those low-level blocks but its high-level WalletUtils.loadCredentials entry point lives in the heavier web3j-core artifact, which would drag in JSON-RPC, contract-binding, and WebSocket dependencies the payments module doesn't otherwise need. We pin tnsai-payments to the crypto slice only — keystore-file decryption is a follow-up that either inlines scrypt + AES or pulls in the larger artifact when there's a demonstrated need.

Production guidance

• A private-key env var is a real attack surface — it's visible to anyone with process-listing access and lands in the env table of any child process. Treat the env var like a password: inject from a secret manager at process-start, never check it into source.
• For deployments that need zero in-process key material, plug a DelegatedWallet (separate issue) that proxies signing to a remote service (KMS / HSM / Ledger / signing daemon) instead. The Wallet SPI is the same; only the construction path changes.
• The wallet keeps the decrypted key in JVM heap memory while the process is running.

Since:

0.10.5 (TNS-449 P4)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	EnvKeystoreWallet.MissingEnvVarException	Thrown when a required env var is missing or blank.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	PRIVATE_KEY_SUFFIX	Env var suffix appended to the prefix for the raw private key.

Method Summary

Modifier and Type	Method	Description
static Web3jWallet	fromEnv(String envVarPrefix, Network network)	Resolve and load a wallet from env vars derived from envVarPrefix.
static Web3jWallet	fromEnv(String envVarPrefix, Network network, Function<String,String> envLookup)	Like fromEnv(String, Network) but with a caller-supplied env lookup function — tests use this to drive the resolver deterministically without touching real environment variables.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

PRIVATE_KEY_SUFFIX

public static final String PRIVATE_KEY_SUFFIX

Env var suffix appended to the prefix for the raw private key.

See Also:

• Constant Field Values

Method Details

fromEnv

public static Web3jWallet fromEnv(String envVarPrefix,
 Network network)

Resolve and load a wallet from env vars derived from envVarPrefix. With prefix "X402_WALLET" this reads X402_WALLET_PRIVATE_KEY.

Throws:

EnvKeystoreWallet.MissingEnvVarException - if the env var is absent or blank

IllegalArgumentException - if the env var value is not a valid 32-byte hex

fromEnv

public static Web3jWallet fromEnv(String envVarPrefix,
 Network network,
 Function<String,String> envLookup)

Like fromEnv(String, Network) but with a caller-supplied env lookup function — tests use this to drive the resolver deterministically without touching real environment variables.