@kingdomchain/wallet-client 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# Kingdom Chain TypeScript / CosmJS client
+
+Self-contained TypeScript package for constructing, signing, and broadcasting Kingdom Chain transactions via [CosmJS](https://github.com/cosmos/cosm-js). Includes a Keplr/Leap browser wallet connector for non-custodial signing.
+
+## Scope (current)
+
+- **MsgSubmitApplication** (citizenship application)
+- **MsgSubmitRecoveryAttestation** (wallet recovery attestation)
+- **Browser wallet connector** (`src/browserSigner.ts`) — Keplr / Leap via `experimentalSuggestChain` + `OfflineDirectSigner`
+- Ed25519 attestation signing ported from `x/compliance/types/attestation.go`
+- Proto codegen via `ts-proto` + `buf`
+
+## Setup
+
+```bash
+cd clients/ts
+npm install
+npm run codegen   # regenerate from ../../proto (requires buf + repo root)
+```
+
+## Testing
+
+```bash
+cd clients/ts
+npm test              # unit + property fuzz (1500 cross-lang iterations)
+npm run test:mutate   # Stryker mutation testing on attestation.ts + registry.ts
+```
+
+Cross-language fuzz compares TS `attestationSignPayload` against a compiled Go helper (`payload_attestation.go`) for 1000 citizenship + 500 recovery inputs.
+
+## Live E2E (Ona devnet)
+
+Requires a running node at `~/.kingdomchain-e2e` (see `scripts/citizen-compliance-e2e/run.sh`).
+
+```bash
+# Build CLI if needed
+go build -o /tmp/kingdomchaind ./cmd/kingdomchaind
+
+cd clients/ts
+npm run e2e:submit-application
+npm run e2e:submit-recovery
+```
+
+Environment overrides:
+
+| Variable | Default |
+|----------|---------|
+| `CHAIN_ID` | `kingdomchain-e2e` |
+| `RPC_URL` | `http://127.0.0.1:26657` |
+| `REST_URL` | `http://127.0.0.1:1317` |
+| `HOME_DIR` | `~/.kingdomchain-e2e` |
+| `KINGDOMCHAIND` | `/tmp/kingdomchaind` |
+| `PROVIDER_SEED_HEX` | devnet provider-alpha seed from e2e script |
+
+## Browser wallet demo (Keplr / Leap)
+
+Manual click-through demo for Isa — **not automated in CI**. Unit tests mock `window.keplr` / `window.leap`; the demo requires a real extension in your browser.
+
+1. Start the Ona devnet (`scripts/citizen-compliance-e2e/run.sh` or your existing node).
+2. Fund the Keplr/Leap account you will connect with (`ukdr` on `kingdomchain-e2e`).
+3. From `clients/ts`:
+
+```bash
+npm run demo
+```
+
+4. Open the printed URL (default `http://localhost:5173`) in a browser with Keplr or Leap installed.
+5. Click **Connect Keplr** or **Connect Leap**, approve the chain suggestion + connection, then **Submit test application**.
+
+Optional Vite env overrides (prefix `VITE_`):
+
+| Variable | Default |
+|----------|---------|
+| `VITE_CHAIN_ID` | `kingdomchain-e2e` |
+| `VITE_RPC_URL` | `http://127.0.0.1:26657` |
+| `VITE_REST_URL` | `http://127.0.0.1:1317` |
+| `VITE_PROVIDER_ID` | `provider-alpha` |
+| `VITE_POLICY_VERSION` | `policy-v1` |
+| `VITE_PROVIDER_SEED_HEX` | devnet provider-alpha seed |
+
+The demo signs the provider attestation off-chain (devnet seed) and broadcasts `MsgSubmitApplication` using your connected wallet as the on-chain tx signer.
+
+### Browser wallet API (`src/browserSigner.ts`)
+
+- `isKeplrAvailable()` / `isLeapAvailable()`
+- `buildKingdomChainInfo(chainId, rpcUrl, restUrl)` — `ukdr` / KDR with **6 decimals** (`x/supply/types/constants.go`, `TOKENOMICS_COSMOS_SPEC.md`), bech32 prefix `king`, coin type 118
+- `connectKeplr(chainInfo)` / `connectLeap(chainInfo)` — suggest chain + enable + offline signer
+- `createBrowserSigningClient(rpcUrl, signer)` — `SigningStargateClient` + `createKingdomChainRegistry()`
+
+## Encoding notes (for Base44 frontend)
+
+1. **Custom protobuf registry** — CosmJS `SigningStargateClient` must be constructed with a `Registry` that includes Kingdom Chain message type URLs (e.g. `/isatheword.kingdomchain.compliance.v1.MsgSubmitApplication`) alongside `defaultRegistryTypes`.
+2. **Attestation signing is off-chain** — providers sign a canonical SHA256-payload (not the tx bytes). The TS port in `src/attestation.ts` must match Go `AttestationSignPayload` exactly; the E2E script cross-checks against `scripts/citizen-compliance-e2e/sign_attestation.go`.
+3. **Timestamps** — proto `google.protobuf.Timestamp` fields (`issued_at`, `expires_at`) are `Date` in generated TS; encoding uses `@bufbuild/protobuf` wire format.
+4. **Uint64 fields** — `provider_key_version` is `bigint` in generated types.
+5. **Tx signer** — `MsgSubmitApplication` signer is `applicant_wallet`; the fee payer / signer must be the applicant's secp256k1 account (`king` bech32 prefix, coin type 118).

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import { Registry, OfflineDirectSigner, EncodeObject } from '@cosmjs/proto-signing';
+import { SigningStargateClient } from '@cosmjs/stargate';
+import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
+
+/** Must match x/compliance/types/keys.go AttestationTypeCitizenshipApplication */
+declare const ATTESTATION_TYPE_CITIZENSHIP_APPLICATION = "citizenship_application";
+/** Must match x/compliance/types/keys.go AttestationTypeRecovery */
+declare const ATTESTATION_TYPE_RECOVERY = "recovery";
+interface AttestationPayloadInput {
+    attestationType: string;
+    chainId: string;
+    intendedWallet: string;
+    caseId: string;
+    policyVersion: string;
+    nonce: string;
+    uniquenessReference: string;
+    issuedAt: Date;
+    expiresAt: Date;
+    providerId: string;
+    providerKeyVersion: bigint;
+    citizenId?: bigint;
+    oldWallet?: string;
+    newWallet?: string;
+}
+/**
+ * Canonical attestation payload — must match Go types.AttestationSignPayload bit-for-bit.
+ */
+declare function attestationSignPayload(input: AttestationPayloadInput): string;
+declare function signAttestationPayload(privateKeySeed: Uint8Array, payload: string): Promise<string>;
+declare function publicKeyFromPrivateSeed(privateKeySeed: Uint8Array): Promise<string>;
+declare function providerSeedFromHex(hex: string): Uint8Array;
+
+interface MsgSubmitApplication {
+    applicant_wallet: string;
+    application_id: string;
+    provider_id: string;
+    provider_key_version: bigint;
+    chain_id: string;
+    case_id: string;
+    policy_version: string;
+    nonce: string;
+    uniqueness_reference: string;
+    issued_at?: Date | undefined;
+    expires_at?: Date | undefined;
+    signature: string;
+}
+declare const MsgSubmitApplication: MessageFns<MsgSubmitApplication>;
+interface MsgSubmitRecoveryAttestation {
+    applicant_wallet: string;
+    recovery_case_id: string;
+    provider_id: string;
+    provider_key_version: bigint;
+    chain_id: string;
+    case_id: string;
+    policy_version: string;
+    nonce: string;
+    uniqueness_reference: string;
+    citizen_id: bigint;
+    old_wallet: string;
+    new_wallet: string;
+    issued_at?: Date | undefined;
+    expires_at?: Date | undefined;
+    signature: string;
+}
+declare const MsgSubmitRecoveryAttestation: MessageFns<MsgSubmitRecoveryAttestation>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | bigint | undefined;
+type DeepPartial<T> = T extends bigint ? string | number | bigint : T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    create(base?: DeepPartial<T>): T;
+    fromPartial(object: DeepPartial<T>): T;
+}
+
+declare enum ApplicationStatus {
+    APPLICATION_STATUS_UNSPECIFIED = 0,
+    APPLICATION_STATUS_SUBMITTED = 1,
+    APPLICATION_STATUS_PENDING_REVIEW = 2,
+    APPLICATION_STATUS_APPROVED = 3,
+    APPLICATION_STATUS_REJECTED = 4,
+    UNRECOGNIZED = -1
+}
+declare enum RecoveryAttestationStatus {
+    RECOVERY_ATTESTATION_STATUS_UNSPECIFIED = 0,
+    RECOVERY_ATTESTATION_STATUS_SUBMITTED = 1,
+    RECOVERY_ATTESTATION_STATUS_PENDING_REVIEW = 2,
+    RECOVERY_ATTESTATION_STATUS_APPROVED = 3,
+    RECOVERY_ATTESTATION_STATUS_REJECTED = 4,
+    UNRECOGNIZED = -1
+}
+
+/** CosmJS registry: standard Cosmos SDK types + Kingdom Chain citizen/compliance messages. */
+declare function createKingdomChainRegistry(): Registry;
+
+/** Keplr/Leap-compatible currency entry. */
+interface ChainCurrency {
+    coinDenom: string;
+    coinMinimalDenom: string;
+    coinDecimals: number;
+    gasPriceStep?: {
+        low: number;
+        average: number;
+        high: number;
+    };
+}
+/** Keplr/Leap-compatible ChainInfo for experimentalSuggestChain. */
+interface ChainInfo {
+    chainId: string;
+    chainName: string;
+    rpc: string;
+    rest: string;
+    bip44: {
+        coinType: number;
+    };
+    bech32Config: {
+        bech32PrefixAccAddr: string;
+        bech32PrefixAccPub: string;
+        bech32PrefixValAddr: string;
+        bech32PrefixValPub: string;
+        bech32PrefixConsAddr: string;
+        bech32PrefixConsPub: string;
+    };
+    currencies: ChainCurrency[];
+    feeCurrencies: ChainCurrency[];
+    stakeCurrency: ChainCurrency;
+}
+/** Subset of Keplr/Leap window API used for chain connect. */
+interface BrowserWalletApi {
+    experimentalSuggestChain(chainInfo: ChainInfo): Promise<void>;
+    enable(chainId: string): Promise<void>;
+    getOfflineSigner(chainId: string): OfflineDirectSigner;
+}
+declare class WalletNotInstalledError extends Error {
+    readonly walletName: string;
+    constructor(walletName: string);
+}
+declare class WalletConnectionError extends Error {
+    readonly walletName: string;
+    readonly step: "suggestChain" | "enable" | "getOfflineSigner";
+    constructor(walletName: string, step: "suggestChain" | "enable" | "getOfflineSigner", cause?: unknown);
+}
+/** @deprecated Use WalletConnectionError — kept for backward compatibility in tests/demo. */
+declare class WalletConnectionRejectedError extends WalletConnectionError {
+    constructor(walletName: string, step: "suggestChain" | "enable", cause?: unknown);
+}
+declare class WalletAccountError extends Error {
+    readonly walletName: string;
+    constructor(walletName: string);
+}
+declare class InvalidChainConfigError extends Error {
+    constructor(message: string);
+}
+declare class RpcConnectionError extends Error {
+    readonly rpcUrl: string;
+    constructor(rpcUrl: string, cause?: unknown);
+}
+declare global {
+    interface Window {
+        keplr?: BrowserWalletApi;
+        leap?: BrowserWalletApi;
+    }
+}
+/** Validate chain endpoint inputs before passing to Keplr/Leap. */
+declare function validateChainConfig(chainId: string, rpcUrl: string, restUrl: string): void;
+declare function isKeplrAvailable(): boolean;
+declare function isLeapAvailable(): boolean;
+/** Build ChainInfo for Keplr/Leap experimentalSuggestChain. */
+declare function buildKingdomChainInfo(chainId: string, rpcUrl: string, restUrl: string, chainName?: string): ChainInfo;
+/** Suggest chain, request access, return CosmJS OfflineDirectSigner. */
+declare function suggestAndConnect(walletApi: BrowserWalletApi, chainInfo: ChainInfo, walletName?: string): Promise<OfflineDirectSigner>;
+declare function connectKeplr(chainInfo: ChainInfo): Promise<OfflineDirectSigner>;
+declare function connectLeap(chainInfo: ChainInfo): Promise<OfflineDirectSigner>;
+/** SigningStargateClient wired with Kingdom Chain custom message registry. */
+declare function createBrowserSigningClient(rpcUrl: string, signer: OfflineDirectSigner): Promise<SigningStargateClient>;
+
+/**
+ * Kingdom Chain on-chain denom and display metadata.
+ *
+ * Sources:
+ * - x/supply/types/constants.go (UkdrDenom = "ukdr")
+ * - TOKENOMICS_COSMOS_SPEC.md (1 KDR = 1,000,000 ukdr)
+ * - app/app.go + app/config.go (bech32 prefix, coin type)
+ */
+/** Base (minimal) denom registered in x/supply. */
+declare const UKDR_MINIMAL_DENOM = "ukdr";
+/** Human-readable display symbol. */
+declare const UKDR_DISPLAY_DENOM = "KDR";
+/** ukdr is a micro-unit: 10^6 ukdr = 1 KDR. */
+declare const UKDR_DECIMALS = 6;
+/** Account / validator bech32 prefix (AccountAddressPrefix in app/app.go). */
+declare const BECH32_PREFIX = "king";
+/** SLIP-0044 coin type (ChainCoinType in app/app.go). */
+declare const CHAIN_COIN_TYPE = 118;
+/** Devnet default chain ID (override via env when a permanent node exists). */
+declare const DEFAULT_CHAIN_ID = "kingdomchain-e2e";
+declare const DEFAULT_RPC_URL = "http://127.0.0.1:26657";
+declare const DEFAULT_REST_URL = "http://127.0.0.1:1317";
+
+interface SubmitApplicationParams {
+    applicantWallet: string;
+    applicationId: string;
+    chainId: string;
+    providerId: string;
+    policyVersion: string;
+    providerSeedHex: string;
+    nonce: string;
+    uniquenessReference: string;
+    issuedAt: Date;
+    expiresAt: Date;
+    providerKeyVersion?: bigint;
+}
+declare function buildSubmitApplicationMsg(applicantWallet: string, applicationId: string, attestationInput: AttestationPayloadInput, signature: string): EncodeObject;
+declare function signCitizenshipAttestation(params: SubmitApplicationParams): Promise<{
+    signature: string;
+    input: AttestationPayloadInput;
+}>;
+
+export { ATTESTATION_TYPE_CITIZENSHIP_APPLICATION, ATTESTATION_TYPE_RECOVERY, ApplicationStatus, type AttestationPayloadInput, BECH32_PREFIX, type BrowserWalletApi, CHAIN_COIN_TYPE, type ChainCurrency, type ChainInfo, DEFAULT_CHAIN_ID, DEFAULT_REST_URL, DEFAULT_RPC_URL, InvalidChainConfigError, MsgSubmitApplication, MsgSubmitRecoveryAttestation, RecoveryAttestationStatus, RpcConnectionError, type SubmitApplicationParams, UKDR_DECIMALS, UKDR_DISPLAY_DENOM, UKDR_MINIMAL_DENOM, WalletAccountError, WalletConnectionError, WalletConnectionRejectedError, WalletNotInstalledError, attestationSignPayload, buildKingdomChainInfo, buildSubmitApplicationMsg, connectKeplr, connectLeap, createBrowserSigningClient, createKingdomChainRegistry, isKeplrAvailable, isLeapAvailable, providerSeedFromHex, publicKeyFromPrivateSeed, signAttestationPayload, signCitizenshipAttestation, suggestAndConnect, validateChainConfig };