Merge pull request #157 from hyperweb-io/major-refactor-unisigner

Major refactor unisigner

Author: Zetazzz

.github/workflows/e2e-tests.yaml

@@ -10,34 +10,6 @@ on:
   workflow_dispatch:
 
 jobs:
-  interchainjs:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout Repository 📝
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20.x"
-          cache: "yarn"
-
-      - name: Install Dependencies
-        run: yarn install --frozen-lockfile
-
-      - name: Build Project
-        run: yarn build
-
-      - name: Set Up Starship Infrastructure
-        id: starship-infra
-        uses: hyperweb-io/[email protected]
-        with:
-          config: libs/interchainjs/starship/configs/config.workflow.yaml
-
-      - name: Run E2E Tests
-        run: cd ./libs/interchainjs && yarn starship:test
-
   networks-cosmos:
     runs-on: ubuntu-latest
 

README.md

@@ -130,80 +130,77 @@ npm i @interchainjs/cosmos
 
 ## Quick Start
 
-Get a signing client to send the trasactions:
+### Using Signers Directly
 
-```ts
-import { SigningClient as CosmosSigningClient } from "@interchainjs/cosmos";
+Create and use signers for transaction signing and broadcasting:
 
-const signingClient = await CosmosSigningClient.connectWithSigner(
-  await getRpcEndpoint(),
-  new DirectGenericOfflineSigner(directSigner),
+```typescript
+import { DirectSigner } from '@interchainjs/cosmos';
+import { Secp256k1HDWallet } from '@interchainjs/cosmos';
+import { HDPath } from '@interchainjs/types';
+
+// Create wallet from mnemonic
+const wallet = await Secp256k1HDWallet.fromMnemonic(
+  "your twelve word mnemonic phrase here",
   {
-    registry: [
-      // as many as possible encoders registered here.
-      MsgDelegate,
-      MsgSend,
-    ],
-    broadcast: {
-      checkTx: true,
-    },
+    derivations: [{
+      prefix: "cosmos",
+      hdPath: HDPath.cosmos(0, 0, 0).toString(), // m/44'/118'/0'/0/0
+    }]
   }
 );
 
-// sign and broadcast
-const result = await signingClient.signAndBroadcast(<MESSAGE>[]);
-console.log(result.hash); // the hash of TxRaw
+// Create signer
+const signer = new DirectSigner(wallet, {
+  chainId: 'cosmoshub-4',
+  queryClient: queryClient,
+  addressPrefix: 'cosmos'
+});
+
+// Sign and broadcast transaction
+const result = await signer.signAndBroadcast({
+  messages: [{
+    typeUrl: '/cosmos.bank.v1beta1.MsgSend',
+    value: {
+      fromAddress: 'cosmos1...',
+      toAddress: 'cosmos1...',
+      amount: [{ denom: 'uatom', amount: '1000000' }]
+    }
+  }],
+  fee: {
+    amount: [{ denom: 'uatom', amount: '5000' }],
+    gas: '200000'
+  },
+  memo: 'Transfer via InterchainJS'
+});
+
+console.log('Transaction hash:', result.transactionHash);
 ```
 
-Use the tree shakable helper functions provided by interchainjs or generated by telescope for query or send the transctions:
+### Using with External Wallets
 
-```ts
-import { SigningClient as CosmosSigningClient } from "@interchainjs/cosmos/signing-client";
-import { getBalance } from "interchainjs/cosmos/bank/v1beta1/query.rpc.func";
-import { submitProposal } from "interchainjs/cosmos/gov/v1beta1/tx.rpc.func";
+For integration with browser wallets like Keplr:
 
-// query to get balance
-const { balance } = await getBalance(await getRpcEndpoint(), {
-  address: directAddress,
-  denom,
-});
+```typescript
+import { DirectSigner } from '@interchainjs/cosmos';
 
-const signingClient = await CosmosSigningClient.connectWithSigner(
-  await getRpcEndpoint(),
-  new DirectGenericOfflineSigner(directSigner),
-  {
-    // no registry needed here anymore
-    // registry: [
-    // ],
-    broadcast: {
-      checkTx: true,
-    },
-  }
-);
+// Get offline signer from Keplr
+await window.keplr.enable(chainId);
+const offlineSigner = window.keplr.getOfflineSigner(chainId);
 
-// Necessary typeurl and codecs will be registered automatically in the helper functions. Meaning users don't have to register them all at once.
-const result = await submitProposal(
-  signingClient,
-  directAddress,
-  {
-    proposer: directAddress,
-    initialDeposit: [
-      {
-        amount: "1000000",
-        denom: denom,
-      },
-    ],
-    content: {
-      typeUrl: "/cosmos.gov.v1beta1.TextProposal",
-      value: TextProposal.encode(contentMsg).finish(),
-    },
-  },
-  fee,
-  "submit proposal"
-);
-console.log(result.hash); // the hash of TxRaw
-```
+// Create signer with offline signer
+const signer = new DirectSigner(offlineSigner, {
+  chainId: 'cosmoshub-4',
+  queryClient: queryClient,
+  addressPrefix: 'cosmos'
+});
 
+// Use the same signing interface
+const result = await signer.signAndBroadcast({
+  messages: [/* your messages */],
+  fee: { amount: [{ denom: 'uatom', amount: '5000' }], gas: '200000' }
+});
+```
 
 ### Quick Setup with create-interchain-app
 
@@ -247,6 +244,27 @@ Then an authz example website will be created and users can take a look how sign
 
 ---
 
+## Developer Documentation
+
+### For Contributors and Network Implementers
+
+- **[Network Implementation Guide](./docs/advanced/network-implementation-guide.md)** - Comprehensive guide for implementing new blockchain network support
+- **[Workflow Builder and Plugins Guide](./docs/advanced/workflow-builder-and-plugins.md)** - Plugin-based transaction workflow architecture
+- **[Auth vs. Wallet vs. Signer](./docs/advanced/auth-wallet-signer.md)** - Understanding the three-layer architecture
+- **[Tutorial](./docs/advanced/tutorial.md)** - Using and extending signers in the InterchainJS ecosystem
+
+### Architecture and Design
+
+InterchainJS follows a modular, three-layer architecture that separates concerns and enables flexible blockchain integration:
+
+1. **Auth Layer**: Cryptographic operations and key management
+2. **Wallet Layer**: Account management and address derivation
+3. **Signer Layer**: Transaction building, signing, and broadcasting
+
+This separation allows for maximum flexibility while maintaining type safety and consistent interfaces across different blockchain networks.
+
+---
+
 ## Interchain JavaScript Stack ⚛️
 
 A unified toolkit for building applications and smart contracts in the Interchain ecosystem

docs/advanced/auth-wallet-signer.md

@@ -1,58 +1,99 @@
 # Auth vs. Wallet vs. Signer: A Comparison
 
-This document aims to provide an overview and comparison of `Auth`, `Wallet`, and `Signer`, three types commonly used for encryption and signing purposes in different networks. Each type serves a specific purpose and has its own characteristics and functionalities.
+This document provides an overview and comparison of `Auth`, `Wallet`, and `Signer`, three core abstractions used for cryptographic operations and transaction signing in the InterchainJS ecosystem. Each serves a specific purpose in the signing workflow and has distinct characteristics and functionalities.
 
 ```mermaid
 graph LR
-    subgraph AuthType[Auth]
-        ByteAuth --> |privateKey| PrivateKey
-        PrivateKey --> |sign| SignedTx
-        OfflineSigner[Hide PrivateKey] --> DocAuth
-        DocAuth --> |signDoc| SignedTx
+    subgraph AuthLayer[Auth Layer]
+        IWallet --> |getAccounts| IAccount[Account]
+        IWallet --> |signByIndex| Signature
+        OfflineSigner --> |signDirect/signAmino| SignedDoc
     end
 
-    Wallet --> |accounts| IAccount[Account]
-    Wallet --> |toOfflineSigner| OfflineSigner
-
-    Signer --> |prefix| Prefix
-    Signer --> |account| Account
-    Signer --> |encoders| Encoder
-    Signer --> |signAndBroadCast| SignAndBroadCast
+    subgraph SignerLayer[Signer Layer]
+        IUniSigner --> |getAccounts| AccountData
+        IUniSigner --> |sign| ISigned
+        IUniSigner --> |signAndBroadcast| BroadcastResponse
+        IUniSigner --> |signArbitrary| ICryptoBytes
+    end
 
-    Account --> |auth| Auth
+    AuthLayer --> SignerLayer
+    IAccount --> |address/publicKey| SignerLayer
 
 ```
 
-## 1. Auth
+## 1. Auth Layer
+
+The Auth layer provides the foundational cryptographic capabilities for account management and signing operations. It consists of two main abstractions:
+
+### IWallet Interface
+
+`IWallet` is the primary interface for managing cryptographic accounts and performing low-level signing operations:
+
+- **Account Management**: Provides access to multiple accounts through `getAccounts()` and `getAccountByIndex()`
+- **Direct Signing**: Offers `signByIndex()` method to sign arbitrary binary data using a specific account
+- **Network Agnostic**: Designed to work across different blockchain networks with configurable address derivation strategies
+
+### OfflineSigner Interface
+
+`OfflineSigner` provides a secure way to sign transactions without exposing private keys:
+
+- **External Wallet Integration**: Designed for integration with external wallets like Keplr, Leap, or hardware wallets
+- **Document Signing**: Supports both Direct (protobuf) and Amino (JSON) signing modes through `OfflineDirectSigner` and `OfflineAminoSigner`
+- **Privacy Preservation**: Keeps private keys secure within the external wallet while providing signing capabilities
+
+## 2. Wallet Implementations
+
+Wallet implementations provide concrete realizations of the `IWallet` interface, offering HD (Hierarchical Deterministic) key derivation and network-specific address generation:
+
+### Secp256k1HDWallet
+
+The primary wallet implementation for secp256k1 cryptography:
+
+- **HD Key Derivation**: Supports BIP-32/BIP-44 hierarchical deterministic key derivation from mnemonic phrases
+- **Multi-Account Support**: Can manage multiple accounts with different derivation paths
+- **Network Compatibility**: Works across Cosmos, Ethereum, and Injective networks with appropriate address strategies
+- **Offline Signer Conversion**: Can be converted to `OfflineDirectSigner` or `OfflineAminoSigner` for external wallet compatibility
 
-`Auth` is a common implementation of an encryption algorithm that can be utilized across different networks. It provides a signing method to sign binary data. The primary features and characteristics of `Auth` are as follows:
+### Network-Specific Variants
 
-- **Encryption Algorithm**: `Auth` implements an encryption algorithm that is compatible and usable across various networks.
+- **Cosmos**: `Secp256k1HDWallet` with bech32 address encoding
+- **Ethereum**: `Secp256k1HDWallet` with keccak256 hashing and hex address format
+- **Injective**: `EthSecp256k1HDWallet` with Ethereum-style addresses but Cosmos transaction format
 
-- **Signing Binary Data**: `Auth` offers a method to sign binary data, which can be used for verifying the integrity and authenticity of the data.
+## 3. Signer Layer
 
-- **Network Agnostic**: Auth is designed to work with different networks, making it a versatile solution for encryption and signing needs.
+The Signer layer provides the highest-level abstraction for transaction signing and broadcasting, implementing the `IUniSigner` interface. Signers can be constructed from either `IWallet` implementations or `OfflineSigner` interfaces.
 
-## 2. Wallet
+### IUniSigner Interface
 
-`Wallet` is a wrapper built upon `Auth`, providing additional functionalities and convenience, particularly for Web3 usage. `Wallet` extends the capabilities of `Auth` and introduces the following aspects:
+The universal signer interface provides a consistent API across all blockchain networks:
 
-- **Signing Network and Document**: In addition to signing binary data, `Wallet` provides a signing method specifically designed for signing network-related information and sign mode specified documents.
+- **Account Management**: `getAccounts()` returns account information including addresses and public keys
+- **Transaction Workflow**: `sign()` creates signed transactions, `broadcast()` submits them to the network, and `signAndBroadcast()` combines both operations
+- **Arbitrary Signing**: `signArbitrary()` signs raw binary data for authentication purposes
+- **Network Abstraction**: Generic type parameters allow network-specific customization while maintaining a unified interface
 
-- **Web3 Integration**: `Wallet` is tailored for Web3 usage, making it compatible with blockchain and decentralized applications.
+### Network-Specific Implementations
 
-- **Enhanced Functionality**: `Wallet` encompasses the features of `Auth` while incorporating additional functionalities to facilitate secure interactions with Web3 wallets.
+- **Cosmos Signers**: `DirectSigner` and `AminoSigner` for protobuf and JSON signing modes
+- **Ethereum Signers**: `LegacySigner` and `Eip1559Signer` for different transaction types
+- **Injective Signers**: Cosmos-compatible signers with Ethereum-style address derivation
 
-## 3. Signer
+### Construction Patterns
 
-`Signer` is a class that can be constructed from `Auth` or `Wallet`. It focuses on providing a signing method specifically for directly signing human-readable messages. Key aspects of `Signer` include:
+Signers can be constructed in multiple ways:
 
-- **Signing Human-Readable Messages**: `Signer` offers a dedicated signing method for signing messages that are in a human-readable format, such as plain text or structured data.
+1. **From IWallet**: Direct construction with full private key access
+2. **From OfflineSigner**: Construction for external wallet integration
+3. **Configuration-based**: Using network-specific configuration objects
 
-- **Flexible Construction**: `Signer` can be constructed using either `Auth` or `Wallet`, allowing users to choose their preferred underlying implementation based on their specific requirements.
+## Summary
 
-- **Message-Level Security**: `Signer` emphasizes the signing of human-readable messages, making it suitable for use cases where secure communication and message integrity are essential.
+The three-layer architecture provides clear separation of concerns:
 
-In summary, `Auth` serves as a fundamental implementation of an encryption algorithm, providing a signing method for binary data. `Wallet`, built upon `Auth`, extends its capabilities by introducing network and document-specific signing methods, tailored for Web3 usage. `Signer`, the top-level layer, contains the code for structured data signing and focuses on dedicated methods for directly signing human-readable messages, which offers flexibility and message-level security.
+- **Auth Layer**: Foundational cryptographic operations and account management
+- **Wallet Layer**: HD key derivation and network-specific address generation
+- **Signer Layer**: High-level transaction signing and broadcasting with network abstraction
 
-The hierarchical relationship between `Auth`, `Wallet`, and `Signer` positions Auth as the foundation, Wallet as the middle layer, and Signer as the top layer with the highest-level functionality for structured data signing. However, the specific choice among `Auth`, `Wallet`, or `Signer` depends on specific requirements and use cases, ensuring the appropriate level of encryption, signing, and security for various network-related operations.
+This design allows developers to choose the appropriate abstraction level based on their security requirements, from low-level cryptographic control to high-level transaction management, while maintaining compatibility across different blockchain networks.