@hiero-ledger/sdk 2.79.0 → 2.80.0

package/README.md

@@ -72,6 +72,55 @@ After downloading the repo run:
 
 2. `task build` to build the SDK
 
+## Development
+
+### Local Development Workflow
+
+The SDK uses `pnpm workspaces` to manage its monorepo structure with sub-packages (`@hiero-ledger/proto` and `@hiero-ledger/cryptography`). For local development and testing the SDK in other projects, use the following workflow:
+
+#### Build and Link Globally
+
+Build the SDK and link it globally for use in other local projects:
+
+```bash
+task build:dev
+```
+
+This command:
+- Builds all packages (`proto`, `cryptography`, and the main SDK)
+- Creates global symlinks for all three packages
+- Allows you to use the local SDK in any other project on your machine
+
+#### Use in Another Project
+
+In your other project, link to the globally linked SDK:
+
+```bash
+cd /path/to/your/other/project
+pnpm link --global @hiero-ledger/sdk
+```
+
+Now any changes you make to the SDK and rebuild will be immediately available in your project.
+
+#### Unlink and Clean
+
+When you're done with local development:
+
+```bash
+# In the hiero-sdk-js repository
+task clean
+```
+
+This removes all global links and cleans up `node_modules`.
+
+To unlink in your other project:
+
+```bash
+# In your other project
+pnpm unlink @hiero-ledger/sdk
+pnpm install
+```
+
 ## React Native Support
 
 The Hiero JavaScript SDK provides comprehensive support for React Native environments, including Expo. To ensure seamless integration, follow the guidelines based on your Expo version:
@@ -141,17 +190,125 @@ Every example can be executed using the following command from the root director
 
 For detailed information on configuring the SDK, including environment variables and client settings, please refer to the [CONFIGURATION.md](./manual/CONFIGURATION.md) file.
 
-## Start tests
-
-- To start the integration tests follow the next steps:
-    - Run the [local node](https://github.com/hiero-ledger/hiero-local-node)
-    - Rename [sample.env](https://github.com/hiero-ledger/hiero-sdk-js/blob/main/.env.sample) in the root directory to .env
-        - Ensure the `OPERATOR_ID` and `OPERATOR_KEY` are fields populated from accounts created by the local node
-        - Update the network to `HEDERA_NETWORK="local-node"`
-    - Run `task test:integration:node`
-    - Stop the [local node](https://github.com/hiero-ledger/hiero-local-node)
-- To start unit tests follow the next steps:
-    - Run `task test:unit`
+## Local Development Setup
+
+For contributors and developers who want to run integration tests locally, we provide **Solo** - the official Hiero local network solution. Solo provides a production-like Kubernetes-based environment with multiple consensus nodes and mirror node services.
+
+### Quick Setup
+
+1. **Install dependencies:**
+   ```bash
+   task install
+   ```
+   
+   **Important:** This installs Solo and all project dependencies. Must be run before setup.
+
+2. **Set up Solo local network:**
+   ```bash
+   task solo:setup
+   ```
+   
+   This will automatically:
+   - Create a local Kubernetes cluster with Kind
+   - Deploy a 2-node consensus network (default: v0.69.1)
+   - Deploy mirror node services (default: v0.145.2)
+   - Create a dedicated ECDSA test account
+   - Generate a `.env` file with all necessary credentials
+
+   **Optional:** Specify custom versions or use local build:
+   ```bash
+   # Custom consensus node version
+   task solo:setup -- --consensus-node-version v0.70.0
+   
+   # Custom mirror node version
+   task solo:setup -- --mirror-node-version v0.146.0
+   
+   # Both custom versions
+   task solo:setup -- --consensus-node-version v0.70.0 --mirror-node-version v0.146.0
+   
+   # Use local build (overrides consensus-node-version)
+   task solo:setup -- --local-build-path ../hiero-consensus-node/hedera-node/data
+   ```
+
+3. **(Required for dynamic address book tests) Configure hosts:**
+   
+   Before running dynamic address book tests, add Kubernetes service names to your `/etc/hosts` file:
+   
+   ```bash
+   echo "127.0.0.1 network-node1-svc.solo.svc.cluster.local" | sudo tee -a /etc/hosts
+   echo "127.0.0.1 envoy-proxy-node1-svc.solo.svc.cluster.local" | sudo tee -a /etc/hosts
+   echo "127.0.0.1 network-node2-svc.solo.svc.cluster.local" | sudo tee -a /etc/hosts
+   echo "127.0.0.1 envoy-proxy-node2-svc.solo.svc.cluster.local" | sudo tee -a /etc/hosts
+   ```
+   
+   **Note:** This is required for dynamic address book tests to pass. Skip if you're only running other integration tests.
+
+4. **Run integration tests:**
+   ```bash
+   task test:integration
+   ```
+
+5. **Teardown when done:**
+   ```bash
+   task solo:teardown
+   ```
+
+For detailed setup instructions, troubleshooting, and advanced usage, see the [Solo Setup Guide](./manual/SOLO_SETUP.md).
+
+### Prerequisites
+
+Before setting up Solo, ensure you have:
+- Docker Desktop (or Docker Engine)
+- Kind (Kubernetes in Docker)
+- kubectl
+- Node.js v18+ (comes with npm/npx)
+
+See the [Solo Setup Guide](./manual/SOLO_SETUP.md#prerequisites) for installation instructions.
+
+## Running Tests
+
+### Unit Tests
+
+Unit tests do not require a local network and can be run directly:
+
+```bash
+task test:unit
+```
+
+Or separately for Node.js and browser:
+
+```bash
+task test:unit:node
+task test:unit:browser
+```
+
+### Integration Tests
+
+Integration tests require a running local network. After setting up Solo (see above):
+
+```bash
+# Run all integration tests
+task test:integration
+
+# Run Node.js integration tests only
+task test:integration:node
+
+# Run browser integration tests only
+task test:integration:browser
+
+# Run dual-mode tests
+task test:integration:dual-mode
+```
+
+#### Running Dynamic Address Book Tests
+
+Dynamic address book tests require the `/etc/hosts` configuration described in step 3 of the setup. These tests validate that the SDK can correctly handle node address changes and reconnections using Kubernetes service names.
+
+**Note:** All integration tests should pass reliably with the Solo setup. If you encounter failures:
+1. Verify Solo is running: `task solo:status`
+2. For dynamic address book test failures, ensure `/etc/hosts` is configured (see setup step 3)
+3. Check the troubleshooting section in the [Solo Setup Guide](./manual/SOLO_SETUP.md#troubleshooting)
+4. Try a fresh setup: `task solo:teardown && task solo:setup`
 
 ## Contributing