@canton-network/core-signing-fireblocks 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# Fireblocks Signing Driver
+
+A driver for signing and retrieving transactions using the Fireblocks API implementing the `SigningDriverInterface` from `@canton-network/core-signing-lib`.
+
+# Testing
+
+To test the Fireblocks signing driver with mocks, you can use the normal `yarn workspace @canton-network/core-signing-fireblocks test` command from the root directory.
+
+To test with an actual Fireblocks account:
+
+1. Generate a Fireblocks signing key: `openssl req -new -newkey rsa:4096 -nodes -keyout fireblocks_secret.key -out fireblocks.csr -subj '/O=Digital Asset - Canton'`
+2. Put the `fireblocks_secret.key` file in this directory
+3. Create an API User in Fireblocks and upload the `fireblocks.csr` file. Save the API Key it gives you (it will be a UUIDv4 string)
+4. From the root directory, run the tests with: `FIREBLOCKS_API_KEY=<your_api_key> yarn workspace @canton-network/core-signing-fireblocks test`

package/dist/fireblocks.d.ts

@@ -0,0 +1,71 @@
+import { PublicKeyInformationAlgorithmEnum } from '@fireblocks/ts-sdk';
+import { SigningStatus } from '@canton-network/core-signing-lib';
+interface FireblocksKey {
+    name: string;
+    publicKey: string;
+    derivationPath: number[];
+    algorithm: PublicKeyInformationAlgorithmEnum;
+}
+export interface FireblocksTransaction {
+    txId: string;
+    status: SigningStatus;
+    createdAt?: number;
+    signature?: string | undefined;
+    publicKey?: string | undefined;
+    derivationPath: number[];
+}
+export interface FireblocksApiKeyInfo {
+    apiKey: string;
+    apiSecret: string;
+}
+export declare class FireblocksHandler {
+    private defaultClient;
+    private clients;
+    private keyInfoByPublicKey;
+    private publicKeyByDerivationPath;
+    private getClient;
+    constructor(defaultKey: FireblocksApiKeyInfo | undefined, userKeys: Map<string, FireblocksApiKeyInfo>, apiPath?: string);
+    /**
+     * Get all public keys which correspond to Fireblocks vault accounts. This will
+     * also refresh the key cache.
+     * @returns List of Fireblocks public key information
+     */
+    getPublicKeys(userId: string | undefined): Promise<FireblocksKey[]>;
+    /**
+     * Takes a Fireblocks response from a transactions call and extracts the transaction information
+     * relevant to the Wallet Kernel. This will potentially fetch the public key since unsigned transactions
+     * do  not include it
+     * @returns FireblocksTransaction
+     */
+    private formatTransaction;
+    /**
+     * Looks up or fetches the public key (only) for a given derivation path
+     * @returns The public key as a string
+     */
+    private lookupPublicKey;
+    /**
+     * Fetch a single RAW transaction from Fireblocks by its transaction ID
+     * @returns FireblocksTransaction or undefined if not found
+     */
+    getTransaction(userId: string | undefined, txId: string): Promise<FireblocksTransaction | undefined>;
+    /**
+     * Get all RAW transactions from Fireblocks. Returns an async generator as
+     * this may return a large number of transactions and will occasionally need to
+     * refresh the key cache.
+     * @returns AsyncGenerator of FireblocksTransactions
+     */
+    getTransactions(userId: string | undefined, { limit, before, }?: {
+        limit?: number;
+        before?: number;
+    }): AsyncGenerator<FireblocksTransaction>;
+    /**
+     * Sign a transaction using a public key
+     * @param tx - The transaction to sign, as a string
+     * @param publicKey - The public key to use for signing
+     * @param externalTxId - The transaction ID assigned by the wallet kernel
+     * @return The transaction object from Fireblocks
+     */
+    signTransaction(userId: string | undefined, tx: string, publicKey: string, externalTxId?: string): Promise<FireblocksTransaction>;
+}
+export {};
+//# sourceMappingURL=fireblocks.d.ts.map

package/dist/fireblocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fireblocks.d.ts","sourceRoot":"","sources":["../src/fireblocks.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,iCAAiC,EAGpC,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,aAAa,EAAgB,MAAM,kCAAkC,CAAA;AAiB9E,UAAU,aAAa;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,SAAS,EAAE,iCAAiC,CAAA;CAC/C;AAED,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,aAAa,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,cAAc,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CACpB;AAID,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,OAAO,CAAqC;IAEpD,OAAO,CAAC,kBAAkB,CAAwC;IAClE,OAAO,CAAC,yBAAyB,CAAiC;IAElE,OAAO,CAAC,SAAS,CAQhB;gBAGG,UAAU,EAAE,oBAAoB,GAAG,SAAS,EAC5C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAC3C,OAAO,GAAE,MAAuC;IAmBpD;;;;OAIG;IACU,aAAa,CACtB,MAAM,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAAC,aAAa,EAAE,CAAC;IA+C3B;;;;;OAKG;YACW,iBAAiB;IAmD/B;;;OAGG;YACW,eAAe;IA+B7B;;;OAGG;IACU,cAAc,CACvB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC;IAa7C;;;;;OAKG;IACW,eAAe,CACzB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EACI,KAAW,EACX,MAAM,GACT,GAAE;QACC,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,MAAM,CAAC,EAAE,MAAM,CAAA;KACb,GACP,cAAc,CAAC,qBAAqB,CAAC;IAmCxC;;;;;;OAMG;IACU,eAAe,CACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,qBAAqB,CAAC;CAwDpC"}

package/dist/fireblocks.js

@@ -0,0 +1,286 @@
+import { Fireblocks, PublicKeyInformationAlgorithmEnum, } from '@fireblocks/ts-sdk';
+import { pino } from 'pino';
+import { CC_COIN_TYPE } from '@canton-network/core-signing-lib';
+import { z } from 'zod';
+const RawMessageSchema = z.object({
+    content: z.string(),
+    derivationPath: z.array(z.number()),
+});
+const RawMessageDataSchema = z.object({
+    messages: z.array(RawMessageSchema),
+    algorithm: z.string(),
+});
+const RawMessageExtraParametersSchema = z.object({
+    rawMessageData: RawMessageDataSchema,
+});
+const logger = pino({ name: 'main', level: 'debug' });
+export class FireblocksHandler {
+    defaultClient = undefined;
+    clients = new Map();
+    keyInfoByPublicKey = new Map();
+    publicKeyByDerivationPath = new Map();
+    getClient = (userId) => {
+        if (userId !== undefined && this.clients.has(userId)) {
+            return this.clients.get(userId);
+        }
+        else if (this.defaultClient) {
+            return this.defaultClient;
+        }
+        else {
+            throw new Error('No Fireblocks client available for this user.');
+        }
+    };
+    constructor(defaultKey, userKeys, apiPath = 'https://api.fireblocks.io/v1') {
+        if (defaultKey) {
+            this.defaultClient = new Fireblocks({
+                apiKey: defaultKey.apiKey,
+                basePath: apiPath,
+                secretKey: defaultKey.apiSecret,
+            });
+        }
+        userKeys.forEach((keyInfo, userId) => {
+            const client = new Fireblocks({
+                apiKey: keyInfo.apiKey,
+                basePath: apiPath,
+                secretKey: keyInfo.apiSecret,
+            });
+            this.clients.set(userId, client);
+        });
+    }
+    /**
+     * Get all public keys which correspond to Fireblocks vault accounts. This will
+     * also refresh the key cache.
+     * @returns List of Fireblocks public key information
+     */
+    async getPublicKeys(userId) {
+        const keys = [];
+        try {
+            const client = this.getClient(userId);
+            const vaultAccounts = [];
+            let after = undefined;
+            do {
+                const resp = await client.vaults.getPagedVaultAccounts(after ? { after } : {});
+                after = resp.data.paging?.after;
+                vaultAccounts.push(...(resp.data.accounts || []));
+            } while (after !== undefined);
+            for (const vault of vaultAccounts) {
+                if (vault.id) {
+                    const derivationPath = [
+                        44,
+                        CC_COIN_TYPE,
+                        Number(vault.id) || 0,
+                        0,
+                        0,
+                    ];
+                    const publicKey = await this.lookupPublicKey(userId, derivationPath);
+                    const storedKey = {
+                        derivationPath,
+                        publicKey,
+                        name: vault.name || vault.id,
+                        algorithm: PublicKeyInformationAlgorithmEnum.EddsaEd25519,
+                    };
+                    keys.push(storedKey);
+                    this.keyInfoByPublicKey.set(storedKey.publicKey, storedKey);
+                }
+            }
+        }
+        catch (error) {
+            logger.error(error, 'Error fetching vault accounts:');
+            throw error;
+        }
+        return keys;
+    }
+    /**
+     * Takes a Fireblocks response from a transactions call and extracts the transaction information
+     * relevant to the Wallet Kernel. This will potentially fetch the public key since unsigned transactions
+     * do  not include it
+     * @returns FireblocksTransaction
+     */
+    async formatTransaction(userId, tx) {
+        if (tx.signedMessages && tx.signedMessages.length > 0) {
+            const signedMessage = tx.signedMessages[0];
+            if (!signedMessage.publicKey ||
+                !signedMessage.content ||
+                !signedMessage.signature) {
+                return undefined;
+            }
+            return {
+                txId: tx.id,
+                status: 'signed',
+                createdAt: tx.createdAt,
+                publicKey: signedMessage.publicKey,
+                signature: signedMessage.signature.fullSig,
+                derivationPath: signedMessage.derivationPath,
+            };
+        }
+        else {
+            const rawMessageData = RawMessageExtraParametersSchema.safeParse(tx.extraParameters);
+            if (!rawMessageData.success) {
+                // Skip transactions with invalid rawMessageData
+                return undefined;
+            }
+            const message = rawMessageData.data.rawMessageData.messages[0];
+            const publicKey = await this.lookupPublicKey(userId, message.derivationPath);
+            const status = tx.status === 'REJECTED' || tx.status === 'BLOCKED'
+                ? 'rejected'
+                : tx.status === 'FAILED'
+                    ? 'failed'
+                    : 'pending';
+            return {
+                txId: tx.id,
+                status: status,
+                createdAt: tx.createdAt,
+                publicKey: publicKey,
+                derivationPath: message.derivationPath,
+            };
+        }
+    }
+    /**
+     * Looks up or fetches the public key (only) for a given derivation path
+     * @returns The public key as a string
+     */
+    async lookupPublicKey(userId, derivationPath) {
+        const derivationPathString = JSON.stringify(derivationPath);
+        if (this.publicKeyByDerivationPath.has(derivationPathString)) {
+            return this.publicKeyByDerivationPath.get(derivationPathString);
+        }
+        else {
+            try {
+                const client = this.getClient(userId);
+                const key = await client.vaults.getPublicKeyInfo({
+                    algorithm: PublicKeyInformationAlgorithmEnum.EddsaEd25519,
+                    derivationPath: derivationPathString,
+                });
+                if (key.data.publicKey) {
+                    this.publicKeyByDerivationPath.set(derivationPathString, key.data.publicKey);
+                    return key.data.publicKey;
+                }
+                else {
+                    throw new Error('Malformed public key response from Fireblocks');
+                }
+            }
+            catch (error) {
+                throw new Error(`Error looking up public key: ${error}`);
+            }
+        }
+    }
+    /**
+     * Fetch a single RAW transaction from Fireblocks by its transaction ID
+     * @returns FireblocksTransaction or undefined if not found
+     */
+    async getTransaction(userId, txId) {
+        try {
+            const client = this.getClient(userId);
+            const transaction = await client.transactions.getTransaction({
+                txId: txId,
+            });
+            return await this.formatTransaction(userId, transaction.data);
+        }
+        catch {
+            // if the transaction was not found for any reason, return undefined
+            return undefined;
+        }
+    }
+    /**
+     * Get all RAW transactions from Fireblocks. Returns an async generator as
+     * this may return a large number of transactions and will occasionally need to
+     * refresh the key cache.
+     * @returns AsyncGenerator of FireblocksTransactions
+     */
+    async *getTransactions(userId, { limit = 200, before, } = {}) {
+        let fetchedLength = 0;
+        let beforeQuery = before;
+        try {
+            const client = this.getClient(userId);
+            do {
+                const transactions = await client.transactions.getTransactions({
+                    sourceType: 'VAULT_ACCOUNT',
+                    limit,
+                    ...(beforeQuery ? { before: beforeQuery.toString() } : {}),
+                });
+                fetchedLength = transactions.data.length;
+                for (const tx of transactions.data) {
+                    // set next before to createdAt - 1 as before is inclusive of any transaction exactly at that
+                    // timestamp
+                    beforeQuery = tx.createdAt - 1;
+                    const formatTransaction = await this.formatTransaction(userId, tx);
+                    if (formatTransaction) {
+                        yield formatTransaction;
+                    }
+                    else {
+                        // if the transaction failed to format, continue so we do not skip remaining valid transactions
+                        continue;
+                    }
+                }
+                // once the fetched length is 0 before our last createdAt tx,
+                // there will be no transactions to fetch
+            } while (fetchedLength > 0);
+        }
+        catch (error) {
+            logger.error(error, 'Error fetching signatures');
+            throw error;
+        }
+    }
+    /**
+     * Sign a transaction using a public key
+     * @param tx - The transaction to sign, as a string
+     * @param publicKey - The public key to use for signing
+     * @param externalTxId - The transaction ID assigned by the wallet kernel
+     * @return The transaction object from Fireblocks
+     */
+    async signTransaction(userId, tx, publicKey, externalTxId) {
+        try {
+            const client = this.getClient(userId);
+            if (!this.keyInfoByPublicKey.has(publicKey)) {
+                // refresh the keycache
+                await this.getPublicKeys(userId);
+            }
+            const key = this.keyInfoByPublicKey.get(publicKey);
+            if (!key) {
+                throw new Error(`Public key ${publicKey} not found in vaults`);
+            }
+            const transaction = await client.transactions.createTransaction({
+                transactionRequest: {
+                    operation: 'RAW',
+                    note: `Signing transaction with public key ${publicKey}`,
+                    externalTxId,
+                    extraParameters: {
+                        rawMessageData: {
+                            messages: [
+                                {
+                                    content: tx,
+                                    derivationPath: key.derivationPath,
+                                },
+                            ],
+                            algorithm: key.algorithm,
+                        },
+                    },
+                },
+            });
+            let status = 'pending';
+            switch (transaction.data.status) {
+                case 'REJECTED':
+                    status = 'rejected';
+                    break;
+                case 'COMPLETED':
+                    status = 'signed';
+                    break;
+                case 'CANCELLED':
+                case 'FAILED':
+                case 'BLOCKED':
+                    status = 'failed';
+                    break;
+            }
+            return {
+                txId: transaction.data.id,
+                status,
+                publicKey: key.publicKey,
+                derivationPath: key.derivationPath,
+            };
+        }
+        catch (error) {
+            logger.error(error, 'Error signing transaction:');
+            throw error;
+        }
+    }
+}

package/dist/fireblocks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fireblocks.test.d.ts.map

package/dist/fireblocks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fireblocks.test.d.ts","sourceRoot":"","sources":["../src/fireblocks.test.ts"],"names":[],"mappings":""}

package/dist/fireblocks.test.js

@@ -0,0 +1,52 @@
+import { expect, test, describe } from '@jest/globals';
+import { FireblocksHandler } from './fireblocks.js';
+import { readFileSync } from 'fs-extra';
+import path from 'path';
+const TEST_TRANSACTION_HASH = '88beb0783e394f6128699bad42906374ab64197d260db05bb0cfeeb518ba3ac2';
+const SECRET_KEY_LOCATION = 'fireblocks_secret.key';
+const TEST_USER_ID = 'test-user-id';
+describe('fireblocks handler', () => {
+    const apiKey = process.env.FIREBLOCKS_API_KEY;
+    if (!apiKey) {
+        // skip this test suite if FIREBLOCKS_API_KEY is not set - there's really nothing to test for this class
+        // if the API Key is not set. Mocked functionality of this class is tested in context of the controller
+        // in index.test.ts
+        test.skip('FIREBLOCKS_API_KEY environment variable is not set, skipping test.', () => { });
+    }
+    else {
+        const secretPath = path.resolve(process.cwd(), SECRET_KEY_LOCATION);
+        const apiSecret = readFileSync(secretPath, 'utf8');
+        const userApiKeys = new Map([[TEST_USER_ID, { apiKey, apiSecret }]]);
+        const handler = new FireblocksHandler(undefined, userApiKeys);
+        test('error is thrown if userId is not found and there is no default', async () => {
+            await expect(handler.getPublicKeys('unknown')).rejects.toThrow();
+        });
+        const userId = TEST_USER_ID;
+        test('getPublicKeys', async () => {
+            const keys = await handler.getPublicKeys(userId);
+            expect(keys.length).toBeGreaterThan(0);
+        }, 25000);
+        test('sign and find transaction', async () => {
+            const transaction = await handler.signTransaction(userId, TEST_TRANSACTION_HASH, '02fefbcc9aebc8a479f211167a9f564df53aefd603a8662d9449a98c1ead2eba');
+            expect(transaction).toBeDefined();
+            const foundTransaction = await handler.getTransaction(userId, transaction.txId);
+            expect(foundTransaction).toBeDefined();
+        });
+        test('findTransaction failure', async () => {
+            const badTransaction = await handler.getTransaction(userId, 'bad-tx-id');
+            expect(badTransaction).toBeUndefined();
+        });
+        test('getTransactions', async () => {
+            const transactions = await Array.fromAsync(handler.getTransactions(userId, { limit: 200 }));
+            // ensure transactions created by other tests are not included
+            const before = transactions[0]?.createdAt;
+            const limitedTransactions = await Array.fromAsync(handler.getTransactions(userId, { limit: 25, before }));
+            expect(transactions.length).toEqual(limitedTransactions.length);
+        }, 25000);
+        const defaultHandler = new FireblocksHandler({ apiKey, apiSecret }, new Map());
+        test('getPublicKeys works with a default handler', async () => {
+            const keys = await defaultHandler.getPublicKeys(userId);
+            expect(keys.length).toBeGreaterThan(0);
+        }, 25000);
+    }
+});

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { PartyMode, SigningDriverInterface, SigningProvider } from '@canton-network/core-signing-lib';
+import { FireblocksApiKeyInfo } from './fireblocks.js';
+import { AuthContext } from '@canton-network/core-wallet-auth';
+export interface FireblocksConfig {
+    defaultKeyInfo?: FireblocksApiKeyInfo;
+    userApiKeys: Map<string, FireblocksApiKeyInfo>;
+    apiPath?: string;
+}
+export default class FireblocksSigningDriver implements SigningDriverInterface {
+    private fireblocks;
+    private config;
+    constructor(config: FireblocksConfig);
+    partyMode: PartyMode;
+    signingProvider: SigningProvider;
+    controller: (userId: AuthContext["userId"] | undefined) => {
+        signTransaction: import("@canton-network/core-signing-lib").SignTransaction;
+        getTransaction: import("@canton-network/core-signing-lib").GetTransaction;
+        getTransactions: import("@canton-network/core-signing-lib").GetTransactions;
+        getKeys: import("@canton-network/core-signing-lib").GetKeys;
+        createKey: import("@canton-network/core-signing-lib").CreateKey;
+        getConfiguration: import("@canton-network/core-signing-lib").GetConfiguration;
+        setConfiguration: import("@canton-network/core-signing-lib").SetConfiguration;
+        subscribeTransactions: import("@canton-network/core-signing-lib").SubscribeTransactions;
+    };
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEH,SAAS,EACT,sBAAsB,EACtB,eAAe,EAClB,MAAM,kCAAkC,CAAA;AAmBzC,OAAO,EAAqB,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAGzE,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAE9D,MAAM,WAAW,gBAAgB;IAC7B,cAAc,CAAC,EAAE,oBAAoB,CAAA;IACrC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AA4BD,MAAM,CAAC,OAAO,OAAO,uBAAwB,YAAW,sBAAsB;IAC1E,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,gBAAgB;IAI7B,SAAS,YAAqB;IAC9B,eAAe,kBAA6B;IAC5C,UAAU,GAAI,QAAQ,WAAW,CAAC,QAAQ,CAAC,GAAG,SAAS;;;;;;;;;MA0KxD;CACT"}

package/dist/index.js

@@ -0,0 +1,162 @@
+// Disabled unused vars rule to allow for future implementations
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { buildController, PartyMode, SigningProvider, } from '@canton-network/core-signing-lib';
+import { FireblocksHandler } from './fireblocks.js';
+import _ from 'lodash';
+import { z } from 'zod';
+const FireblocksApiKeyInfoSchema = z.object({
+    apiKey: z.string(),
+    apiSecret: z.string(),
+});
+const FireblocksConfigSchema = z.object({
+    defaultApiKey: FireblocksApiKeyInfoSchema.optional(),
+    userApiKeys: z.map(z.string(), FireblocksApiKeyInfoSchema),
+    apiPath: z.string().optional(),
+});
+const createFireblocksHandler = (config) => {
+    return new FireblocksHandler(config.defaultKeyInfo
+        ? {
+            apiKey: config.defaultKeyInfo.apiKey,
+            apiSecret: config.defaultKeyInfo.apiSecret,
+        }
+        : undefined, config.userApiKeys, config.apiPath || 'https://api.fireblocks.io/v1');
+};
+export default class FireblocksSigningDriver {
+    fireblocks;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.fireblocks = createFireblocksHandler(config);
+    }
+    partyMode = PartyMode.EXTERNAL;
+    signingProvider = SigningProvider.FIREBLOCKS;
+    controller = (userId) => buildController({
+        signTransaction: async (params) => {
+            // TODO: validate transaction here
+            try {
+                const tx = await this.fireblocks.signTransaction(userId, params.txHash, params.publicKey, params.internalTxId);
+                return {
+                    txId: tx.txId,
+                    status: tx.status,
+                    signature: tx.signature,
+                    publicKey: tx.publicKey,
+                };
+            }
+            catch (error) {
+                return {
+                    error: 'signing_error',
+                    error_description: error.message,
+                };
+            }
+        },
+        getTransaction: async (params) => {
+            const tx = await this.fireblocks.getTransaction(userId, params.txId);
+            if (tx) {
+                return {
+                    txId: tx.txId,
+                    status: tx.status,
+                    signature: tx.signature,
+                    publicKey: tx.publicKey,
+                };
+            }
+            else {
+                return {
+                    error: 'transaction_not_found',
+                    error_description: 'The requested transaction does not exist.',
+                };
+            }
+        },
+        getTransactions: async (params) => {
+            const transactions = [];
+            if (params.publicKeys || params.txIds) {
+                const txIds = new Set(params.txIds);
+                const publicKeys = new Set(params.publicKeys);
+                for await (const tx of this.fireblocks.getTransactions(userId)) {
+                    if (txIds.has(tx.txId) ||
+                        publicKeys.has(tx.publicKey || '')) {
+                        transactions.push({
+                            txId: tx.txId,
+                            status: tx.status,
+                            signature: tx.signature,
+                            publicKey: tx.publicKey,
+                        });
+                    }
+                    if (params.txIds &&
+                        !params.publicKeys &&
+                        transactions.length == txIds.size) {
+                        // stop if we are filtering by only txIds and have found all requested transactions
+                        break;
+                    }
+                }
+                return {
+                    transactions: transactions,
+                };
+            }
+            else {
+                return {
+                    error: 'bad_arguments',
+                    error_description: 'either public key or txIds must be supplied',
+                };
+            }
+        },
+        getKeys: async () => {
+            try {
+                const keys = await this.fireblocks.getPublicKeys(userId);
+                return {
+                    keys: keys.map((k) => ({
+                        id: k.derivationPath.join('-'),
+                        name: k.name,
+                        publicKey: k.publicKey,
+                    })),
+                };
+            }
+            catch (error) {
+                return {
+                    error: 'fetch_error',
+                    error_description: error.message,
+                };
+            }
+        },
+        createKey: async (_params) => {
+            return {
+                error: 'not_allowed',
+                error_description: 'Creating a Fireblocks key through the Wallet Kernel is not allowed, please create new keys directly in Fireblocks.',
+            };
+        },
+        getConfiguration: async () => {
+            const hideFireblocksKeySecret = (keyInfo) => {
+                return keyInfo
+                    ? {
+                        apiKey: keyInfo.apiKey,
+                        apiSecret: '***HIDDEN***',
+                    }
+                    : undefined;
+            };
+            return {
+                ...this.config,
+                defaultKeyInfo: hideFireblocksKeySecret(this.config.defaultKeyInfo),
+                userApiKeys: new Map([...this.config.userApiKeys].map(([k, v]) => [
+                    k,
+                    hideFireblocksKeySecret(v),
+                ])),
+            };
+        },
+        setConfiguration: async (params) => {
+            const validated = FireblocksConfigSchema.safeParse(params);
+            if (!validated.success) {
+                return {
+                    error: 'bad_arguments',
+                    error_description: validated.error.message,
+                };
+            }
+            if (!_.isEqual(validated.data, this.config)) {
+                this.config = validated.data;
+                this.fireblocks = createFireblocksHandler(this.config);
+            }
+            return params;
+        },
+        // TODO: implement subscribeTransactions - we will need to figure out how to handle subscriptions
+        // when the controller is not running in a server context
+        subscribeTransactions: async (params) => Promise.resolve({}),
+    });
+}

package/dist/index.test.d.ts

@@ -0,0 +1,3 @@
+import { Error as RpcError } from '@canton-network/core-signing-lib';
+export declare function throwWhenRpcError<T>(value: T | RpcError): void;
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"AAMA,OAAO,EAIH,KAAK,IAAI,QAAQ,EAEpB,MAAM,kCAAkC,CAAA;AA0GzC,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,GAAG,IAAI,CAM9D"}

package/dist/index.test.js

@@ -0,0 +1,188 @@
+import { expect, test } from '@jest/globals';
+import FireblocksSigningDriver from './index.js';
+import { readFileSync } from 'fs-extra';
+import path from 'path';
+import { isRpcError, CC_COIN_TYPE, } from '@canton-network/core-signing-lib';
+import { PublicKeyInformationAlgorithmEnum } from '@fireblocks/ts-sdk';
+const TEST_KEY_NAME = 'test-key-name';
+const TEST_TRANSACTION = 'test-tx';
+const TEST_TRANSACTION_HASH = '88beb0783e394f6128699bad42906374ab64197d260db05bb0cfeeb518ba3ac2';
+const TEST_FIREBLOCKS_DERIVATION_PATH = [42, CC_COIN_TYPE, 4, 0, 0];
+const TEST_FIREBLOCKS_VAULT_ID = TEST_FIREBLOCKS_DERIVATION_PATH.join('-');
+const TEST_FIREBLOCKS_PUBLIC_KEY = '02fefbcc9aebc8a479f211167a9f564df53aefd603a8662d9449a98c1ead2eba';
+const FAKE_TRANSACTION = {
+    txId: TEST_TRANSACTION_HASH,
+    status: 'signed',
+    signature: 'test-signature',
+    publicKey: TEST_FIREBLOCKS_PUBLIC_KEY,
+    derivationPath: TEST_FIREBLOCKS_DERIVATION_PATH,
+};
+const TEST_AUTH_CONTEXT = {
+    userId: 'test-user-id',
+    accessToken: 'test-access-token',
+};
+const TEST_BAD_AUTH_CONTEXT = {
+    userId: 'bad-user-id',
+    accessToken: 'test-access-token',
+};
+jest.mock('./fireblocks', () => {
+    const actual = jest.requireActual('./fireblocks');
+    if (process.env.FIREBLOCKS_API_KEY) {
+        return actual;
+    }
+    else {
+        return {
+            // NOTE: beware that the mock's constructor is _not_ typesafe, if the constructor's first argument is changed,
+            // the test will fail at runtime, not at compile time
+            FireblocksHandler: jest
+                .fn()
+                .mockImplementation((defaultKey) => {
+                return {
+                    constructor: jest.fn(),
+                    getPublicKeys: jest
+                        .fn()
+                        .mockImplementation((userId) => {
+                        if (userId === TEST_AUTH_CONTEXT.userId ||
+                            defaultKey !== undefined) {
+                            return [
+                                {
+                                    name: TEST_KEY_NAME,
+                                    publicKey: TEST_FIREBLOCKS_PUBLIC_KEY,
+                                    derivationPath: [
+                                        42,
+                                        CC_COIN_TYPE,
+                                        4,
+                                        0,
+                                        0,
+                                    ],
+                                    algorithm: PublicKeyInformationAlgorithmEnum.EddsaEd25519,
+                                },
+                            ];
+                        }
+                        else {
+                            return {
+                                error: 'User not found',
+                                error_description: 'User does not exist in Fireblocks',
+                            };
+                        }
+                    }),
+                    getTransactions: jest.fn(() => {
+                        async function* generator() {
+                            yield FAKE_TRANSACTION;
+                        }
+                        return generator();
+                    }),
+                    getTransaction: jest
+                        .fn()
+                        .mockResolvedValue(FAKE_TRANSACTION),
+                    signTransaction: jest.fn().mockResolvedValue({
+                        txId: TEST_TRANSACTION_HASH,
+                        status: 'signed',
+                    }),
+                };
+            }),
+        };
+    }
+});
+export function throwWhenRpcError(value) {
+    if (isRpcError(value)) {
+        throw new Error(`Expected a valid return, but got an error: ${value.error_description}`);
+    }
+}
+async function setupTest(keyName = TEST_KEY_NAME) {
+    const apiKey = process.env.FIREBLOCKS_API_KEY;
+    const secretLocation = process.env.SECRET_KEY_LOCATION || 'fireblocks_secret.key';
+    let keyInfo;
+    if (!apiKey) {
+        keyInfo = {
+            apiKey: 'mocked',
+            apiSecret: 'mocked',
+        };
+    }
+    else {
+        const secretPath = path.resolve(process.cwd(), secretLocation);
+        const apiSecret = readFileSync(secretPath, 'utf8');
+        keyInfo = {
+            apiKey,
+            apiSecret,
+        };
+    }
+    const userApiKeys = new Map([
+        [TEST_AUTH_CONTEXT.userId, keyInfo],
+    ]);
+    const signingDriver = new FireblocksSigningDriver({
+        defaultKeyInfo: keyInfo,
+        userApiKeys,
+    });
+    const noDefaultSigningDriver = new FireblocksSigningDriver({
+        defaultKeyInfo: undefined,
+        userApiKeys,
+    });
+    const key = {
+        id: TEST_FIREBLOCKS_VAULT_ID,
+        name: keyName,
+        publicKey: TEST_FIREBLOCKS_PUBLIC_KEY,
+    };
+    return {
+        signingDriver,
+        noDefaultSigningDriver,
+        key,
+        controller: signingDriver.controller(TEST_AUTH_CONTEXT.userId),
+    };
+}
+test('key creation', async () => {
+    const { controller } = await setupTest();
+    const err = await controller.createKey({ name: 'test' });
+    expect(isRpcError(err)).toBe(true);
+});
+test('non-existing user cannot use driver without a default', async () => {
+    const { noDefaultSigningDriver } = await setupTest();
+    const err = await noDefaultSigningDriver
+        .controller(TEST_BAD_AUTH_CONTEXT.userId)
+        .getKeys();
+    expect(isRpcError(err)).toBe(true);
+});
+test('non-existing user can use driver that does have a default', async () => {
+    const { signingDriver } = await setupTest();
+    const keys = await signingDriver
+        .controller(TEST_BAD_AUTH_CONTEXT.userId)
+        .getKeys();
+    expect(isRpcError(keys)).toBe(false);
+});
+test('transaction signature', async () => {
+    const { controller, key } = await setupTest();
+    const tx = await controller.signTransaction({
+        tx: TEST_TRANSACTION,
+        txHash: TEST_TRANSACTION_HASH,
+        publicKey: key.publicKey,
+    });
+    throwWhenRpcError(tx);
+    // this hash has already been signed so Fireblocks won't bother getting it signed again
+    expect(tx.status).toBe('signed');
+    const transactionsByKey = await controller.getTransactions({
+        publicKeys: [key.publicKey],
+    });
+    throwWhenRpcError(transactionsByKey);
+    expect(transactionsByKey.transactions?.find((t) => t.txId === tx.txId)).toBeDefined();
+    const transactionsById = await controller.getTransactions({
+        txIds: [tx.txId],
+    });
+    throwWhenRpcError(transactionsById);
+    expect(transactionsById.transactions?.find((t) => t.txId === tx.txId)).toBeDefined();
+    const foundTx = await controller.getTransaction({
+        txId: tx.txId,
+    });
+    throwWhenRpcError(foundTx);
+}, 60000);
+test('test config change', async () => {
+    const { controller } = await setupTest();
+    const newPath = 'new-path';
+    const config = await controller.getConfiguration();
+    controller.setConfiguration({
+        defaultKeyInfo: config.defaultKeyInfo,
+        userApiKeys: config.userApiKeys,
+        apiPath: newPath,
+    });
+    const newConfig = await controller.getConfiguration();
+    expect(newConfig.apiPath).toBe(newPath);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@canton-network/core-signing-fireblocks",
+  "version": "0.1.0",
+  "packageManager": "yarn@4.9.2",
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean && rm -rf ./dist",
+    "test": "jest"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "dependencies": {
+    "@canton-network/core-signing-lib": "^0.1.0",
+    "@canton-network/core-wallet-auth": "^0.1.0",
+    "@fireblocks/ts-sdk": "^10.2.0",
+    "async-mutex": "^0.5.0",
+    "fs-extra": "^11.3.0",
+    "lodash": "^4.17.21",
+    "pino": "^9.7.0",
+    "tweetnacl": "^1.0.3",
+    "tweetnacl-util": "^0.15.1",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.0.0",
+    "@swc/core": "^1.11.31",
+    "@swc/jest": "^0.2.38",
+    "@types/fs-extra": "^11",
+    "@types/jest": "^29.5.14",
+    "@types/lodash": "^4.17.17",
+    "@types/node": "^22.15.29",
+    "jest": "^29.7.0",
+    "ts-jest-resolver": "^2.0.1",
+    "typescript": "^5.8.3"
+  },
+  "files": [
+    "dist/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}