Merge pull request #54 from IntersectMBO/docs/update-address

docs: expand address, provider, wallet, and client guides

Author: solidsnakedev

.gitignore

@@ -7,6 +7,7 @@ dist
 .direnv
 docs/out
 docs/.next
+docs/.twoslash
 # TypeScript incremental compilation cache
 *.tsbuildinfo
 .tsbuildinfo/

docs/app/provider.tsx

@@ -1,5 +1,5 @@
 "use client"
-import { RootProvider } from "fumadocs-ui/provider"
+import { RootProvider } from "fumadocs-ui/provider/next"
 // your custom dialog
 import SearchDialog from "@/components/search"
 import type { ReactNode } from "react"

docs/content/docs/addresses/base.mdx

@@ -0,0 +1,103 @@
+---
+title: Base Addresses
+description: Standard Cardano addresses with payment and staking credentials
+---
+
+# Base Addresses
+
+Base addresses are the most common address type on Cardano. They contain both a payment credential (for spending funds) and a staking credential (for delegation and rewards).
+
+## Structure
+
+```
+Base Address = Payment Credential + Staking Credential
+```
+
+**Payment Credential**: Controls who can spend UTXOs at this address  
+**Staking Credential**: Controls delegation and receives staking rewards
+
+Both credentials are typically derived from the same wallet, but can come from different sources (see [Franken Addresses](/docs/addresses/franken)).
+
+## When to Use
+
+- **Standard addresses**: Most common address type
+- **Staking-enabled applications**: When you want automatic staking rewards
+- **General purpose**: Default for most scenarios
+
+## Manual Construction
+
+Create base addresses by instantiating the `BaseAddress` class:
+
+```ts twoslash
+import { BaseAddress, KeyHash, Address } from "@evolution-sdk/evolution";
+
+const address = new BaseAddress.BaseAddress({
+  networkId: 1, // mainnet
+  paymentCredential: new KeyHash.KeyHash({
+    hash: new Uint8Array(28)
+  }),
+  stakeCredential: new KeyHash.KeyHash({
+    hash: new Uint8Array(28)
+  })
+});
+
+// Convert to Bech32 string
+const bech32 = Address.toBech32(address);
+console.log(bech32); // "addr1..."
+```
+
+## Parsing Existing Addresses
+
+Parse a Bech32 address string into a `BaseAddress` instance:
+
+```ts twoslash
+import { Address, BaseAddress } from "@evolution-sdk/evolution";
+
+const bech32 = "addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd";
+
+const address = Address.fromBech32(bech32) as BaseAddress.BaseAddress;
+
+console.log("Network ID:", address.networkId);
+console.log("Payment:", address.paymentCredential);
+console.log("Stake:", address.stakeCredential);
+```
+
+## Address Components
+
+### Payment Credential
+- **Purpose**: Spending authorization
+- **Type**: Key hash (28 bytes) or script hash (28 bytes)
+- **Usage**: Required to sign spending transactions
+
+### Staking Credential
+- **Purpose**: Delegation and rewards
+- **Type**: Key hash (28 bytes) or script hash (28 bytes)
+- **Usage**: Required to delegate stake or withdraw rewards
+
+## Format Details
+
+**Bech32 Prefix**: `addr` (mainnet) or `addr_test` (testnet)  
+**Size**: 57 bytes on-chain
+
+## Best Practices
+
+**Default Choice**: Use base addresses unless you have a specific reason not to. They enable staking rewards with no extra effort.
+
+**Delegation**: Base addresses automatically support stake delegation. Users can earn rewards while keeping funds liquid.
+
+**Key Separation**: Payment and stake keys can be rotated independently if needed (advanced use case).
+
+## Security Considerations
+
+**Key Management**: Both payment and stake keys must be secured. Loss of payment key = loss of funds. Loss of stake key = loss of delegation control.
+
+**Delegation**: Staking is non-custodial. Delegating stake does NOT give the stake pool operator access to your funds.
+
+**Withdrawal**: Only the stake key holder can withdraw rewards. This is separate from spending funds (payment key).
+
+## Next Steps
+
+- **[Enterprise Addresses](/docs/addresses/enterprise)** - Payment only, no staking
+- **[Reward Addresses](/docs/addresses/reward)** - Stake only, for withdrawing rewards
+- **[Franken Addresses](/docs/addresses/franken)** - Hybrid construction patterns
+- **[Address Construction](/docs/addresses/construction)** - Advanced building techniques

docs/content/docs/addresses/conversion.mdx

@@ -1,8 +1,159 @@
 ---
 title: Address Conversion
-description: Convert between different address formats
+description: Convert between different address formats using Core AddressStructure
 ---
 
 # Address Conversion
 
-Content coming soon.
+The Core `AddressStructure` module provides transformations between different address representations: Bech32 strings, hexadecimal, and raw bytes.
+
+## Available Formats
+
+### Bech32 (Human-Readable)
+
+Standard format used in wallets and explorers:
+- Mainnet base: `addr1...`
+- Testnet base: `addr_test1...`
+- Mainnet reward: `stake1...`
+- Testnet reward: `stake_test1...`
+
+### Hexadecimal
+
+Hex-encoded bytes, useful for low-level operations and debugging.
+
+### Raw Bytes
+
+Binary format (Uint8Array), used internally and for serialization.
+
+## Conversion Examples
+
+### Bech32 ↔ AddressStructure
+
+```typescript twoslash
+import { Address, BaseAddress } from "@evolution-sdk/evolution";
+
+const bech32 = "addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd";
+
+// Parse Bech32 string to address
+const address = Address.fromBech32(bech32) as BaseAddress.BaseAddress;
+
+console.log("Network ID:", address.networkId);
+console.log("Payment credential:", address.paymentCredential);
+console.log("Staking credential:", address.stakeCredential);
+
+// Convert address back to Bech32
+const encoded = Address.toBech32(address);
+console.log("Bech32:", encoded);
+// Same as original: addr1qx2kd28nq8ac5prwg32hhvudlwggpgfp8utlyqxu6wqgz62f79qsdmm5dsknt9ecr5w468r9ey0fxwkdrwh08ly3tu9sy0f4qd
+```
+
+### Hex ↔ AddressStructure
+
+```typescript twoslash
+import { Address } from "@evolution-sdk/evolution";
+
+const hexAddress = "019493315cd92eb5d8c4304e67b7e16ae36d61d34502694657811a2c8e32c728d3861e164cab28cb8f006448139c8f1740ffb8e7aa9e5232dc";
+
+// Parse hex to address
+const address = Address.fromHex(hexAddress);
+
+console.log("Parsed from hex:", address);
+
+// Convert address to hex
+const hex = Address.toHex(address);
+console.log("Hex:", hex);
+```
+
+### Bytes ↔ AddressStructure
+
+```typescript twoslash
+import { BaseAddress, KeyHash, Address } from "@evolution-sdk/evolution";
+
+// Create an address structure
+const address = new BaseAddress.BaseAddress({
+  networkId: 1,
+  paymentCredential: new KeyHash.KeyHash({
+    hash: new Uint8Array(28)
+  }),
+  stakeCredential: new KeyHash.KeyHash({
+    hash: new Uint8Array(28)
+  })
+});
+
+// Convert to raw bytes
+const bytes = Address.toBytes(address);
+console.log("Bytes length:", bytes.length); // 57 for base address
+
+// Parse from bytes
+const decoded = Address.fromBytes(bytes);
+console.log("Decoded:", decoded);
+```
+
+## Chain Conversions
+
+Combine transformations for multi-step conversions:
+
+### Bech32 → Hex
+
+```typescript twoslash
+import { Address } from "@evolution-sdk/evolution";
+
+const bech32 = "addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3jcu5d8ps7zex2k2xt3uqxgjqnnj83ws8lhrn648jjxtwq2ytjqp";
+
+// Parse from Bech32
+const address = Address.fromBech32(bech32);
+
+// Convert to hex
+const hex = Address.toHex(address);
+console.log("Hex:", hex);
+```
+
+### Hex → Bech32
+
+```typescript twoslash
+import { Address } from "@evolution-sdk/evolution";
+
+const hex = "009493315cd92eb5d8c4304e67b7e16ae36d61d34502694657811a2c8e32c728d3861e164cab28cb8f006448139c8f1740ffb8e7aa9e5232dc";
+
+// Parse from hex
+const address = Address.fromHex(hex);
+
+// Convert to Bech32
+const bech32 = Address.toBech32(address);
+console.log("Bech32:", bech32);
+```
+
+## Best Practices
+
+**Use Bech32 for Display**: Always show users Bech32-encoded addresses. They're human-readable and include error detection.
+
+**Use Bytes Internally**: For storage and serialization, raw bytes are most efficient.
+
+**Validate After Conversion**: Always validate addresses after parsing from external sources.
+
+**Network Awareness**: Verify the network ID matches your expected environment (mainnet vs testnet).
+
+## Error Handling
+
+Conversions can fail with invalid input:
+
+```typescript twoslash
+import { Address } from "@evolution-sdk/evolution";
+
+const invalidBech32 = "invalid_address";
+
+// Error handling with try-catch
+try {
+  const address = Address.fromBech32(invalidBech32);
+  console.log("Parsed address:", address);
+} catch (error) {
+  console.error("Failed to parse address:", error);
+}
+```
+
+## Next Steps
+
+- [Address Validation](/docs/addresses/validation) - Verify address correctness
+- [Address Construction](/docs/addresses/construction) - Build addresses from scratch
+- [Base Addresses](/docs/addresses/base) - Understanding base address structure
+- [Enterprise Addresses](/docs/addresses/enterprise) - Enterprise address format