@solana/keychain-core 0.0.0 → 0.3.0

package/README.md

@@ -0,0 +1,124 @@
+# @solana/keychain-core
+
+Core interfaces and utilities for building external Solana signers.
+
+## Installation
+
+```bash
+pnpm add @solana/keychain-core
+```
+
+## What's Included
+
+### Interfaces
+
+**`SolanaSigner`** - Unified interface that all signer implementations extend:
+
+```typescript
+import { SolanaSigner } from '@solana/keychain-core';
+
+interface SolanaSigner {
+    address: Address;
+    isAvailable(): Promise<boolean>;
+    signMessages(messages: readonly SignableMessage[]): Promise<readonly SignatureDictionary[]>;
+    signTransactions(transactions: readonly Transaction[]): Promise<readonly SignatureDictionary[]>;
+}
+```
+
+### Error Handling
+
+```typescript
+import { SignerError, SignerErrorCode, throwSignerError } from '@solana/keychain-core';
+
+// Check error type
+if (error instanceof SignerError) {
+    console.log(error.code); // e.g., 'SIGNER_SIGNING_FAILED'
+    console.log(error.context); // Additional error details
+}
+
+// Throw typed errors
+throwSignerError(SignerErrorCode.SIGNING_FAILED, {
+    address: 'signer-address',
+    message: 'Custom error message'
+});
+```
+
+**Available error codes:**
+- `INVALID_PRIVATE_KEY` - Invalid private key format
+- `INVALID_PUBLIC_KEY` - Invalid public key format
+- `SIGNING_FAILED` - Signing operation failed
+- `REMOTE_API_ERROR` - Remote signer API error
+- `HTTP_ERROR` - HTTP request failed
+- `SERIALIZATION_ERROR` - Transaction serialization failed
+- `CONFIG_ERROR` - Invalid configuration
+- `NOT_AVAILABLE` - Signer not available/healthy
+- `IO_ERROR` - File I/O error
+- `PRIVY_NOT_INITIALIZED` - Privy signer not initialized
+
+### Utilities
+
+**`extractSignatureFromWireTransaction`** - Extract a specific signer's signature from a signed transaction:
+
+```typescript
+import { extractSignatureFromWireTransaction } from '@solana/keychain-core';
+
+// When a remote API returns a fully signed base64 transaction, we need to extract the signature to use Kit's native methods (which rely on .signTransactions to return a SignatureDictionary)
+const signedTx = await remoteApi.signTransaction(...);
+const sigDict = extractSignatureFromWireTransaction({
+    base64WireTransaction: signedTx,
+    signerAddress: myAddress
+});
+```
+
+**`createSignatureDictionary`** - Create a signature dictionary from raw signature bytes:
+
+```typescript
+import { createSignatureDictionary } from '@solana/keychain-core';
+
+const sigDict = createSignatureDictionary({
+    signature: signatureBytes,
+    signerAddress: myAddress
+});
+```
+
+## Usage
+
+This package is typically used as a dependency when building custom signer implementations. See [@solana/keychain-privy](https://www.npmjs.com/package/@solana/keychain-privy) for an example implementation.
+
+```typescript
+import { SolanaSigner, SignerErrorCode, throwSignerError } from '@solana/keychain-core';
+
+class MyCustomSigner implements SolanaSigner {
+    readonly address: Address;
+
+    async isAvailable(): Promise<boolean> {
+        // Check if backend is healthy
+    }
+
+    async signMessages(messages: readonly SignableMessage[]) {
+        // Sign messages using your backend
+    }
+
+    async signTransactions(transactions: readonly Transaction[]) {
+        // Sign transactions using your backend
+    }
+}
+```
+
+## Type Guards
+
+**`isSolanaSigner`** - Check if a value is a SolanaSigner:
+
+```typescript
+import { isSolanaSigner } from '@solana/keychain-core';
+
+const isSigner = isSolanaSigner(value); // true or false
+```
+
+**`assertIsSolanaSigner`** - Assert that a value is a SolanaSigner:
+
+```typescript
+import { assertIsSolanaSigner } from '@solana/keychain-core';
+
+assertIsSolanaSigner(value); // void (throws if not a SolanaSigner)
+```

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Custom error codes for solana-keychain, specific to this library
+ */
+export declare enum SignerErrorCode {
+    INVALID_PRIVATE_KEY = "SIGNER_INVALID_PRIVATE_KEY",
+    INVALID_PUBLIC_KEY = "SIGNER_INVALID_PUBLIC_KEY",
+    SIGNING_FAILED = "SIGNER_SIGNING_FAILED",
+    REMOTE_API_ERROR = "SIGNER_REMOTE_API_ERROR",
+    HTTP_ERROR = "SIGNER_HTTP_ERROR",
+    SERIALIZATION_ERROR = "SIGNER_SERIALIZATION_ERROR",
+    PARSING_ERROR = "SIGNER_PARSING_ERROR",
+    CONFIG_ERROR = "SIGNER_CONFIG_ERROR",
+    NOT_AVAILABLE = "SIGNER_NOT_AVAILABLE",
+    IO_ERROR = "SIGNER_IO_ERROR",
+    SIGNER_NOT_INITIALIZED = "SIGNER_NOT_INITIALIZED",
+    EXPECTED_SOLANA_SIGNER = "SIGNER_EXPECTED_SOLANA_SIGNER"
+}
+/**
+ * Custom error class for signer-specific errors
+ * Extends Error with code and context properties
+ */
+export declare class SignerError extends Error {
+    readonly code: SignerErrorCode;
+    readonly context?: Record<string, unknown>;
+    constructor(code: SignerErrorCode, context?: Record<string, unknown>);
+}
+/**
+ * Helper function to create signer-specific errors
+ */
+export declare function createSignerError(code: SignerErrorCode, context?: Record<string, unknown>): SignerError;
+/**
+ * Helper function to throw signer-specific errors
+ */
+export declare function throwSignerError(code: SignerErrorCode, context?: Record<string, unknown>): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,eAAe;IACvB,mBAAmB,+BAA+B;IAClD,kBAAkB,8BAA8B;IAChD,cAAc,0BAA0B;IACxC,gBAAgB,4BAA4B;IAC5C,UAAU,sBAAsB;IAChC,mBAAmB,+BAA+B;IAClD,aAAa,yBAAyB;IACtC,YAAY,wBAAwB;IACpC,aAAa,yBAAyB;IACtC,QAAQ,oBAAoB;IAC5B,sBAAsB,2BAA2B;IACjD,sBAAsB,kCAAkC;CAC3D;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE/B,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQvE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAEvG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEhG"}

package/dist/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Custom error codes for solana-keychain, specific to this library
+ */
+export var SignerErrorCode;
+(function (SignerErrorCode) {
+    SignerErrorCode["INVALID_PRIVATE_KEY"] = "SIGNER_INVALID_PRIVATE_KEY";
+    SignerErrorCode["INVALID_PUBLIC_KEY"] = "SIGNER_INVALID_PUBLIC_KEY";
+    SignerErrorCode["SIGNING_FAILED"] = "SIGNER_SIGNING_FAILED";
+    SignerErrorCode["REMOTE_API_ERROR"] = "SIGNER_REMOTE_API_ERROR";
+    SignerErrorCode["HTTP_ERROR"] = "SIGNER_HTTP_ERROR";
+    SignerErrorCode["SERIALIZATION_ERROR"] = "SIGNER_SERIALIZATION_ERROR";
+    SignerErrorCode["PARSING_ERROR"] = "SIGNER_PARSING_ERROR";
+    SignerErrorCode["CONFIG_ERROR"] = "SIGNER_CONFIG_ERROR";
+    SignerErrorCode["NOT_AVAILABLE"] = "SIGNER_NOT_AVAILABLE";
+    SignerErrorCode["IO_ERROR"] = "SIGNER_IO_ERROR";
+    SignerErrorCode["SIGNER_NOT_INITIALIZED"] = "SIGNER_NOT_INITIALIZED";
+    SignerErrorCode["EXPECTED_SOLANA_SIGNER"] = "SIGNER_EXPECTED_SOLANA_SIGNER";
+})(SignerErrorCode || (SignerErrorCode = {}));
+/**
+ * Custom error class for signer-specific errors
+ * Extends Error with code and context properties
+ */
+export class SignerError extends Error {
+    constructor(code, context) {
+        const message = context?.message && typeof context.message === 'string' ? context.message : `Signer error: ${code}`;
+        super(message);
+        this.name = 'SignerError';
+        this.code = code;
+        this.context = context;
+    }
+}
+/**
+ * Helper function to create signer-specific errors
+ */
+export function createSignerError(code, context) {
+    return new SignerError(code, context);
+}
+/**
+ * Helper function to throw signer-specific errors
+ */
+export function throwSignerError(code, context) {
+    throw createSignerError(code, context);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,eAaX;AAbD,WAAY,eAAe;IACvB,qEAAkD,CAAA;IAClD,mEAAgD,CAAA;IAChD,2DAAwC,CAAA;IACxC,+DAA4C,CAAA;IAC5C,mDAAgC,CAAA;IAChC,qEAAkD,CAAA;IAClD,yDAAsC,CAAA;IACtC,uDAAoC,CAAA;IACpC,yDAAsC,CAAA;IACtC,+CAA4B,CAAA;IAC5B,oEAAiD,CAAA;IACjD,2EAAwD,CAAA;AAC5D,CAAC,EAbW,eAAe,KAAf,eAAe,QAa1B;AAED;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAIlC,YAAY,IAAqB,EAAE,OAAiC;QAChE,MAAM,OAAO,GACT,OAAO,EAAE,OAAO,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,IAAI,EAAE,CAAC;QACxG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAqB,EAAE,OAAiC;IACtF,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAqB,EAAE,OAAiC;IACrF,MAAM,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './errors.js';
+export * from './types.js';
+export * from './utils.js';
+//# 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":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './errors.js';
+export * from './types.js';
+export * from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+import type { Address } from '@solana/addresses';
+import type { MessagePartialSigner, SignableMessage, SignatureDictionary, TransactionPartialSigner } from '@solana/signers';
+import type { Transaction, TransactionWithinSizeLimit, TransactionWithLifetime } from '@solana/transactions';
+/**
+ * Unified signer interface that extends both transaction and message signers.
+ * Provides both high-level (simple) and low-level (@solana/kit compatible) APIs.
+ */
+export interface SolanaSigner<TAddress extends string = string> extends TransactionPartialSigner<TAddress>, MessagePartialSigner<TAddress> {
+    /**
+     * Get the public key address of this signer
+     */
+    readonly address: Address<TAddress>;
+    /**
+     * Check if the signer is available and healthy.
+     * For remote signers (Vault, Privy, Turnkey), this performs an API health check.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Signs multiple messages and returns signature dictionaries
+     * for @solana/kit signing compatibility.
+     *
+     * @param messages - Array of signable messages
+     * @returns Array of signature dictionaries (address -> signature mapping)
+     */
+    signMessages(messages: readonly SignableMessage[]): Promise<readonly SignatureDictionary[]>;
+    /**
+     * Signs multiple transactions and returns signature dictionaries.
+     * for @solana/kit signing compatibility.
+     *
+     * @param transactions - Array of transactions to sign
+     * @returns Array of signature dictionaries (address -> signature mapping)
+     */
+    signTransactions(transactions: readonly (Transaction & TransactionWithinSizeLimit & TransactionWithLifetime)[]): Promise<readonly SignatureDictionary[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EACR,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,WAAW,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE7G;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,CAC1D,SAAQ,wBAAwB,CAAC,QAAQ,CAAC,EACtC,oBAAoB,CAAC,QAAQ,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEpC;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IAE5F;;;;;;OAMG;IACH,gBAAgB,CACZ,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,0BAA0B,GAAG,uBAAuB,CAAC,EAAE,GAC9F,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;CAC9C"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/utils.d.ts

@@ -0,0 +1,61 @@
+import { Address } from '@solana/addresses';
+import { SignatureBytes } from '@solana/keys';
+import { SignatureDictionary } from '@solana/signers';
+import { Base64EncodedWireTransaction } from '@solana/transactions';
+import { SolanaSigner } from './types.js';
+interface ExtractSignatureFromWireTransactionOptions {
+    base64WireTransaction: Base64EncodedWireTransaction;
+    signerAddress: Address;
+}
+/**
+ * Extracts a specific signer's signature from a base64-encoded wire transaction.
+ * Useful for remote signers that return fully signed transactions from their APIs.
+ *
+ * @param base64WireTransaction - Base64 encoded transaction string
+ * @param signerAddress - The address of the signer whose signature to extract
+ * @returns SignatureDictionary with only the specified signer's signature
+ * @throws {SignerError} If no signature is found for the given address
+ *
+ * @example
+ * ```typescript
+ * // Privy API returns a signed transaction
+ * const signedTx = await privyApi.signTransaction(...);
+ * const sigDict = extractSignatureFromWireTransaction(signedTx, this.address);
+ * ```
+ */
+export declare function extractSignatureFromWireTransaction({ base64WireTransaction, signerAddress, }: ExtractSignatureFromWireTransactionOptions): SignatureDictionary;
+interface CreateSignatureDictionaryArgs {
+    signature: SignatureBytes;
+    signerAddress: Address;
+}
+/**
+ * Creates a signature dictionary from a signature and signer address.
+ * @param signature - The signature to create the dictionary from
+ * @param signerAddress - The address of the signer whose signature to create the dictionary from
+ * @returns SignatureDictionary with only the specified signer's signature
+ * @throws {SignerError} If no signature is found for the given address
+ *
+ * @example
+ * ```typescript
+ * const sigDict = createSignatureDictionary({ signature, signerAddress });
+ * ```
+ */
+export declare function createSignatureDictionary({ signature, signerAddress, }: CreateSignatureDictionaryArgs): SignatureDictionary;
+/**
+ * Checks if the given value is a SolanaSigner.
+ * @param value - The value to check
+ * @returns True if the value is a SolanaSigner, false otherwise
+ */
+export declare function isSolanaSigner<TAddress extends string>(value: {
+    address: Address<TAddress>;
+}): value is SolanaSigner<TAddress>;
+/**
+ * Asserts that the given value is a SolanaSigner, throwing an error if it is not.
+ * @param value - The value to check
+ * @throws {SignerError} If the value is not a SolanaSigner
+ */
+export declare function assertIsSolanaSigner<TAddress extends string>(value: {
+    address: Address<TAddress>;
+}): asserts value is SolanaSigner<TAddress>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAmB,MAAM,mBAAmB,CAAC;AAE7D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAsD,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC1G,OAAO,EAAE,4BAA4B,EAAyB,MAAM,sBAAsB,CAAC;AAG3F,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,UAAU,0CAA0C;IAChD,qBAAqB,EAAE,4BAA4B,CAAC;IACpD,aAAa,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mCAAmC,CAAC,EAChD,qBAAqB,EACrB,aAAa,GAChB,EAAE,0CAA0C,GAAG,mBAAmB,CAmBlE;AAED,UAAU,6BAA6B;IACnC,SAAS,EAAE,cAAc,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,EACtC,SAAS,EACT,aAAa,GAChB,EAAE,6BAA6B,GAAG,mBAAmB,CASrD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,SAAS,MAAM,EAAE,KAAK,EAAE;IAC3D,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9B,GAAG,KAAK,IAAI,YAAY,CAAC,QAAQ,CAAC,CAOlC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,SAAS,MAAM,EAAE,KAAK,EAAE;IACjE,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9B,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC,QAAQ,CAAC,CAM1C"}

package/dist/utils.js

@@ -0,0 +1,85 @@
+import { assertIsAddress } from '@solana/addresses';
+import { getBase64Encoder } from '@solana/codecs-strings';
+import { isMessagePartialSigner, isTransactionPartialSigner } from '@solana/signers';
+import { getTransactionDecoder } from '@solana/transactions';
+import { SignerErrorCode, throwSignerError } from './errors.js';
+/**
+ * Extracts a specific signer's signature from a base64-encoded wire transaction.
+ * Useful for remote signers that return fully signed transactions from their APIs.
+ *
+ * @param base64WireTransaction - Base64 encoded transaction string
+ * @param signerAddress - The address of the signer whose signature to extract
+ * @returns SignatureDictionary with only the specified signer's signature
+ * @throws {SignerError} If no signature is found for the given address
+ *
+ * @example
+ * ```typescript
+ * // Privy API returns a signed transaction
+ * const signedTx = await privyApi.signTransaction(...);
+ * const sigDict = extractSignatureFromWireTransaction(signedTx, this.address);
+ * ```
+ */
+export function extractSignatureFromWireTransaction({ base64WireTransaction, signerAddress, }) {
+    assertIsAddress(signerAddress);
+    const encoder = getBase64Encoder();
+    const decoder = getTransactionDecoder();
+    const transactionBytes = encoder.encode(base64WireTransaction);
+    const { signatures } = decoder.decode(transactionBytes);
+    const signature = signatures[signerAddress];
+    if (!signature) {
+        throwSignerError(SignerErrorCode.SIGNING_FAILED, {
+            address: signerAddress,
+            message: `No signature found for address ${signerAddress}`,
+        });
+    }
+    return createSignatureDictionary({
+        signature,
+        signerAddress,
+    });
+}
+/**
+ * Creates a signature dictionary from a signature and signer address.
+ * @param signature - The signature to create the dictionary from
+ * @param signerAddress - The address of the signer whose signature to create the dictionary from
+ * @returns SignatureDictionary with only the specified signer's signature
+ * @throws {SignerError} If no signature is found for the given address
+ *
+ * @example
+ * ```typescript
+ * const sigDict = createSignatureDictionary({ signature, signerAddress });
+ * ```
+ */
+export function createSignatureDictionary({ signature, signerAddress, }) {
+    assertIsAddress(signerAddress);
+    if (!signature) {
+        throwSignerError(SignerErrorCode.SIGNING_FAILED, {
+            address: signerAddress,
+            message: `No signature found for address ${signerAddress}`,
+        });
+    }
+    return Object.freeze({ [signerAddress]: signature });
+}
+/**
+ * Checks if the given value is a SolanaSigner.
+ * @param value - The value to check
+ * @returns True if the value is a SolanaSigner, false otherwise
+ */
+export function isSolanaSigner(value) {
+    return ('address' in value &&
+        'isAvailable' in value &&
+        isMessagePartialSigner(value) &&
+        isTransactionPartialSigner(value));
+}
+/**
+ * Asserts that the given value is a SolanaSigner, throwing an error if it is not.
+ * @param value - The value to check
+ * @throws {SignerError} If the value is not a SolanaSigner
+ */
+export function assertIsSolanaSigner(value) {
+    if (!isSolanaSigner(value)) {
+        throwSignerError(SignerErrorCode.EXPECTED_SOLANA_SIGNER, {
+            address: value.address,
+        });
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAuB,MAAM,iBAAiB,CAAC;AAC1G,OAAO,EAAgC,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE3F,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAQhE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mCAAmC,CAAC,EAChD,qBAAqB,EACrB,aAAa,GAC4B;IACzC,eAAe,CAAC,aAAa,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;IACxC,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAC/D,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAExD,MAAM,SAAS,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;IAC5C,IAAI,CAAC,SAAS,EAAE,CAAC;QACb,gBAAgB,CAAC,eAAe,CAAC,cAAc,EAAE;YAC7C,OAAO,EAAE,aAAa;YACtB,OAAO,EAAE,kCAAkC,aAAa,EAAE;SAC7D,CAAC,CAAC;IACP,CAAC;IAED,OAAO,yBAAyB,CAAC;QAC7B,SAAS;QACT,aAAa;KAChB,CAAC,CAAC;AACP,CAAC;AAOD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CAAC,EACtC,SAAS,EACT,aAAa,GACe;IAC5B,eAAe,CAAC,aAAa,CAAC,CAAC;IAC/B,IAAI,CAAC,SAAS,EAAE,CAAC;QACb,gBAAgB,CAAC,eAAe,CAAC,cAAc,EAAE;YAC7C,OAAO,EAAE,aAAa;YACtB,OAAO,EAAE,kCAAkC,aAAa,EAAE;SAC7D,CAAC,CAAC;IACP,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAA0B,KAEvD;IACG,OAAO,CACH,SAAS,IAAI,KAAK;QAClB,aAAa,IAAI,KAAK;QACtB,sBAAsB,CAAC,KAAK,CAAC;QAC7B,0BAA0B,CAAC,KAAK,CAAC,CACpC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAA0B,KAE7D;IACG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,gBAAgB,CAAC,eAAe,CAAC,sBAAsB,EAAE;YACrD,OAAO,EAAE,KAAK,CAAC,OAAO;SACzB,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}

package/package.json

@@ -1,12 +1,47 @@
 {
   "name": "@solana/keychain-core",
-  "version": "0.0.0",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "author": "Solana Foundation",
+  "license": "MIT",
+  "repository": "https://github.com/solana-foundation/solana-keychain",
+  "version": "0.3.0",
+  "description": "Core interfaces and types for external Solana signers",
+  "keywords": [
+    "solana",
+    "signing",
+    "wallet",
+    "privy",
+    "vault",
+    "turnkey"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@solana/addresses": "^5.0.0",
+    "@solana/codecs-core": "^5.0.0",
+    "@solana/codecs-strings": "^5.0.0",
+    "@solana/keys": "^5.0.0",
+    "@solana/signers": "^5.0.0",
+    "@solana/transactions": "^5.0.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": ""
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "pnpm run typecheck",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,49 @@
+/**
+ * Custom error codes for solana-keychain, specific to this library
+ */
+export enum SignerErrorCode {
+    INVALID_PRIVATE_KEY = 'SIGNER_INVALID_PRIVATE_KEY',
+    INVALID_PUBLIC_KEY = 'SIGNER_INVALID_PUBLIC_KEY',
+    SIGNING_FAILED = 'SIGNER_SIGNING_FAILED',
+    REMOTE_API_ERROR = 'SIGNER_REMOTE_API_ERROR',
+    HTTP_ERROR = 'SIGNER_HTTP_ERROR',
+    SERIALIZATION_ERROR = 'SIGNER_SERIALIZATION_ERROR',
+    PARSING_ERROR = 'SIGNER_PARSING_ERROR',
+    CONFIG_ERROR = 'SIGNER_CONFIG_ERROR',
+    NOT_AVAILABLE = 'SIGNER_NOT_AVAILABLE',
+    IO_ERROR = 'SIGNER_IO_ERROR',
+    SIGNER_NOT_INITIALIZED = 'SIGNER_NOT_INITIALIZED',
+    EXPECTED_SOLANA_SIGNER = 'SIGNER_EXPECTED_SOLANA_SIGNER',
+}
+
+/**
+ * Custom error class for signer-specific errors
+ * Extends Error with code and context properties
+ */
+export class SignerError extends Error {
+    readonly code: SignerErrorCode;
+    readonly context?: Record<string, unknown>;
+
+    constructor(code: SignerErrorCode, context?: Record<string, unknown>) {
+        const message =
+            context?.message && typeof context.message === 'string' ? context.message : `Signer error: ${code}`;
+        super(message);
+        this.name = 'SignerError';
+        this.code = code;
+        this.context = context;
+    }
+}
+
+/**
+ * Helper function to create signer-specific errors
+ */
+export function createSignerError(code: SignerErrorCode, context?: Record<string, unknown>): SignerError {
+    return new SignerError(code, context);
+}
+
+/**
+ * Helper function to throw signer-specific errors
+ */
+export function throwSignerError(code: SignerErrorCode, context?: Record<string, unknown>): never {
+    throw createSignerError(code, context);
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './errors.js';
+export * from './types.js';
+export * from './utils.js';

package/src/types.ts

@@ -0,0 +1,47 @@
+import type { Address } from '@solana/addresses';
+import type {
+    MessagePartialSigner,
+    SignableMessage,
+    SignatureDictionary,
+    TransactionPartialSigner,
+} from '@solana/signers';
+import type { Transaction, TransactionWithinSizeLimit, TransactionWithLifetime } from '@solana/transactions';
+
+/**
+ * Unified signer interface that extends both transaction and message signers.
+ * Provides both high-level (simple) and low-level (@solana/kit compatible) APIs.
+ */
+export interface SolanaSigner<TAddress extends string = string>
+    extends TransactionPartialSigner<TAddress>,
+        MessagePartialSigner<TAddress> {
+    /**
+     * Get the public key address of this signer
+     */
+    readonly address: Address<TAddress>;
+
+    /**
+     * Check if the signer is available and healthy.
+     * For remote signers (Vault, Privy, Turnkey), this performs an API health check.
+     */
+    isAvailable(): Promise<boolean>;
+
+    /**
+     * Signs multiple messages and returns signature dictionaries
+     * for @solana/kit signing compatibility.
+     *
+     * @param messages - Array of signable messages
+     * @returns Array of signature dictionaries (address -> signature mapping)
+     */
+    signMessages(messages: readonly SignableMessage[]): Promise<readonly SignatureDictionary[]>;
+
+    /**
+     * Signs multiple transactions and returns signature dictionaries.
+     * for @solana/kit signing compatibility.
+     *
+     * @param transactions - Array of transactions to sign
+     * @returns Array of signature dictionaries (address -> signature mapping)
+     */
+    signTransactions(
+        transactions: readonly (Transaction & TransactionWithinSizeLimit & TransactionWithLifetime)[],
+    ): Promise<readonly SignatureDictionary[]>;
+}

package/src/utils.ts

@@ -0,0 +1,115 @@
+import { Address, assertIsAddress } from '@solana/addresses';
+import { getBase64Encoder } from '@solana/codecs-strings';
+import { SignatureBytes } from '@solana/keys';
+import { isMessagePartialSigner, isTransactionPartialSigner, SignatureDictionary } from '@solana/signers';
+import { Base64EncodedWireTransaction, getTransactionDecoder } from '@solana/transactions';
+
+import { SignerErrorCode, throwSignerError } from './errors.js';
+import { SolanaSigner } from './types.js';
+
+interface ExtractSignatureFromWireTransactionOptions {
+    base64WireTransaction: Base64EncodedWireTransaction;
+    signerAddress: Address;
+}
+
+/**
+ * Extracts a specific signer's signature from a base64-encoded wire transaction.
+ * Useful for remote signers that return fully signed transactions from their APIs.
+ *
+ * @param base64WireTransaction - Base64 encoded transaction string
+ * @param signerAddress - The address of the signer whose signature to extract
+ * @returns SignatureDictionary with only the specified signer's signature
+ * @throws {SignerError} If no signature is found for the given address
+ *
+ * @example
+ * ```typescript
+ * // Privy API returns a signed transaction
+ * const signedTx = await privyApi.signTransaction(...);
+ * const sigDict = extractSignatureFromWireTransaction(signedTx, this.address);
+ * ```
+ */
+export function extractSignatureFromWireTransaction({
+    base64WireTransaction,
+    signerAddress,
+}: ExtractSignatureFromWireTransactionOptions): SignatureDictionary {
+    assertIsAddress(signerAddress);
+    const encoder = getBase64Encoder();
+    const decoder = getTransactionDecoder();
+    const transactionBytes = encoder.encode(base64WireTransaction);
+    const { signatures } = decoder.decode(transactionBytes);
+
+    const signature = signatures[signerAddress];
+    if (!signature) {
+        throwSignerError(SignerErrorCode.SIGNING_FAILED, {
+            address: signerAddress,
+            message: `No signature found for address ${signerAddress}`,
+        });
+    }
+
+    return createSignatureDictionary({
+        signature,
+        signerAddress,
+    });
+}
+
+interface CreateSignatureDictionaryArgs {
+    signature: SignatureBytes;
+    signerAddress: Address;
+}
+
+/**
+ * Creates a signature dictionary from a signature and signer address.
+ * @param signature - The signature to create the dictionary from
+ * @param signerAddress - The address of the signer whose signature to create the dictionary from
+ * @returns SignatureDictionary with only the specified signer's signature
+ * @throws {SignerError} If no signature is found for the given address
+ *
+ * @example
+ * ```typescript
+ * const sigDict = createSignatureDictionary({ signature, signerAddress });
+ * ```
+ */
+export function createSignatureDictionary({
+    signature,
+    signerAddress,
+}: CreateSignatureDictionaryArgs): SignatureDictionary {
+    assertIsAddress(signerAddress);
+    if (!signature) {
+        throwSignerError(SignerErrorCode.SIGNING_FAILED, {
+            address: signerAddress,
+            message: `No signature found for address ${signerAddress}`,
+        });
+    }
+    return Object.freeze({ [signerAddress]: signature });
+}
+
+/**
+ * Checks if the given value is a SolanaSigner.
+ * @param value - The value to check
+ * @returns True if the value is a SolanaSigner, false otherwise
+ */
+export function isSolanaSigner<TAddress extends string>(value: {
+    address: Address<TAddress>;
+}): value is SolanaSigner<TAddress> {
+    return (
+        'address' in value &&
+        'isAvailable' in value &&
+        isMessagePartialSigner(value) &&
+        isTransactionPartialSigner(value)
+    );
+}
+
+/**
+ * Asserts that the given value is a SolanaSigner, throwing an error if it is not.
+ * @param value - The value to check
+ * @throws {SignerError} If the value is not a SolanaSigner
+ */
+export function assertIsSolanaSigner<TAddress extends string>(value: {
+    address: Address<TAddress>;
+}): asserts value is SolanaSigner<TAddress> {
+    if (!isSolanaSigner(value)) {
+        throwSignerError(SignerErrorCode.EXPECTED_SOLANA_SIGNER, {
+            address: value.address,
+        });
+    }
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};