feat(ts): unified createSigner factory, config union, and resolveAddress

[amilz]

Some helpers for our @solana/keychain umprella package for projects that plan to enable many signers.

Summary

• Export createSigner(config) — unified factory that dispatches to the correct backend based on a backend discriminant field
• Export KeychainSignerConfig discriminated union type and BackendName string literal union for config management
• Export resolveAddress(config) — lightweight address lookup that skips full signer init for backends with the public key in config
• Flat re-export all 10 individual config types from the umbrella package

Motivated by jup-ag/cli#13 where consumers hand-roll the same dispatch logic.

Before (what consumers build today)

// Every consumer writes this same registry...
type KeychainBackend = 'aws-kms' | 'cdp' | 'crossmint' | 'dfns' | 'fireblocks' | ...;

const BACKEND_REGISTRY: Record<KeychainBackend, BackendDef> = {
    'aws-kms': {
        requiredParams: ['keyId', 'publicKey'],
        create: async (params) => {
            const { createAwsKmsSigner } = await import('@solana/keychain-aws-kms');
            return createAwsKmsSigner({ keyId: params.keyId, publicKey: params.publicKey });
        },
    },
    privy: {
        requiredParams: ['appId', 'walletId'],
        create: async (params) => {
            const { createPrivySigner } = await import('@solana/keychain-privy');
            return createPrivySigner({ appId: params.appId, ... });
        },
    },
    // ...repeat for every backend
};

export async function createKeychainSigner(config: KeychainConfig): Promise<SolanaSigner> {
    const def = BACKEND_REGISTRY[config.backend];
    return def.create(config.params);
}

After

import { createSigner, resolveAddress } from '@solana/keychain';

// Create any signer‚ one function, fully typed
const signer = await createSigner({
    backend: 'privy',
    appId: 'your-app-id',
    appSecret: 'your-app-secret',
    walletId: 'your-wallet-id',
});

// Get address without full signer init (instant for config-based backends)
const address = await resolveAddress({
    backend: 'vault',
    vaultAddr: 'https://vault.example.com',
    vaultToken: 'hvs.xxx',
    keyName: 'my-key',
    publicKey: '4Nd1m...',
});

Config management

import type { KeychainSignerConfig, BackendName } from '@solana/keychain';

// Store configs as JSON — the backend field is the discriminant
const configs: KeychainSignerConfig[] = JSON.parse(readFileSync('signers.json', 'utf-8'));

// Type narrows automatically in switch/if blocks
for (const config of configs) {
    if (config.backend === 'fireblocks') {
        console.log(config.vaultAccountId); // TS knows this field exists
    }
}

Test plan

• 44 unit tests (table-driven across all 10 backends) for createSigner and resolveAddress
• pnpm run build — clean
• pnpm run lint — clean
• pnpm run typecheck — clean
• agadoo treeshakability — passes
• Exhaustive never check in default branches — compile-time failure if a backend is added to the union but not handled

Closes TOO-240, TOO-241, TOO-242

[linear]

TOO-240 Export unified `createSigner(type, config)` factory from umbrella package

TOO-241 Export unified `KeychainSignerConfig` discriminated union type

TOO-242 Add lightweight `resolveAddress(config)` for async signers

[greptile-apps]

Greptile Summary

This PR adds three new exports to the @solana/keychain umbrella package: a unified createSigner(config) factory, a lightweight resolveAddress(config) helper, and the KeychainSignerConfig / BackendName types — eliminating the boilerplate dispatch logic consumers were writing by hand (see jup-ag/cli#13). All 10 backends are covered, flat config-type re-exports are added, and 44 table-driven unit tests validate dispatch, config stripping, error propagation, and address resolution.\n\nKey changes:\n- src/types.ts — KeychainSignerConfig discriminated union (XxxSignerConfig & { backend: '...' }) and derived BackendName string literal union; no conflicts with pre-existing config fields.\n- src/create-signer.ts — exhaustive switch with compile-time never guard in the default branch; stripBackend helper cleanly removes the discriminant before forwarding to each factory.\n- src/resolve-address.ts — short-circuits synchronously for the five config-backed backends (aws-kms, gcp-kms, turnkey, vault, cdp) using assertIsAddress for runtime validation; delegates to createSigner for the five API-backed backends.\n- src/index.ts — flat re-exports for all 10 individual config types alongside the new entry points.\n- package.json — @solana/addresses correctly added as a runtime dependency (needed for assertIsAddress); test script now runs vitest before typecheck.\n- README.md — updated to reflect the new recommended factory-first usage pattern.

Confidence Score: 5/5

Safe to merge — all remaining findings are P2 style/test-hygiene suggestions with no impact on runtime correctness.

The core logic is sound: the discriminated union has no field conflicts, the exhaustive switch provides compile-time coverage, and assertIsAddress guards runtime address validity. Both findings are P2 — a missing beforeEach reset in one test file (tests still pass due to deterministic ordering) and inconsistent await usage that has no behavioral difference without a surrounding try/catch.

typescript/packages/keychain/src/tests/resolve-address.test.ts — missing mock reset could make tests fragile if reordered.

Important Files Changed

Filename	Overview
typescript/packages/keychain/src/create-signer.ts	New unified factory dispatching to all 10 backend factories via a discriminated switch; exhaustive never-check in default branch; minor await consistency concern (P2)
typescript/packages/keychain/src/resolve-address.ts	New address-resolver that short-circuits for config-held addresses (aws-kms, gcp-kms, turnkey, vault, cdp) and delegates to createSigner for API-backed backends; runtime assertIsAddress validation present
typescript/packages/keychain/src/types.ts	Clean discriminated union of all 10 backend config types; BackendName derived correctly; no conflicts with existing config type fields
typescript/packages/keychain/src/tests/resolve-address.test.ts	Table-driven tests cover all backends; missing beforeEach mock reset makes not.toHaveBeenCalled assertions order-dependent (P2)
typescript/packages/keychain/src/tests/create-signer.test.ts	Thorough table-driven tests with beforeEach mock reset; verifies dispatch, config stripping, error propagation, and unknown-backend error code
typescript/packages/keychain/src/index.ts	New flat re-exports for all 10 individual config types and the two new entry points; no naming collisions observed
typescript/packages/keychain/package.json	Adds @solana/addresses runtime dependency (correct — assertIsAddress is used at runtime); test script now runs vitest before typecheck

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["createSigner(config)\nor resolveAddress(config)"] --> B{config.backend}

    B -->|aws-kms| C1["resolveAddress: return config.publicKey\ncreateAwsKmsSigner(stripBackend)"]
    B -->|gcp-kms| C2["resolveAddress: return config.publicKey\ncreateGcpKmsSigner(stripBackend)"]
    B -->|turnkey| C3["resolveAddress: return config.publicKey\ncreateTurnkeySigner(stripBackend)"]
    B -->|vault| C4["resolveAddress: return config.publicKey\ncreateVaultSigner(stripBackend)"]
    B -->|cdp| C5["resolveAddress: return config.address\ncreateCdpSigner(stripBackend)"]

    B -->|crossmint| D1["createCrossmintSigner → signer.address"]
    B -->|dfns| D2["createDfnsSigner → signer.address"]
    B -->|fireblocks| D3["createFireblocksSigner → signer.address"]
    B -->|para| D4["createParaSigner → signer.address"]
    B -->|privy| D5["createPrivySigner → signer.address"]

    B -->|unknown| E["throwSignerError(CONFIG_ERROR)"]

    subgraph Sync["Sync — address in config (no network call)"]
        C1
        C2
        C3
        C4
        C5
    end

    subgraph Async["Async — address fetched from remote API"]
        D1
        D2
        D3
        D4
        D5
    end

Loading

_{Reviews (1): Last reviewed commit: "docs(ts): update @solana/keychain README..." | Re-trigger Greptile}

The base branch was changed.