Package com.tnsai.payment.x402

Interface Wallet

All Known Implementing Classes:
InMemoryWallet, Web3jWallet
public interface Wallet
Signing surface the x402 payment broker needs.

Mirrors the FeedbackCollector / PromptInjectionDetector SPI shape elsewhere in the framework: a public interface plus a nested Wallet.Factory interface that can be discovered via ServiceLoader. This keeps the broker decoupled from any single key-management strategy — agents can plug in env-keystore wallets, KMS wallets, hardware wallets, or a remote-signing daemon without the broker code changing.

What an implementation must do

  • Expose the wallet's address() (lowercase 0x... hex string, 42 chars for EVM addresses).
  • Report the network() the wallet is bound to. A wallet is single-network on purpose — keeps the chain-id check at sign time honest and stops cross-chain replay accidents.
  • Sign a prepared EIP712TypedData digest pair and return 65 bytes (r || s || v) for EVM family or 64 bytes (R || s) for SVM family.

Thread safety

Implementations must be safe to call from multiple threads — agents often run concurrent settlements. Stateless wrappers around a fixed key are fine; backends that talk to remote signers should serialise around their own client.

Discovery

 // resources/META-INF/services/com.tnsai.payment.x402.Wallet$Factory
 com.example.kms.AwsKmsWalletFactory
Then call Wallet.Factory.discover() to retrieve the first registered factory on the classpath (or Optional.empty() if none ship).
Since:
0.10.5 (TNS-449 P2)

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Wallet.Factory
    Factory that turns a WalletSpec into a live Wallet.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    address()
    Lowercase 0x... hex address.
    Network
    network()
    Network the wallet is bound to.
    byte[]
    signTypedData(EIP712TypedData td)
    Produce a signature over the EIP-712 digest implied by td.

  • Method Details

    • address

      String address()
      Lowercase 0x... hex address. EVM addresses are 42 chars.

    • network

      Network network()
      Network the wallet is bound to. Cross-network use is not supported.

    • signTypedData

      byte[] signTypedData(EIP712TypedData td)
      Produce a signature over the EIP-712 digest implied by td.
      Parameters:
      td - prepared domain-separator + struct-hash pair
      Returns:
      65 bytes for EVM (r || s || v), 64 for SVM
      Throws:
      NullPointerException - if td is null