Manage key stores

In the FT4 client library, the KeyStore interface represents a general abstraction for managing cryptographic keys. This abstraction is crucial for implementing security and transaction signing mechanisms. Two key implementations extend this interface:

1. EvmKeyStore: Designed for Ethereum-compatible keys.
2. FtKeyStore: Designed for FT4-specific keys.

Both implementations provide methods to sign messages or transactions and to integrate with authentication handlers.

KeyStore interface

The KeyStore interface defines the foundational structure and behavior for cryptographic key management:

• Properties:
  • id: Buffer: A unique identifier for the key.
  • isInteractive: boolean: Indicates if signing requires user interaction.
• Methods:
  • createKeyHandler(authDescriptor: AnyAuthDescriptor): KeyHandler: Creates a handler that interacts with the key for authorization purposes.

EvmKeyStore implementation

Description

The EvmKeyStore extends KeyStore and implements the EvmSigner interface. It is designed for managing Ethereum-compatible (EVM) keys and includes functionality to sign Ethereum messages and handle EVM-specific operations.

Properties and methods

• Properties:
  • address: Buffer: The Ethereum address associated with the key (without the leading 0x).
• Methods:
  • signMessage(message: string): Promise<Signature>: Signs a given message using the EVM key.
  • createKeyHandler(authDescriptor: AnyAuthDescriptor): KeyHandler: Implements key handler creation.

Instantiation options

1. In-memory EvmKeyStore

   • Created with ephemeral keys stored in memory.
   • Method: createInMemoryEvmKeyStore(keyPair: KeyPair): EvmKeyStore
   • Example:

     const keyPair = { privKey: Buffer.from("private_key_hex", "hex") };
     const evmKeyStore = createInMemoryEvmKeyStore(keyPair);

2. Generic EvmKeyStore

   • Allows customization with a provided signing function and configuration.

   • Method: createGenericEvmKeyStore(config: { address: string, signMessage: Function, isInteractive?: boolean }): Promise<EvmKeyStore>

   • Example:

     const evmKeyStore = await createGenericEvmKeyStore({
       address: "YourEthereumAddress",
       signMessage: async (message) => "signature_string",
       isInteractive: false,
     });

3. Web3 provider EvmKeyStore

   • Integrates with external Web3 providers (e.g., MetaMask).

   • Method: createWeb3ProviderEvmKeyStore(externalProvider: Eip1193Provider): Promise<EvmKeyStore>

   • Example:

     const evmKeyStore = await createWeb3ProviderEvmKeyStore(window.ethereum);

FtKeyStore implementation

The FtKeyStore extends KeyStore and implements the FtSigner interface. It manages FT4-specific keys and supports signing FT4 transactions.

Properties and methods

• Properties:

  • pubKey: Buffer: The public key associated with the FT4 key.

• Methods:

  • sign(transaction: GTX | RawGtx): Promise<Buffer>: Signs an FT4 transaction.
  • createKeyHandler(authDescriptor: AnyAuthDescriptor): KeyHandler: Implements key handler creation.

Instantiation options

1. In-memory FtKeyStore

   • Created with ephemeral keys stored in memory.
   • Method: createInMemoryFtKeyStore(keyHolder: KeyPair | SignatureProvider): FtKeyStore
   • Example:

     const keyPair = { privKey: Buffer.from("private_key_hex", "hex") };
     const ftKeyStore = createInMemoryFtKeyStore(keyPair);

Storage options

The FT4 client supports storing keys in:

1. Memory: Keys are stored temporarily and cleared upon application restart.
2. Session storage: Keys persist only for the duration of the browser session.
3. Local storage: Keys persist across browser sessions and application restarts (custom implementations may be needed).

Even though there are implementations ready for the generic KeyStore, individual implementations for custom stores need to be implemented.

Using in-memory storage

In-memory storage is the default for ephemeral keys, especially for testing.

Custom storage implementation

For session or local storage, wrap the KeyStore creation logic to persist the keys using browser APIs or custom storage strategies.

Key differences

Feature	EvmKeyStore	FtKeyStore
Purpose	Ethereum-compatible signing	FT4-specific signing
Identifier	address	pubKey
Signing Method	signMessage	sign
Storage Options	Memory, Session, Browser	Memory

Example usage

EvmKeyStore with Web3 provider

const evmKeyStore = await createWeb3ProviderEvmKeyStore(window.ethereum);
const signature = await evmKeyStore.signMessage("Hello, Ethereum!");

FtKeyStore with in-memory keys

const keyPair = { privKey: Buffer.from("private_key_hex", "hex") };
const ftKeyStore = createInMemoryFtKeyStore(keyPair);
const signedTx = await ftKeyStore.sign(someTransaction);