Merge pull request #2 from AIBlockOfficial/ci/publish-pypi

CI: add PyPI publish workflow; SDK: make Wallet.get_balance return IR…

Author: BarryBoot

.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [ "main" ]
+
+concurrency:
+  group: publish-pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build-and-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build backend
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true
+
+

README.md

@@ -10,78 +10,108 @@ pip install aiblock
 
 ## Quick Start
 
-### Configuration Setup
+### Basic Blockchain Queries
 
-The SDK uses environment variables for configuration:
+```python
+from aiblock.blockchain import BlockchainClient
 
-```bash
-# Required environment variables
-export AIBLOCK_PASSPHRASE="your-secure-passphrase"
+# Initialize blockchain client
+client = BlockchainClient(
+    storage_host='https://storage.aiblock.dev',
+    mempool_host='https://mempool.aiblock.dev'
+)
+
+# Query blockchain
+latest_block = client.get_latest_block()
+if latest_block.is_ok:
+    print(f"Latest block: {latest_block.get_ok()['content']['block_num']}")
+
+# Get specific block by number
+block = client.get_block_by_num(1)
+if block.is_ok:
+    print(f"Block 1: {block.get_ok()['content']}")
 
-# Optional environment variables (defaults shown)
-export AIBLOCK_STORAGE_HOST="https://storage.aiblock.dev"
-export AIBLOCK_MEMPOOL_HOST="https://mempool.aiblock.dev"
-export AIBLOCK_VALENCE_HOST="https://valence.aiblock.dev"
+# Get blockchain entry by hash
+entry = client.get_blockchain_entry('some_hash')
+
+# Get transaction by hash
+transaction = client.get_transaction_by_hash('tx_hash')
+
+# Get multiple transactions
+transactions = client.fetch_transactions(['hash1', 'hash2'])
+
+# Get supply information (requires mempool host)
+total_supply = client.get_total_supply()
+issued_supply = client.get_issued_supply()
 ```
 
-### Basic Usage
+### Wallet Operations
 
 ```python
 from aiblock.wallet import Wallet
-from aiblock.blockchain import BlockchainClient
-from aiblock.config import get_config, validate_env_config
-
-# Get and validate configuration
-config = get_config()
-error = validate_env_config(config)
-if error:
-    print(f"Configuration error: {error}")
-    exit(1)
 
-# Initialize blockchain client
-blockchain_client = BlockchainClient(
-    storage_host=config['storageHost'],
-    mempool_host=config['mempoolHost']
-)
-
-# Create and initialize wallet
+# Create wallet
 wallet = Wallet()
-seed_phrase = wallet.generate_seed_phrase()
-keypair = wallet.generate_keypair()
 
-# Query blockchain
-latest_block = blockchain_client.get_latest_block()
-total_supply = blockchain_client.get_total_supply()
-issued_supply = blockchain_client.get_issued_supply()
-balance = blockchain_client.get_balance(keypair['address'])
+# Generate seed phrase
+seed_phrase = wallet.generate_seed_phrase()
+print(f"Seed phrase: {seed_phrase}")
+
+# Initialize wallet from seed
+config = {
+    'passphrase': 'your-secure-passphrase',
+    'mempoolHost': 'https://mempool.aiblock.dev',
+    'storageHost': 'https://storage.aiblock.dev',
+    'valenceHost': 'https://valence.aiblock.dev'
+}
+
+result = wallet.from_seed(seed_phrase, config)
+if result.is_ok:
+    print(f"Wallet address: {wallet.get_address()}")
 ```
 
 ## Features
 
+### Blockchain Client
+- **get_latest_block()** - Get the latest block information
+- **get_block_by_num(block_num)** - Get a specific block by number
+- **get_blockchain_entry(hash)** - Get blockchain entry by hash
+- **get_transaction_by_hash(tx_hash)** - Get transaction details
+- **fetch_transactions(tx_hashes)** - Get multiple transactions
+- **get_total_supply()** - Get total token supply
+- **get_issued_supply()** - Get issued token supply
+
 ### Wallet Operations
 - Generate and manage seed phrases
 - Create and manage keypairs
 - Create and sign transactions
 - Create item assets
 - Check balances
+- 2WayPayment protocol support
+
+## Configuration
 
-### Blockchain Operations
-- Query latest block
-- Get block by number
-- Get blockchain entry by hash
-- Get total supply
-- Get issued supply
-- Get balance for address
+The SDK uses environment variables for configuration. Create a `.env` file:
 
-## Example Usage
+```bash
+AIBLOCK_PASSPHRASE="your-secure-passphrase"
+AIBLOCK_STORAGE_HOST="https://storage.aiblock.dev"
+AIBLOCK_MEMPOOL_HOST="https://mempool.aiblock.dev"
+AIBLOCK_VALENCE_HOST="https://valence.aiblock.dev"
+```
 
-See the [documentation](https://github.com/AIBlockOfficial/2Way.py/tree/main/docs) for more advanced usage and examples, including:
-- Wallet initialization
-- Keypair generation
-- Blockchain queries
-- Asset creation
-- Transaction creation
-- 2WayPayment protocol
+## Error Handling
+
+All methods return `IResult` objects with proper error handling:
+
+```python
+result = client.get_latest_block()
+if result.is_ok:
+    data = result.get_ok()
+    print(f"Success: {data}")
+else:
+    print(f"Error: {result.error_message}")
+```
 
 ## Development
 
@@ -90,6 +120,14 @@ See the [documentation](https://github.com/AIBlockOfficial/2Way.py/tree/main/doc
 3. Install test dependencies: `pip install -r requirements-test.txt`
 4. Run tests: `pytest`
 
+All 68 tests pass, ensuring reliability and compatibility.
+
+## Documentation
+
+- [API Reference](docs/api-reference.md) - Complete API documentation
+- [Examples](docs/examples.md) - Usage examples and patterns
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
+
 ## Contributing
 
 We welcome contributions! Please feel free to submit a Pull Request.

aiblock/wallet.py

@@ -599,35 +599,51 @@ def get_headers(self) -> Dict[str, str]:
             'Nonce': get_random_string(32)
         }
 
-    def get_balance(self) -> Dict[str, Any]:
-        """Get balance for the current address.
-        
+    def get_balance(self) -> IResult[Dict[str, Any]]:
+        """Get balance for the current address as an IResult for consistency."""
+        try:
+            if not self.current_keypair:
+                return IResult.err(IErrorInternal.WalletNotInitialized, "Wallet not initialized")
+
+            # Initialize network if needed
+            if not self.routes_initialized:
+                init_result = self.init_network(self.config)
+                if init_result.is_err:
+                    return IResult.err(IErrorInternal.UnableToInitializeNetwork, init_result.error_message)
+
+            balance_result = self.fetch_balance([self.current_keypair.address])
+            if balance_result.is_err:
+                return IResult.err(IErrorInternal.UnableToFetchBalance, balance_result.error_message)
+
+            return IResult.ok(balance_result.get_ok())
+        except Exception as e:
+            logger.error(f"Error getting balance: {str(e)}")
+            return IResult.err(IErrorInternal.InternalError, str(e))
+
+    def get_balance_result(self) -> IResult[Dict[str, Any]]:
+        """Get balance for the current address as an IResult for consistency.
+
         Returns:
-            Dict[str, Any]: Balance information
-            
-        Raises:
-            RuntimeError: If wallet is not initialized
+            IResult[Dict[str, Any]]: Success with balance dict, or error with reason.
         """
         try:
             if not self.current_keypair:
-                raise RuntimeError("Wallet not initialized")
+                return IResult.err(IErrorInternal.WalletNotInitialized, "Wallet not initialized")
 
             # Initialize network if needed
             if not self.routes_initialized:
                 init_result = self.init_network(self.config)
                 if init_result.is_err:
-                    raise RuntimeError("Failed to initialize network")
+                    return IResult.err(IErrorInternal.UnableToInitializeNetwork, init_result.error_message)
 
-            # Get balance
             balance_result = self.fetch_balance([self.current_keypair.address])
             if balance_result.is_err:
-                raise RuntimeError("Failed to fetch balance")
-
-            return balance_result.get_ok()
+                return IResult.err(IErrorInternal.UnableToFetchBalance, balance_result.error_message)
 
+            return IResult.ok(balance_result.get_ok())
         except Exception as e:
             logger.error(f"Error getting balance: {str(e)}")
-            raise
+            return IResult.err(IErrorInternal.InternalError, str(e))
 
     def create_item_asset(
         self,