docs: add comprehensive JSDoc and README for Mesh SDK exports

packages/mesh-common/README.md

@@ -1,5 +1,184 @@
-# mesh-common
+# @meshsdk/common
 
-Contains constants, types and interfaces used across the SDK and different serialization libraries
+Shared types, interfaces, and utilities for the Mesh SDK. This package defines the common contracts (interfaces) and data types used across all Mesh packages.
 
-[meshjs.dev](https://meshjs.dev/)
+## Installation
+
+```bash
+npm install @meshsdk/common
+```
+
+## Overview
+
+`@meshsdk/common` is the foundational package of the Mesh SDK. It contains:
+
+- **Interfaces** — `IFetcher`, `ISubmitter`, `IEvaluator`, `IWallet`, `ISigner`
+- **Types** — All Cardano data structure types (`UTxO`, `Asset`, `Protocol`, `PlutusData`, etc.)
+- **Constants** — Network IDs, well-known asset unit strings
+- **Utilities** — Shared helper functions for data conversion
+
+## Core Interfaces
+
+### `IFetcher`
+
+Interface for providers that can fetch chain data.
+
+```typescript
+import type { IFetcher } from '@meshsdk/common';
+
+class MyProvider implements IFetcher {
+  async fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]> {
+    // implementation
+  }
+
+  async fetchProtocolParameters(epoch?: number): Promise<Protocol> {
+    // implementation
+  }
+
+  // ... other methods
+}
+```
+
+**Methods:**
+
+| Method | Description |
+|---|---|
+| `fetchAddressUTxOs(address, asset?)` | Fetch UTxOs at an address |
+| `fetchAssetAddresses(asset)` | Fetch addresses holding an asset |
+| `fetchAssetMetadata(asset)` | Fetch on-chain metadata for an asset |
+| `fetchBlockInfo(hash)` | Fetch block information |
+| `fetchCollectionAssets(policyId, cursor?)` | Paginate assets in a policy |
+| `fetchHandleAddress(handle)` | Resolve ADA Handle to address |
+| `fetchProtocolParameters(epoch?)` | Fetch protocol parameters |
+| `fetchTxInfo(hash)` | Fetch transaction details |
+| `fetchUTxOs(hash, index?)` | Fetch UTxOs by tx hash |
+
+### `ISubmitter`
+
+Interface for providers that can submit transactions.
+
+```typescript
+import type { ISubmitter } from '@meshsdk/common';
+
+class MyProvider implements ISubmitter {
+  async submitTx(tx: string): Promise<string> {
+    // Submit CBOR-encoded transaction, return tx hash
+  }
+}
+```
+
+### `IEvaluator`
+
+Interface for providers that can evaluate script execution units.
+
+```typescript
+import type { IEvaluator } from '@meshsdk/common';
+
+class MyProvider implements IEvaluator {
+  async evaluateTx(tx: string): Promise<Omit<Action, 'data'>[]> {
+    // Evaluate Plutus script execution units
+  }
+}
+```
+
+### `IWallet`
+
+Interface for wallet implementations providing signing and transaction capabilities.
+
+**Key Methods:**
+
+| Method | Description |
+|---|---|
+| `getBalance()` | Get wallet balance as asset list |
+| `getChangeAddress()` | Get the change address |
+| `getCollateral()` | Get collateral UTxOs |
+| `getNetworkId()` | Get network ID (0=testnet, 1=mainnet) |
+| `getUtxos()` | Get all wallet UTxOs |
+| `signData(address, payload)` | Sign arbitrary data (CIP-8) |
+| `signTx(unsignedTx, partialSign?)` | Sign a transaction |
+| `submitTx(tx)` | Submit a signed transaction |
+
+## Common Types
+
+### `UTxO`
+
+```typescript
+interface UTxO {
+  input: {
+    outputIndex: number;
+    txHash: string;
+  };
+  output: {
+    address: string;
+    amount: Asset[];
+    dataHash?: string;
+    plutusData?: string;
+    scriptRef?: string;
+    scriptHash?: string;
+  };
+}
+```
+
+### `Asset`
+
+```typescript
+interface Asset {
+  unit: string;     // 'lovelace' or concatenation of policyId + assetNameHex
+  quantity: string; // Amount as string to handle large integers
+}
+```
+
+### `Protocol`
+
+Represents Cardano protocol parameters including:
+- `minFeeA`, `minFeeB` — Fee calculation coefficients
+- `maxTxSize` — Maximum transaction size in bytes
+- `maxValSize` — Maximum value size
+- `keyDeposit` — Key registration deposit in lovelace
+- `poolDeposit` — Pool registration deposit in lovelace
+- `coinsPerUtxoSize` — Minimum UTxO value calculation
+- `priceMem`, `priceStep` — Plutus execution unit prices
+- `collateralPercent` — Required collateral percentage
+- `maxCollateralInputs` — Maximum collateral inputs
+
+### `PlutusData`
+
+Union type representing all Plutus data constructors:
+- `ConStr` — Constructor with fields
+- `Integer` — Integer value
+- `ByteString` — Hex-encoded byte string
+- `List` — List of Plutus data
+- `Map` — Map of Plutus data key-value pairs
+
+### `Action` (Redeemer)
+
+```typescript
+interface Action {
+  index: number;     // Script input/mint index
+  budget: Budget;    // Execution units { mem: number, steps: number }
+  tag: RedeemerTag;  // 'SPEND' | 'MINT' | 'CERT' | 'REWARD'
+  data: Data;        // Redeemer data
+}
+```
+
+## Utility Functions
+
+### Asset Helpers
+
+- `parseAssetUnit(unit: string): { policyId: string; assetName: string }` — Split an asset unit into policy ID and asset name
+- `mergeAssets(assets: Asset[]): Asset[]` — Merge duplicate asset entries by summing quantities
+
+### Serialization Helpers
+
+- `fromUTF8(utf8: string): string` — Convert UTF-8 string to hex
+- `toUTF8(hex: string): string` — Convert hex string to UTF-8
+- `fromBytes(bytes: Uint8Array): string` — Convert byte array to hex string
+- `toBytes(hex: string): Uint8Array` — Convert hex string to byte array
+
+## Contributing
+
+Please read the [Contributing Guide](../../CONTRIBUTING.md) before submitting pull requests.
+
+## License
+
+[Apache License 2.0](../../LICENSE.md)

packages/mesh-core-cst/README.md

@@ -1,5 +1,97 @@
-# mesh-core-cst
+# @meshsdk/core-cst
 
-Types and utilities functions between Mesh and [cardano-js-sdk](https://github.com/input-output-hk/cardano-js-sdk)
+Cardano Serialization Tools (CST) package for Mesh SDK, built on top of `@cardano-sdk/*` and `@harmoniclabs/*` libraries. This package provides low-level serialization and deserialization utilities for Cardano blockchain data structures.
 
-[meshjs.dev](https://meshjs.dev/)
+## Installation
+
+```bash
+npm install @meshsdk/core-cst
+```
+
+## Overview
+
+This package is part of the [Mesh SDK](https://meshjs.dev/) ecosystem and serves as the core serialization layer using the Cardano SDK and HarmonicLabs libraries. It provides:
+
+- **Type conversions** between Mesh internal types and Cardano SDK types
+- **Transaction serialization** and deserialization utilities
+- **Address utilities** for Cardano address handling
+- **Cryptographic utilities** for key management and signing
+- **Plutus data** serialization helpers
+
+## Usage
+
+```typescript
+import {
+  deserializeTx,
+  serializeTx,
+  toAddress,
+  fromAddress,
+  toPlutusData,
+} from '@meshsdk/core-cst';
+
+// Deserialize a CBOR-encoded transaction
+const tx = deserializeTx(cborHex);
+
+// Convert a bech32 address to Mesh Address type
+const address = toAddress('addr1...');
+```
+
+## API Reference
+
+### Transaction Utilities
+
+#### `deserializeTx(tx: string): Transaction`
+
+Deserializes a CBOR-encoded transaction hex string into a `Transaction` object.
+
+**Parameters:**
+- `tx` — CBOR hex string of the serialized transaction
+
+**Returns:** Deserialized `Transaction` object
+
+#### `serializeTx(tx: Transaction): string`
+
+Serializes a `Transaction` object into a CBOR-encoded hex string.
+
+**Parameters:**
+- `tx` — The `Transaction` object to serialize
+
+**Returns:** CBOR hex string
+
+### Address Utilities
+
+#### `toAddress(address: string): MeshAddress`
+
+Converts a bech32 or hex-encoded Cardano address into a Mesh `Address` object.
+
+**Parameters:**
+- `address` — bech32 or hex address string
+
+**Returns:** Mesh `Address` object
+
+#### `fromAddress(address: MeshAddress): string`
+
+Converts a Mesh `Address` object back to a bech32 string.
+
+**Parameters:**
+- `address` — Mesh `Address` object
+
+**Returns:** bech32 address string
+
+### Plutus Data Utilities
+
+#### `toPlutusData(data: PlutusData): CstPlutusData`
+
+Converts Mesh `PlutusData` into the Cardano SDK `PlutusData` format.
+
+#### `fromPlutusData(data: CstPlutusData): PlutusData`
+
+Converts Cardano SDK `PlutusData` into the Mesh `PlutusData` format.
+
+## Contributing
+
+Please read the [Contributing Guide](../../CONTRIBUTING.md) before submitting pull requests.
+
+## License
+
+[Apache License 2.0](../../LICENSE.md)