@onekeyfe/hardware-cli 1.1.25-alpha.0

package/skills/signing/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: hardware-signing
+description: Multi-chain address generation and transaction signing using OneKey
+  hardware wallet. Use whenever the user wants to get a receive address, sign
+  a transaction, sign a message, or verify an address on any supported blockchain.
+  All signing operations require physical confirmation on the hardware device.
+keywords: [sign, address, transaction, message, bitcoin, ethereum, solana, verify,
+  btc, eth, sol, evm, cosmos, cardano, polkadot, tron, aptos, sui, near, xrp,
+  stellar, ton, nostr]
+---
+
+## Pre-flight Checks
+
+Every time before running any `onekey-hw` command, follow these steps in order.
+
+1. **Check CLI installed**: Run `onekey-hw --version`.
+   - Not found → install: `npm install -g @onekeyfe/hardware-cli`
+
+2. **Check device connected**: Run `onekey-hw search --json`.
+   - No device → guide troubleshooting (USB cable, unlock device, different port).
+   - Device in bootloader mode → cannot sign, guide to `hardware-firmware` skill.
+   - Device not initialized → guide user to set up device first.
+
+## Device Interaction — IMPORTANT
+
+**All signing commands block while waiting for physical interaction on the device.**
+You MUST follow this pattern for every signing/address command:
+
+1. **BEFORE running the command** → Tell the user:
+   "I'm about to [get your address / sign this transaction]. You will need to
+   confirm on your OneKey device. You may also need to enter your PIN if the
+   device is locked."
+
+2. **Run the command** with `timeout: 120000` (120 seconds minimum).
+   The user sees real-time `[onekey-hw]` prompts in their terminal via stderr.
+
+3. **If the command times out or returns `success: false`** → The user likely
+   did not confirm on the device. Ask if they want to retry. Do NOT retry automatically.
+
+## Security Rules — ABSOLUTE
+
+### Physical Confirmation Required
+
+- ALL signing operations display transaction details on the hardware device screen.
+- The user MUST physically press the confirm button on the device.
+- NEVER tell the user to "just press confirm" without showing them what they should
+  verify on the device screen.
+- If a signing request times out, it means the user rejected or did not confirm.
+
+### Address Verification
+
+- When generating addresses for receiving funds, ALWAYS use `--show-on-device true`
+  so the user can verify the address matches on the hardware screen.
+- NEVER trust an address that wasn't verified on-device.
+
+### Transaction Verification
+
+- Before signing, clearly display to the user:
+  - Recipient address
+  - Amount and token
+  - Network/chain
+  - Fee estimate (if available)
+- The device screen will show the same details — instruct user to verify they match.
+
+## Supported Chains
+
+| Chain | `--chain` Value | Address | Sign TX | Sign Message |
+|---|---|---|---|---|
+| Ethereum / EVM | `evm` | Yes | Yes | Yes (+ EIP-712) |
+| Bitcoin | `btc` | Yes | Yes (+ PSBT) | Yes |
+| Solana | `sol` | Yes | Yes | Yes |
+| Tron | `tron` | Yes | Yes | Yes |
+| Cosmos | `cosmos` | Yes | Yes | No |
+| Cardano | `cardano` | Yes | Yes | Yes |
+| Polkadot | `polkadot` | Yes | Yes | No |
+| Aptos | `aptos` | Yes | Yes | Yes |
+| Sui | `sui` | Yes | Yes | Yes |
+| Near | `near` | Yes | Yes | No |
+| XRP | `xrp` | Yes | Yes | No |
+| Stellar | `stellar` | Yes | Yes | No |
+| TON | `ton` | Yes | No | Yes (transfer-style*) |
+| Nostr | `nostr` | Public Key | No | Yes (+ Schnorr) |
+| Filecoin | `filecoin` | Yes | Yes | No |
+| Kaspa | `kaspa` | Yes | Yes | No |
+| Algorand | `algo` | Yes | Yes | No |
+| Conflux | `conflux` | Yes | Yes | Yes |
+| Nervos | `nervos` | Yes | Yes | No |
+| Alephium | `alephium` | Yes | Yes | Yes |
+| Neo | `neo` | Yes | Yes | No |
+| Starcoin | `starcoin` | Yes | Yes | Yes |
+| NEM | `nem` | Yes | Yes | No |
+| Dynex | `dnx` | Yes | Yes | No |
+| SCDO | `scdo` | Yes | Yes | Yes |
+| Benfen | `benfen` | Yes | Yes | Yes |
+| Nexa | `nexa` | Yes | Yes | No |
+
+## Parameter Rules
+
+### BIP44 Derivation Paths
+
+Default paths per chain (user can override with `--path`):
+
+| Chain | Default Path | Description |
+|---|---|---|
+| EVM | `m/44'/60'/0'/0/0` | Standard Ethereum |
+| BTC (segwit) | `m/84'/0'/0'/0/0` | Native SegWit (bech32) |
+| BTC (legacy) | `m/44'/0'/0'/0/0` | Legacy P2PKH |
+| BTC (taproot) | `m/86'/0'/0'/0/0` | Taproot P2TR |
+| SOL | `m/44'/501'/0'/0'` | Solana |
+| COSMOS | `m/44'/118'/0'/0/0` | Cosmos Hub |
+| CARDANO | `m/1852'/1815'/0'/0/0` | Cardano Shelley |
+
+If the user doesn't specify a path, use the chain's default. If they specify
+an account index (e.g., "second account"), adjust the account segment
+(e.g., `m/44'/60'/1'/0/0`).
+
+### Amount Units
+
+For chains that require amounts in transaction data:
+- ALWAYS use the human-readable unit in output display.
+- Transaction data is passed as the chain requires (hex for EVM, etc.).
+
+## Commands
+
+### `onekey-hw get-address`
+
+Get a cryptocurrency address from the connected hardware wallet.
+
+```bash
+onekey-hw get-address \
+  --chain <chain> \
+  [--path <bip44-path>] \
+  [--show-on-device <bool>] \
+  [--connect-id <id>]
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--chain` | Yes | Target blockchain (see supported chains table) |
+| `--path` | No | BIP44 derivation path (uses chain default if omitted) |
+| `--show-on-device` | No | Display address on device for verification (default: true) |
+| `--connect-id` | No | Device connection ID (auto-detected if single device) |
+
+**Returns:**
+```json
+{
+  "success": true,
+  "payload": {
+    "address": "0x1234...abcd",
+    "path": "m/44'/60'/0'/0/0"
+  }
+}
+```
+
+**Agent notes:**
+- Default `--show-on-device` is true. When true, instruct user:
+  "Please verify the address shown on your OneKey device screen matches."
+- For receiving funds, ALWAYS verify on device.
+- For batch operations (multiple addresses), may set `--show-on-device false` for speed.
+
+### `onekey-hw get-public-key`
+
+Get public key (for chains that support it: EVM, BTC, Aptos, Cosmos, Sui, etc.).
+
+```bash
+onekey-hw get-public-key \
+  --chain <chain> \
+  [--path <bip44-path>] \
+  [--connect-id <id>]
+```
+
+**Returns:**
+```json
+{
+  "success": true,
+  "payload": {
+    "publicKey": "04abcdef...",
+    "path": "m/44'/60'/0'/0/0"
+  }
+}
+```
+
+### `onekey-hw sign-transaction`
+
+Sign a blockchain transaction using the hardware wallet. Requires physical
+confirmation on the device.
+
+```bash
+onekey-hw sign-transaction \
+  --chain <chain> \
+  --tx <transaction-json> \
+  [--path <bip44-path>] \
+  [--connect-id <id>]
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--chain` | Yes | Target blockchain |
+| `--tx` | Yes | Transaction data (JSON object, chain-dependent) |
+| `--path` | No | BIP44 derivation path |
+| `--connect-id` | No | Device connection ID |
+
+**EVM Transaction Example (EIP-1559):**
+```bash
+onekey-hw sign-transaction \
+  --chain evm \
+  --tx '{"to":"0xAbC...","value":"0xf4240","data":"0x","chainId":1,"nonce":"0x0","maxFeePerGas":"0x14","maxPriorityFeePerGas":"0x0","gasLimit":"0x5208"}'
+```
+
+**BTC Transaction Example (inputs/outputs/refTxs format):**
+```bash
+onekey-hw sign-transaction \
+  --chain btc \
+  --tx '{"coin":"btc","inputs":[{"address_n":[2147483692,2147483648,2147483650,1,0],"prev_index":0,"prev_hash":"b035d89d..."}],"outputs":[{"address":"18WL2iZ...","amount":"200000","script_type":"PAYTOADDRESS"}],"refTxs":[...]}'
+```
+
+> **Note:** BTC uses `inputs/outputs/refTxs` format, NOT raw hex or PSBT.
+> For PSBT signing, use `sign-psbt` instead.
+
+**Agent notes:**
+- This is the most critical operation — requires physical device confirmation.
+- Before calling, clearly display to the user what will be signed:
+  "You are about to sign: Send 0.01 ETH to 0xAbC... on Ethereum Mainnet"
+- Inform user: "Please review and confirm the transaction on your OneKey device."
+- If the call times out or returns `{ success: false }`, the user likely rejected
+  on device — do NOT retry automatically.
+- Transaction format varies per chain — refer to the SDK documentation for each chain.
+
+### `onekey-hw sign-message`
+
+Sign an arbitrary message (for chains that support message signing).
+
+```bash
+onekey-hw sign-message \
+  --chain <chain> \
+  --message <message> \
+  [--path <bip44-path>] \
+  [--connect-id <id>]
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--chain` | Yes | Target blockchain |
+| `--message` | Yes | Message to sign (string or hex) |
+| `--path` | No | BIP44 derivation path |
+| `--connect-id` | No | Device connection ID |
+
+**Agent notes:**
+- Device will show the message for user verification.
+- **TON note**: `tonSignMessage` is a transfer-signing method, not arbitrary message
+  signing. Pass `--message` as JSON: `'{"destination":"UQ...","tonAmount":100,"seqno":0,"expireAt":1234567890}'`.
+
+### `onekey-hw sign-typed-data`
+
+Sign EIP-712 typed data (EVM only).
+
+```bash
+onekey-hw sign-typed-data \
+  --data <eip712-json> \
+  [--path <bip44-path>] \
+  [--metamask-v4-compat] \
+  [--connect-id <id>]
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--data` | Yes | EIP-712 typed data as JSON |
+| `--path` | No | BIP44 derivation path (default: m/44'/60'/0'/0/0) |
+| `--metamask-v4-compat` | No | MetaMask V4 compatibility mode (default: true) |
+
+### `onekey-hw sign-psbt`
+
+Sign a Bitcoin PSBT (Partially Signed Bitcoin Transaction).
+Only supported on Pro (>= 4.9.3) and Classic1s (>= 3.10.1).
+
+```bash
+onekey-hw sign-psbt \
+  --psbt <hex-encoded-psbt> \
+  [--coin <coin>] \
+  [--connect-id <id>]
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--psbt` | Yes | Hex-encoded PSBT data |
+| `--coin` | No | Bitcoin network: btc, ltc, etc. (default: btc) |
+
+**Agent notes:**
+- Simpler than `sign-transaction --chain btc` (no need to construct inputs/outputs/refTxs).
+- Classic1s has a limit of 5 UTXOs per PSBT.
+- Preferred method when the application provides PSBT format.
+
+### `onekey-hw verify-message`
+
+Verify a signed message on-device (BTC, EVM, Starcoin).
+
+```bash
+onekey-hw verify-message \
+  --chain <chain> \
+  --address <address> \
+  --message <message> \
+  --signature <signature> \
+  [--connect-id <id>]
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--chain` | Yes | btc, evm, or starcoin |
+| `--address` | Yes | Signer address (or publicKey for starcoin) |
+| `--message` | Yes | Original message |
+| `--signature` | Yes | Signature to verify |
+
+### `onekey-hw batch-get-address`
+
+Get addresses for multiple chains/paths in a single session.
+
+```bash
+onekey-hw batch-get-address \
+  --bundle <json-array> \
+  [--connect-id <id>]
+```
+
+**Example bundle:**
+```json
+[
+  { "chain": "evm", "path": "m/44'/60'/0'/0/0", "showOnDevice": false },
+  { "chain": "btc", "path": "m/84'/0'/0'/0/0", "showOnDevice": false },
+  { "chain": "sol", "path": "m/44'/501'/0'/0'", "showOnDevice": false }
+]
+```
+
+**Agent notes:**
+- Batch mode disables on-device verification for speed.
+- Useful for portfolio dashboards or multi-chain wallet setup.
+
+## Chain-Specific Commands
+
+These commands wrap chain-specific SDK methods that don't fit the generic
+`sign-message` / `sign-transaction` pattern.
+
+### `onekey-hw evm-sign-eip712`
+
+Sign EIP-712 message by pre-computed domain and message hashes.
+
+```bash
+onekey-hw evm-sign-eip712 --domain-hash <hex> --message-hash <hex> [--path <path>]
+```
+
+### `onekey-hw sol-sign-offchain`
+
+Sign a Solana off-chain message.
+
+```bash
+onekey-hw sol-sign-offchain --message-hex <hex> [--path <path>]
+```
+
+### `onekey-hw nostr-encrypt` / `nostr-decrypt`
+
+Encrypt/decrypt Nostr NIP-04 messages.
+
+```bash
+onekey-hw nostr-encrypt --pubkey <hex> --plaintext <text> [--path <path>]
+onekey-hw nostr-decrypt --pubkey <hex> --ciphertext <text> [--path <path>]
+```
+
+### `onekey-hw nostr-sign-schnorr`
+
+Sign a Schnorr signature (BIP-340) for Nostr.
+
+```bash
+onekey-hw nostr-sign-schnorr --hash <hex> [--path <path>]
+```
+
+### `onekey-hw lnurl-auth`
+
+Authenticate with a service using LNURL-auth (Lightning Network).
+
+```bash
+onekey-hw lnurl-auth --domain <domain> --k1 <hex>
+```
+
+### `onekey-hw conflux-sign-cip23`
+
+Sign a Conflux CIP-23 structured message.
+
+```bash
+onekey-hw conflux-sign-cip23 --domain-hash <hex> --message-hash <hex> [--path <path>]
+```
+
+### `onekey-hw aptos-sign-in`
+
+Sign an Aptos sign-in message (wallet authentication).
+
+```bash
+onekey-hw aptos-sign-in --payload <text> [--path <path>]
+```
+
+### `onekey-hw ton-sign-proof`
+
+Sign a TON Connect proof for wallet authentication.
+
+```bash
+onekey-hw ton-sign-proof --appdomain <domain> --expire-at <timestamp> [--comment <text>] [--path <path>]
+```
+
+## Workflows
+
+### Get Receive Address
+
+```
+User: "Give me my Ethereum address"
+
+Step 1 — Ensure device connected
+→ onekey-hw search --json
+→ onekey-hw status --connect-id <id>
+
+Step 2 — Get address with on-device verification
+→ onekey-hw get-address --chain evm --show-on-device true --connect-id <id>
+→ "Please verify the address on your OneKey device screen."
+→ Display address to user
+```
+
+### Sign an EVM Transaction
+
+```
+User: "Sign this transaction: send 0.1 ETH to 0xAbc..."
+
+Step 1 — Ensure device connected
+→ onekey-hw search --json
+
+Step 2 — Display transaction details to user
+→ "You are about to sign: Send 0.1 ETH to 0xAbc... on Ethereum"
+
+Step 3 — Wait for user confirmation in chat
+→ User says "yes" / "confirm"
+
+Step 4 — Sign
+→ onekey-hw sign-transaction --chain evm --tx '{"to":"0xAbc...","value":"0x16345785D8A0000",...}' --connect-id <id>
+→ "Please review and confirm on your OneKey device."
+
+Step 5 — Return signature
+→ Display signed transaction
+```
+
+### Multi-Chain Address Setup
+
+```
+User: "Set up my wallet with addresses for ETH, BTC, and SOL"
+
+Step 1 — Ensure device connected
+→ onekey-hw search --json
+
+Step 2 — Batch get addresses
+→ onekey-hw batch-get-address --bundle '[
+    {"chain":"evm","path":"m/44'/60'/0'/0/0","showOnDevice":false},
+    {"chain":"btc","path":"m/84'/0'/0'/0/0","showOnDevice":false},
+    {"chain":"sol","path":"m/44'/501'/0'/0'","showOnDevice":false}
+  ]' --connect-id <id>
+
+Step 3 — Present results
+→ Display all addresses in a clean table
+```
+
+## When To Use
+
+- User wants to get a cryptocurrency address for receiving funds.
+- User wants to sign any blockchain transaction.
+- User wants to sign or verify a message.
+- User needs public keys for multi-sig or advanced setups.
+- User wants addresses across multiple chains.
+
+## When NOT To Use
+
+- User wants to connect or search for devices → use `hardware-device`.
+- User wants to update firmware → use `hardware-firmware`.
+- User wants to change PIN/passphrase → use `hardware-security`.
+- User wants to broadcast a signed transaction → this skill only SIGNS,
+  broadcasting is handled by the application layer.