orbital-wallet-provider 1.0.0

package/README.md

@@ -0,0 +1,223 @@
+<div align="center">
+  <img src="logo.svg" width="80" height="80" alt="Orbital Wallet" />
+  <h1>Orbital Wallet Provider</h1>
+  <p>React provider and hooks for integrating the <a href="https://github.com/blademaster-888/radiant-orbital-wallet">Orbital Wallet</a> Chrome extension into any React or Next.js application.</p>
+  <p>Orbital Wallet is a non-custodial browser wallet for the <a href="https://radiantblockchain.org">Radiant</a> L1 blockchain with Glyph NFT support.</p>
+</div>
+
+---
+
+## Installation
+
+```bash
+npm install orbital-wallet-provider
+# or
+pnpm add orbital-wallet-provider
+```
+
+React 17+ is required as a peer dependency.
+
+---
+
+## Quick start
+
+### 1. Wrap your app with `OrbitalProvider`
+
+```tsx
+import { OrbitalProvider } from "orbital-wallet-provider"
+
+export default function App({ children }) {
+  return (
+    <OrbitalProvider>
+      {children}
+    </OrbitalProvider>
+  )
+}
+```
+
+The provider automatically detects the injected `window.orbital` object and **restores connection state on page refresh** if the site was previously authorised — no manual reconnect needed.
+
+### 2. Use the `useOrbitalWallet` hook
+
+```tsx
+import { useOrbitalWallet } from "orbital-wallet-provider"
+
+export function ConnectButton() {
+  const { isReady, isConnected, connect, disconnect, addresses, balance } = useOrbitalWallet()
+
+  if (!isReady) {
+    return (
+      <a href="https://github.com/blademaster-888/radiant-orbital-wallet" target="_blank">
+        Install Orbital Wallet
+      </a>
+    )
+  }
+
+  if (!isConnected) {
+    return <button onClick={() => connect()}>Connect Wallet</button>
+  }
+
+  return (
+    <div>
+      <p>{addresses?.rxdAddress}</p>
+      <p>{balance ? (balance.total / 1e8).toFixed(8) : "—"} RXD</p>
+      <button onClick={() => disconnect()}>Disconnect</button>
+    </div>
+  )
+}
+```
+
+---
+
+## API
+
+### `<OrbitalProvider>`
+
+Wrap your application (or any subtree that needs wallet access) with this provider. It:
+
+- Polls for `window.orbital` for up to 5 seconds after mount (the extension may inject after the page loads)
+- Calls `isConnected()` once the extension is detected — if the site was previously authorised, `isConnected` and `addresses` are restored silently without opening a popup
+- Listens for `"signedOut"` events from the extension and clears connection state accordingly
+
+### `useOrbitalWallet()`
+
+Returns the full wallet context:
+
+| Property | Type | Description |
+|---|---|---|
+| `isReady` | `boolean` | Extension detected in the page |
+| `isConnected` | `boolean` | Site is connected and authorised |
+| `pubKey` | `string \| null` | Identity public key (hex) |
+| `addresses` | `OrbitalAddresses \| null` | RXD, Glyph, and identity addresses |
+| `balance` | `RxdBalance \| null` | Confirmed + unconfirmed RXD (photons) |
+| `connect()` | `() => Promise<PubKey \| undefined>` | Request connection — opens wallet popup |
+| `disconnect()` | `() => Promise<void>` | Disconnect and clear state |
+| `getAddresses()` | `() => Promise<OrbitalAddresses \| undefined>` | Refresh addresses from extension |
+| `getBalance()` | `() => Promise<RxdBalance \| undefined>` | Refresh RXD balance |
+| `signMessage(params)` | `(SignMessageParams) => Promise<SignMessageResponse \| undefined>` | Sign a message with the RXD key |
+| `sendRxd(params)` | `(SendRxdParams[]) => Promise<SendRxdResponse[] \| undefined>` | Send RXD to one or more addresses |
+| `transferGlyphFt(params)` | `(GlyphFtParams) => Promise<GlyphFtResponse \| undefined>` | Transfer a Glyph fungible token |
+| `transferGlyphNft(params)` | `(GlyphNftParams) => Promise<GlyphNftResponse \| undefined>` | Transfer a Glyph NFT |
+| `purchaseGlyphNft(params)` | `(PurchaseGlyphNftParams) => Promise<PurchaseGlyphNftResponse \| undefined>` | Purchase a listed Glyph NFT |
+| `getSignatures(params)` | `(GetSignaturesParams) => Promise<SignatureResponse[] \| undefined>` | Sign specific inputs in a raw tx |
+| `broadcast(params)` | `(BroadcastParams) => Promise<BroadcastResponse \| undefined>` | Broadcast a fully signed raw transaction |
+| `encrypt(params)` | `(EncryptParams) => Promise<string \| undefined>` | ECIES-encrypt a message |
+| `decrypt(params)` | `(DecryptParams) => Promise<string \| undefined>` | ECIES-decrypt a ciphertext |
+| `getExchangeRate()` | `() => Promise<ExchangeRateResponse \| undefined>` | RXD/fiat exchange rate |
+| `getSocialProfile()` | `() => Promise<OrbitalSocialProfile \| undefined>` | Social profile for the connected account |
+| `on(event, handler)` | | Subscribe to a wallet event |
+| `off(event, handler)` | | Unsubscribe from a wallet event |
+
+### Key types
+
+```ts
+interface OrbitalAddresses {
+  rxdAddress:      string  // P2PKH address — used for RXD payments and signing
+  glyphAddress:    string  // Address for Glyph NFT/FT operations
+  identityAddress: string  // Identity derivation address
+}
+
+interface RxdBalance {
+  confirmed:   number  // photons (1 RXD = 100_000_000 photons)
+  unconfirmed: number
+  total:       number
+}
+
+interface SignMessageResponse {
+  sig:     string  // base64 Bitcoin-style signed message
+  address: string  // RXD address that produced the signature
+  pubKey:  string  // hex-encoded compressed public key
+}
+```
+
+### Events
+
+| Event | Fired when |
+|---|---|
+| `"signedOut"` | User locks the wallet or signs out |
+| `"connect"` | Site connection approved |
+| `"disconnect"` | Site disconnected from wallet |
+
+### `OrbitalIcon`
+
+Inline SVG of the Orbital Wallet logo — useful for connect buttons and nav bars.
+
+```tsx
+import { OrbitalIcon } from "orbital-wallet-provider"
+
+// defaults: size="24px", color="currentColor"
+<OrbitalIcon size="32px" color="#00d4ff" />
+```
+
+### Utility helpers
+
+```ts
+import {
+  photonsToRxd,
+  rxdToPhotons,
+  formatRxd,
+  formatToken,
+  truncateAddress,
+  glyphExplorerUrl,
+  explorerTxUrl,
+  isValidRxdAddress,
+} from "orbital-wallet-provider"
+
+photonsToRxd(100_000_000)           // → 1
+rxdToPhotons(1)                     // → 100000000
+formatRxd(100_000_000)              // → "1.00000000 RXD"
+formatToken(1000000, "BNET", 0)     // → "1,000,000 BNET"
+truncateAddress("1AbCdEfGhIjKlMn")  // → "1AbCdE…lMn"
+isValidRxdAddress("1AbC...")        // → true / false
+```
+
+---
+
+## Sign-in pattern (wallet authentication)
+
+Prove wallet ownership to a backend using a Bitcoin-style signed message. `signMessage` always uses the **RXD key** (`addresses.rxdAddress`) so the address you register with the backend matches the address shown to the user in the wallet.
+
+```tsx
+import { useOrbitalWallet } from "orbital-wallet-provider"
+
+const { signMessage, addresses } = useOrbitalWallet()
+
+async function signIn() {
+  // 1. Request a nonce from your backend for the user's RXD address
+  const { nonce, message } = await fetch("/api/auth/nonce", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ address: addresses?.rxdAddress }),
+  }).then(r => r.json())
+
+  // 2. Ask the wallet to sign — opens the Orbital Wallet popup
+  //    Returns undefined if the user cancels
+  const signed = await signMessage({ message })
+  if (!signed) throw new Error("Sign-in cancelled")
+
+  // 3. Verify on your backend
+  //    signed.address is the RXD address that produced the signature
+  //    signed.sig     is a base64 Bitcoin Signed Message (65 bytes)
+  //    signed.pubKey  is the hex-encoded compressed public key
+  const { token } = await fetch("/api/auth/verify", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      address:   signed.address,
+      message,
+      nonce,
+      signature: signed.sig,
+    }),
+  }).then(r => r.json())
+
+  return token
+}
+```
+
+> **Backend verification**: the signature is a standard Bitcoin Signed Message. Use `coincurve`, `bitcoinjs-message`, or any BSM-compatible library on the server. The message is hashed as `SHA256d("Bitcoin Signed Message:\n" + varint(len) + message)` and the signature is 65 bytes: `[recovery_flag][r][s]`.
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,264 @@
+import React from 'react';
+
+/** Satoshi-equivalent unit on Radiant. 1 RXD = 100_000_000 photons */
+type Photons = number;
+/** A Radiant P2PKH address string */
+type RxdAddress = string;
+/** Hex-encoded public key */
+type PubKey = string;
+/** Hex-encoded raw transaction */
+type RawTx = string;
+/** Hex-encoded transaction ID */
+type TxID = string;
+/** Glyph token contract reference (20-byte hex string) */
+type GlyphRef = string;
+interface OrbitalAddresses {
+    rxdAddress: RxdAddress;
+    glyphAddress: RxdAddress;
+    identityAddress: RxdAddress;
+}
+interface RxdBalance {
+    confirmed: Photons;
+    unconfirmed: Photons;
+    total: Photons;
+}
+interface SendRxdParams {
+    address: RxdAddress;
+    satoshis: Photons;
+}
+interface SendRxdResponse {
+    txid: TxID;
+    rawtx: RawTx;
+}
+interface GlyphFtParams {
+    tokenRef: GlyphRef;
+    address: RxdAddress;
+    amount: number;
+}
+interface GlyphFtResponse {
+    txid: TxID;
+    rawtx: RawTx;
+}
+interface GlyphNftParams {
+    tokenRef: GlyphRef;
+    address: RxdAddress;
+}
+interface GlyphNftResponse {
+    txid: TxID;
+    rawtx: RawTx;
+}
+interface PurchaseGlyphNftParams {
+    listingTxid: TxID;
+    priceSatoshis: Photons;
+    sellerAddress: RxdAddress;
+}
+interface PurchaseGlyphNftResponse {
+    txid: TxID;
+    rawtx: RawTx;
+}
+interface SignMessageParams {
+    message: string;
+    address?: RxdAddress;
+}
+interface SignMessageResponse {
+    sig: string;
+    address: RxdAddress;
+    pubKey: PubKey;
+}
+interface SignatureRequest {
+    prevTxid: TxID;
+    outputIndex: number;
+    inputIndex: number;
+    satoshis: Photons;
+    address: RxdAddress;
+    script: string;
+    sigHashType: number;
+    csIdx?: number;
+    data?: Record<string, unknown>;
+}
+interface SignatureResponse {
+    sig: string;
+    pubKey: PubKey;
+    sigHashType: number;
+    csIdx?: number;
+    data?: Record<string, unknown>;
+}
+interface GetSignaturesParams {
+    rawtx: RawTx;
+    sigRequests: SignatureRequest[];
+}
+interface BroadcastParams {
+    rawtx: RawTx;
+}
+interface BroadcastResponse {
+    txid: TxID;
+}
+interface EncryptParams {
+    message: string;
+    pubKey: PubKey;
+}
+interface DecryptParams {
+    ciphertext: string;
+}
+interface ExchangeRateResponse {
+    currency: string;
+    rate: number;
+}
+interface OrbitalSocialProfile {
+    displayName?: string;
+    avatar?: string;
+    idAddress?: RxdAddress;
+}
+type OrbitalWalletEventName = "signedOut" | "connect" | "disconnect";
+type OrbitalWalletEventHandler = () => void;
+interface OrbitalWalletProvider {
+    isReady: boolean;
+    isConnected: () => Promise<boolean>;
+    connect: () => Promise<PubKey | undefined>;
+    disconnect: () => Promise<void>;
+    getAddresses: () => Promise<OrbitalAddresses | undefined>;
+    getBalance: () => Promise<RxdBalance | undefined>;
+    sendRxd: (params: SendRxdParams[]) => Promise<SendRxdResponse[] | undefined>;
+    transferGlyphFt: (params: GlyphFtParams) => Promise<GlyphFtResponse | undefined>;
+    transferGlyphNft: (params: GlyphNftParams) => Promise<GlyphNftResponse | undefined>;
+    purchaseGlyphNft: (params: PurchaseGlyphNftParams) => Promise<PurchaseGlyphNftResponse | undefined>;
+    signMessage: (params: SignMessageParams) => Promise<SignMessageResponse | undefined>;
+    getSignatures: (params: GetSignaturesParams) => Promise<SignatureResponse[] | undefined>;
+    broadcast: (params: BroadcastParams) => Promise<BroadcastResponse | undefined>;
+    encrypt: (params: EncryptParams) => Promise<string | undefined>;
+    decrypt: (params: DecryptParams) => Promise<string | undefined>;
+    getExchangeRate: () => Promise<ExchangeRateResponse | undefined>;
+    getSocialProfile: () => Promise<OrbitalSocialProfile | undefined>;
+    on: (event: OrbitalWalletEventName, handler: OrbitalWalletEventHandler) => void;
+    off: (event: OrbitalWalletEventName, handler: OrbitalWalletEventHandler) => void;
+}
+declare global {
+    interface Window {
+        orbital?: OrbitalWalletProvider;
+    }
+}
+
+interface OrbitalWalletContextState {
+    /**
+     * True when the Orbital Wallet extension is installed and unlocked.
+     * Check this before calling connect().
+     */
+    isReady: boolean;
+    /**
+     * True when the user has actively connected this site in the wallet.
+     */
+    isConnected: boolean;
+    /**
+     * The identity public key returned by connect(), null when not connected.
+     */
+    pubKey: PubKey | null;
+    /**
+     * Addresses for the connected account, null when not connected.
+     */
+    addresses: OrbitalAddresses | null;
+    /**
+     * Confirmed + unconfirmed RXD balance, null when not connected.
+     */
+    balance: RxdBalance | null;
+    /** Request connection. Opens the Orbital Wallet popup. */
+    connect: () => Promise<PubKey | undefined>;
+    /** Disconnect this site from the wallet. */
+    disconnect: () => Promise<void>;
+    /** Refresh addresses from the wallet. */
+    getAddresses: () => Promise<OrbitalAddresses | undefined>;
+    /** Refresh balance from the wallet. */
+    getBalance: () => Promise<RxdBalance | undefined>;
+    /** Send RXD to one or more recipients. */
+    sendRxd: (params: SendRxdParams[]) => Promise<SendRxdResponse[] | undefined>;
+    /** Transfer a Glyph fungible token (FT/BNET/etc). */
+    transferGlyphFt: (params: GlyphFtParams) => Promise<GlyphFtResponse | undefined>;
+    /** Transfer a Glyph NFT. */
+    transferGlyphNft: (params: GlyphNftParams) => Promise<GlyphNftResponse | undefined>;
+    /** Purchase a listed Glyph NFT from a P2P listing. */
+    purchaseGlyphNft: (params: PurchaseGlyphNftParams) => Promise<PurchaseGlyphNftResponse | undefined>;
+    /** Sign a human-readable message. */
+    signMessage: (params: SignMessageParams) => Promise<SignMessageResponse | undefined>;
+    /** Sign specific inputs in a raw tx (PSBT-style). */
+    getSignatures: (params: GetSignaturesParams) => Promise<SignatureResponse[] | undefined>;
+    /** Broadcast a fully signed raw transaction. */
+    broadcast: (params: BroadcastParams) => Promise<BroadcastResponse | undefined>;
+    /** ECIES-encrypt a message to a public key. */
+    encrypt: (params: EncryptParams) => Promise<string | undefined>;
+    /** ECIES-decrypt a ciphertext with the wallet private key. */
+    decrypt: (params: DecryptParams) => Promise<string | undefined>;
+    /** Get the current RXD/fiat exchange rate. */
+    getExchangeRate: () => Promise<ExchangeRateResponse | undefined>;
+    /** Get social/profile info for the connected account. */
+    getSocialProfile: () => Promise<OrbitalSocialProfile | undefined>;
+    /** Register an event listener on the wallet. */
+    on: (event: OrbitalWalletEventName, handler: OrbitalWalletEventHandler) => void;
+    /** Remove an event listener from the wallet. */
+    off: (event: OrbitalWalletEventName, handler: OrbitalWalletEventHandler) => void;
+}
+interface OrbitalProviderProps {
+    children: React.ReactNode;
+}
+declare const OrbitalProvider: React.FC<OrbitalProviderProps>;
+/**
+ * useOrbitalWallet — access the connected Orbital Wallet state and methods.
+ *
+ * Must be used inside <OrbitalProvider>.
+ *
+ * @example
+ * const { isReady, connect, balance, transferGlyphFt } = useOrbitalWallet();
+ */
+declare const useOrbitalWallet: () => OrbitalWalletContextState;
+
+interface OrbitalIconProps {
+    size?: string | number;
+    color?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * OrbitalIcon — the Orbital Wallet logo as an inline SVG.
+ * Drop-in replacement for YoursIcon from yours-wallet-provider.
+ *
+ * @example
+ * <OrbitalIcon size="32px" color="#00d4ff" />
+ */
+declare const OrbitalIcon: React.FC<OrbitalIconProps>;
+
+/**
+ * orbital-wallet-provider — utils.ts
+ * Helper functions for working with Radiant/Glyph values.
+ */
+/** Convert photons (base unit) to RXD */
+declare const photonsToRxd: (photons: number) => number;
+/** Convert RXD to photons */
+declare const rxdToPhotons: (rxd: number) => number;
+/**
+ * Format a photon amount as a human-readable RXD string.
+ * e.g. formatRxd(100000000) → "1.00000000 RXD"
+ */
+declare const formatRxd: (photons: number, decimals?: number) => string;
+/**
+ * Format a Glyph token amount using its decimals.
+ * e.g. formatToken(1000000, "BNET", 0) → "1000000 BNET"
+ */
+declare const formatToken: (amount: number, ticker: string, decimals?: number) => string;
+/**
+ * Truncate a Radiant address for display.
+ * e.g. "1AbCd...xYz9"
+ */
+declare const truncateAddress: (address: string, prefixLen?: number, suffixLen?: number) => string;
+/**
+ * Returns the Glyph explorer URL for a given token ref.
+ */
+declare const glyphExplorerUrl: (ref: string) => string;
+/**
+ * Returns the block explorer TX URL.
+ */
+declare const explorerTxUrl: (txid: string) => string;
+/**
+ * Validate a Radiant P2PKH address (basic check).
+ * Radiant addresses start with '1' (mainnet).
+ */
+declare const isValidRxdAddress: (address: string) => boolean;
+
+export { type BroadcastParams, type BroadcastResponse, type DecryptParams, type EncryptParams, type ExchangeRateResponse, type GetSignaturesParams, type GlyphFtParams, type GlyphFtResponse, type GlyphNftParams, type GlyphNftResponse, type GlyphRef, type OrbitalAddresses, OrbitalIcon, type OrbitalIconProps, OrbitalProvider, type OrbitalProviderProps, type OrbitalSocialProfile, type OrbitalWalletContextState, type OrbitalWalletEventHandler, type OrbitalWalletEventName, type OrbitalWalletProvider, type Photons, type PubKey, type PurchaseGlyphNftParams, type PurchaseGlyphNftResponse, type RawTx, type RxdAddress, type RxdBalance, type SendRxdParams, type SendRxdResponse, type SignMessageParams, type SignMessageResponse, type SignatureRequest, type SignatureResponse, type TxID, explorerTxUrl, formatRxd, formatToken, glyphExplorerUrl, isValidRxdAddress, photonsToRxd, rxdToPhotons, truncateAddress, useOrbitalWallet };