diff --git a/docs/pages/getting-started/_meta.json b/docs/pages/getting-started/_meta.json deleted file mode 100644 index 46e6ac21..00000000 --- a/docs/pages/getting-started/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "installation": "Installation", - "quick-start": "Quick Start", - "examples": "Examples" -} diff --git a/docs/pages/getting-started/address.mdx b/docs/pages/getting-started/address.mdx new file mode 100644 index 00000000..a5b80c81 --- /dev/null +++ b/docs/pages/getting-started/address.mdx @@ -0,0 +1,26 @@ +# Address + +Address module provides functionality for working with address types in Cardano. + +## Address Example + +```typescript +import { Address } from "@evolution-sdk/evolution" + +const hexAddress = "60ba1d6b6283c219a0530e3682c316215d55819cf97bbf26552c6f8530" +const expectedBech32 = "addr_test1vzap66mzs0ppngznpcmg9scky9w4tqvul9am7fj493hc2vq4ry02m" + +// Decode from hex +const address = Address.Codec.Decode.hex(hexAddress) + +// Encode to bech32 +const actualBech32 = Address.Codec.Encode.bech32(address) + +// Verify the conversion is correct +assert(actualBech32 === expectedBech32) + +``` + +## API Reference + +For detailed API documentation, see the generated TypeDoc documentation. \ No newline at end of file diff --git a/docs/pages/getting-started/data.mdx b/docs/pages/getting-started/data.mdx new file mode 100644 index 00000000..ac5e4821 --- /dev/null +++ b/docs/pages/getting-started/data.mdx @@ -0,0 +1,87 @@ +# Data + +Data module provides functionality for working with data types in Cardano. + +## Data Example + +```typescript +import { Data } from "@evolution-sdk/evolution" + +// Create a complex nested data structure with: +// - Constructor with index 1 containing multiple fields +// - Nested constructors with different indices +// - A Map with mixed key-value pairs +// - An array of numbers +const nestedUnsortedData = new Data.Constr({ + index: 1n, + fields: [ + // Nested constructor: 121_0([123_0([])]) + new Data.Constr({ + index: 0n, + fields: [ + new Data.Constr({ + index: 2n, + fields: [] + }) + ] + }), + // Map with unsorted keys (will be sorted in canonical mode) + new Map([ + ["deadbeef01", new Data.Constr({ index: 0n, fields: [] })], + ["beef", 19n], + ["deadbeef03", new Data.Constr({ index: 1n, fields: [] })] + ]), + // Array of numbers + [10n, 5n, 2n, 3n, 1n, 4n] + ] +}) + +// Encode using default codec (indefinite-length encoding) +const cborHex = Data.Codec().Encode.cborHex(nestedUnsortedData) +// Output: d87a9fd8799fd87b80ffbf45deadbeef01d8798042beef1345deadbeef03d87a80ff9f0a0502030104ffff + +// CBOR diagnostic notation (indefinite-length): +// 122_0([_ +// 121_0([_ 123_0([])]), +// {_ +// h'deadbeef01': 121_0([]), +// h'beef': 19, +// h'deadbeef03': 122_0([]), +// }, +// [_ 10, 5, 2, 3, 1, 4], +// ]) +// Visualize at: https://cbor.nemo157.com/ + +const decodedData = Data.Codec().Decode.cborHex(cborHex) + +// Create a canonical codec for deterministic encoding +// This ensures consistent output and sorted map keys +const canonicalCodec = Data.Codec({ + options: { + mode: "canonical" + } +}) + +// Encode using canonical mode (definite-length, sorted keys) +const canonicalCborHex = canonicalCodec.Encode.cborHex(nestedUnsortedData) +// Output: d87a83d87981d87b80a342beef1345deadbeef01d8798045deadbeef03d87a80860a0502030104 + +// CBOR diagnostic notation (canonical/definite-length): +// 122_0([ +// 121_0([123_0([])]), +// { +// h'beef': 19, ← Keys are now sorted +// h'deadbeef01': 121_0([]), +// h'deadbeef03': 122_0([]), +// }, +// [10, 5, 2, 3, 1, 4], ← Definite-length array +// ]) + +// Verify that decoding works correctly +assert.deepStrictEqual(decodedData, nestedUnsortedData, "Decoded data should match original") + +``` + +## API Reference + +For detailed API documentation, see the generated TypeDoc documentation. \ No newline at end of file diff --git a/docs/pages/getting-started/examples.mdx b/docs/pages/getting-started/examples.mdx deleted file mode 100644 index c71444f4..00000000 --- a/docs/pages/getting-started/examples.mdx +++ /dev/null @@ -1,245 +0,0 @@ -# Examples - -Comprehensive examples showing how to use Evolution SDK for common Cardano development tasks. - -## Address Validation and Analysis - -### Validating Different Address Types - -```typescript -import * as PaymentAddress from "@evolution-sdk/evolution/PaymentAddress" -import * as RewardAddress from "@evolution-sdk/evolution/RewardAddress" - -// Collection of different address types from mainnet and testnet -const addresses = { - // Mainnet addresses - mainnet: { - base: "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x", - enterprise: "addr1vx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer66hrl8", - pointer: "addr1gx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer5pnz75xxcrzqf96k", - reward: "stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw" - }, - // Testnet addresses - testnet: { - base: "addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgs68faae", - enterprise: "addr_test1vz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzerspjrlsz", - pointer: "addr_test1gz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer5pnz75xxcrdw5vky", - reward: "stake_test1uqehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gssrtvn" - } -} - -// Validate payment addresses (base, enterprise, pointer) -function validatePaymentAddresses() { - const paymentAddresses = [ - addresses.mainnet.base, - addresses.mainnet.enterprise, - addresses.mainnet.pointer, - addresses.testnet.base, - addresses.testnet.enterprise, - addresses.testnet.pointer - ] - - paymentAddresses.forEach((address) => { - const isValid = PaymentAddress.isPaymentAddress(address) - console.log(`${address.substring(0, 20)}... is payment address: ${isValid}`) - }) -} - -// Validate reward addresses -function validateRewardAddresses() { - const rewardAddresses = [addresses.mainnet.reward, addresses.testnet.reward] - - rewardAddresses.forEach((address) => { - const isValid = RewardAddress.isRewardAddress(address) - console.log(`${address.substring(0, 20)}... is reward address: ${isValid}`) - }) -} - -validatePaymentAddresses() -validateRewardAddresses() -``` - -## Address Format Conversion - -### Working with Hex and Bech32 Formats - -```typescript -import * as Address from "@evolution-sdk/evolution/Address" - -// Sample hex addresses from the Cardano blockchain -const validHexAddresses = [ - "019493315cd92eb5d8c4304e67b7e16ae36d61d34502694657811a2c8e337b62cfff6403a06a3acbc34f8c46003c69fe79a3628cefa9c47251", - "60ba1d6b6283c219a0530e3682c316215d55819cf97bbf26552c6f8530" -] - -function demonstrateConversion() { - validHexAddresses.forEach((hex) => { - try { - // Decode from hex - const address = Address.Codec.Decode.hex(hex) - console.log(`Decoded address from hex: ${hex.substring(0, 20)}...`) - - // Encode to bech32 - const bech32 = Address.Codec.Encode.bech32(address) - console.log(`Bech32 format: ${bech32}`) - - // Round-trip back to hex - const backToHex = Address.Codec.Encode.hex(address) - console.log(`Round-trip successful: ${backToHex === hex}`) - console.log("---") - } catch (error) { - console.error(`Failed to process hex: ${hex}`, error) - } - }) -} - -demonstrateConversion() -``` - -### Specific Hex to Bech32 Example - -```typescript -import * as Address from "@evolution-sdk/evolution/Address" - -// Real example from Cardano testnet -const hexAddress = "60ba1d6b6283c219a0530e3682c316215d55819cf97bbf26552c6f8530" -const expectedBech32 = "addr_test1vzap66mzs0ppngznpcmg9scky9w4tqvul9am7fj493hc2vq4ry02m" - -const address = Address.Codec.Decode.hex(hexAddress) -const actualBech32 = Address.Codec.Encode.bech32(address) - -console.log(`Input hex: ${hexAddress}`) -console.log(`Expected: ${expectedBech32}`) -console.log(`Actual: ${actualBech32}`) -console.log(`Match: ${actualBech32 === expectedBech32}`) -``` - -## Data Type Validation - -### Working with PlutusData Types - -```typescript -import * as Data from "@evolution-sdk/evolution/Data" - -// Create a codec for data operations -const codec = Data.Codec() - -// Valid hex examples (even-length hex strings) -const validHexCases = ["deadbeef", "cafe0123", "abcdef0123456789", "00", "ff"] - -// Invalid hex examples -const invalidHexCases = [ - "not-hex", - "xyz", - "123g", - "deadbeef ", // trailing space - " deadbeef", // leading space - "0x123456" // hex prefix not allowed -] - -function validateHexData() { - console.log("Valid hex data:") - validHexCases.forEach((hex) => { - const isValid = Data.isBytes(hex) - console.log(`"${hex}" -> ${isValid}`) - }) - - console.log("\nInvalid hex data:") - invalidHexCases.forEach((hex) => { - const isValid = Data.isBytes(hex) - console.log(`"${hex}" -> ${isValid}`) - }) -} - -validateHexData() -``` - -## Error Handling Patterns - -### Safe Address Operations with Effect - -```typescript -import { Effect } from "effect" -import * as Address from "@evolution-sdk/evolution/Address" - -// Safe address decoding with error handling -function safeAddressOperations() { - const addresses = [ - "60ba1d6b6283c219a0530e3682c316215d55819cf97bbf26552c6f8530", // valid - "invalid-hex-address", // invalid - "019493315cd92eb5d8c4304e67b7e16ae36d61d34502694657811a2c8e337b62cfff6403a06a3acbc34f8c46003c69fe79a3628cefa9c47251" // valid - ] - - addresses.forEach((hex) => { - const program = Effect.gen(function* () { - // Try to decode the address - const address = yield* Effect.try(() => Address.Codec.Decode.hex(hex)) - - // If successful, convert to bech32 - const bech32 = Address.Codec.Encode.bech32(address) - - return { - success: true, - input: hex, - output: bech32 - } - }) - - // Handle the result - Effect.runPromise(program) - .then((result) => { - console.log(`✅ Success: ${result.input.substring(0, 20)}... -> ${result.output}`) - }) - .catch((error) => { - console.log(`❌ Failed: ${hex.substring(0, 20)}... -> ${error.message || "Invalid address"}`) - }) - }) -} - -safeAddressOperations() -``` - -### Batch Address Validation - -```typescript -import * as PaymentAddress from "@evolution-sdk/evolution/PaymentAddress" -import * as RewardAddress from "@evolution-sdk/evolution/RewardAddress" - -// Mixed collection of valid and invalid addresses -const testAddresses = [ - "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x", - "stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw", - "not-an-address", - "addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgs68faae", - "stake_test1uqehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gssrtvn" -] - -function batchValidation() { - const results = testAddresses.map((address) => { - const isPayment = PaymentAddress.isPaymentAddress(address) - const isReward = RewardAddress.isRewardAddress(address) - - let type = "invalid" - if (isPayment) type = "payment" - else if (isReward) type = "reward" - - return { - address: address.substring(0, 30) + "...", - type, - valid: isPayment || isReward - } - }) - - console.log("Batch validation results:") - console.table(results) -} - -batchValidation() -``` - -## Next Steps - -- Check out the [API Reference](/api) for complete documentation -- Learn about [Address Types](/getting-started/address-types) in detail -- Explore [Advanced Usage](/guides/advanced) patterns -- View the [Test Suite](https://github.com/your-repo/tests) for more examples diff --git a/docs/pages/getting-started/installation.mdx b/docs/pages/getting-started/installation.mdx deleted file mode 100644 index 812b7daa..00000000 --- a/docs/pages/getting-started/installation.mdx +++ /dev/null @@ -1,73 +0,0 @@ -# Installation - -## Prerequisites - -- Node.js 18+ -- TypeScript 5+ -- A package manager (npm, yarn, or pnpm) - -## Package Manager Installation - -### npm - -```bash -npm install @evolution-sdk/evolution -``` - -### yarn - -```bash -yarn add @evolution-sdk/evolution -``` - -### pnpm - -```bash -pnpm add @evolution-sdk/evolution -``` - -## Development Dependencies - -If you're contributing to the SDK or need development dependencies: - -```bash -# Clone the repository -git clone https://github.com/no-witness-labs/evolution-sdk.git -cd evolution-sdk - -# Install dependencies -pnpm install - -# Build the project -pnpm build - -# Run tests -pnpm test -``` - -## TypeScript Configuration - -Evolution SDK requires TypeScript 5+ with strict mode enabled. Add to your `tsconfig.json`: - -```json -{ - "compilerOptions": { - "strict": true, - "target": "ES2022", - "moduleResolution": "node", - "allowSyntheticDefaultImports": true, - "esModuleInterop": true - } -} -``` - -## Verify Installation - -Create a simple test file to verify the installation: - -```typescript -import { Network, Address } from "@evolution-sdk/evolution" - -console.log("Evolution SDK installed successfully!") -console.log("Mainnet ID:", Network.toId("Mainnet")) -``` diff --git a/docs/pages/getting-started/quick-start.mdx b/docs/pages/getting-started/quick-start.mdx deleted file mode 100644 index 540f3446..00000000 --- a/docs/pages/getting-started/quick-start.mdx +++ /dev/null @@ -1,135 +0,0 @@ -# Quick Start - -Get up and running with Evolution SDK in minutes. - -## Installation - -First, install the Evolution SDK in your project: - -```bash -npm install @evolution-sdk/evolution -# or -yarn add @evolution-sdk/evolution -# or -pnpm add @evolution-sdk/evolution -``` - -## Basic Usage - -### Working with Cardano Addresses - -```typescript -import * as Address from "@evolution-sdk/evolution/Address" -import * as PaymentAddress from "@evolution-sdk/evolution/PaymentAddress" -import * as RewardAddress from "@evolution-sdk/evolution/RewardAddress" - -// Sample mainnet addresses from the Cardano blockchain -const mainnetBaseAddress = - "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x" -const mainnetRewardAddress = "stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw" - -// Sample testnet addresses -const testnetBaseAddress = - "addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgs68faae" -const testnetRewardAddress = "stake_test1uqehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gssrtvn" - -// Validate payment addresses -console.log(PaymentAddress.isPaymentAddress(mainnetBaseAddress)) // true -console.log(PaymentAddress.isPaymentAddress(mainnetRewardAddress)) // false - -// Validate reward addresses -console.log(RewardAddress.isRewardAddress(mainnetRewardAddress)) // true -console.log(RewardAddress.isRewardAddress(mainnetBaseAddress)) // false -``` - -### Address Format Conversion - -```typescript -import * as Address from "@evolution-sdk/evolution/Address" - -// Convert between hex and bech32 formats -const hexAddress = "60ba1d6b6283c219a0530e3682c316215d55819cf97bbf26552c6f8530" -const expectedBech32 = "addr_test1vzap66mzs0ppngznpcmg9scky9w4tqvul9am7fj493hc2vq4ry02m" - -// Decode from hex -const address = Address.Codec.Decode.hex(hexAddress) - -// Encode to bech32 -const actualBech32 = Address.Codec.Encode.bech32(address) -console.log(actualBech32 === expectedBech32) // true - -// Round-trip conversion -const backToHex = Address.Codec.Encode.hex(address) -console.log(backToHex === hexAddress) // true -``` - -### Working with Different Address Types - -```typescript -// Base address (payment key hash + stake key hash) -const baseAddress = - "addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgse35a3x" - -// Enterprise address (payment key hash only) -const enterpriseAddress = "addr1vx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzers66hrl8" - -// Pointer address (payment key hash + pointer) -const pointerAddress = "addr1gx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer5pnz75xxcrzqf96k" - -// Reward address (stake key hash) -const rewardAddress = "stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw" - -// Each address type serves different purposes in the Cardano ecosystem -console.log("All addresses are valid Cardano addresses") -``` - -### Working with Data Types - -```typescript -import * as Data from "@evolution-sdk/evolution/Data" - -// Create a codec for encoding/decoding data -const codec = Data.Codec() - -// Working with hex data -const validHex = "deadbeef" -const isValidBytes = Data.isBytes(validHex) // true - -// Invalid hex examples -const invalidHex = "not-hex" -const isInvalidBytes = Data.isBytes(invalidHex) // false -``` - -## Error Handling - -Evolution SDK uses Effect-TS for robust error handling. Most operations return an `Effect` that can either succeed or fail: - -```typescript -import { Effect } from "effect" -import * as Address from "@evolution-sdk/evolution/Address" - -// Operations that might fail are wrapped in Effect -const program = Effect.gen(function* () { - // This will succeed with a valid address - const validAddress = yield* Effect.try(() => - Address.Codec.Decode.hex("60ba1d6b6283c219a0530e3682c316215d55819cf97bbf26552c6f8530") - ) - - // Convert to bech32 format - const bech32 = Address.Codec.Encode.bech32(validAddress) - - return bech32 -}) - -// Run the program -Effect.runPromise(program) - .then((result) => console.log("Address:", result)) - .catch((error) => console.error("Error:", error)) -``` - -## Next Steps - -- Explore the [API Reference](/api) for detailed documentation -- Learn about [Address Types](/getting-started/address-types) for more details -- Check out more [Examples](/getting-started/examples) for complex use cases -- Read the [Guides](/guides) for specific development scenarios diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index fcd5ab86..151d441c 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -6,39 +6,6 @@ A comprehensive TypeScript SDK for Cardano blockchain development, built with Ef Evolution SDK provides a type-safe, functional programming approach to Cardano blockchain development. Built on top of Effect-TS, it offers: -- **Type Safety**: Full TypeScript support with comprehensive type definitions -- **CBOR Support**: Native CBOR encoding/decoding for Cardano data structures -- **Effect Integration**: Leverages Effect-TS for error handling and composability -- **Address Management**: Support for all Cardano address types -- **Transaction Building**: Tools for constructing and signing transactions -- **Plutus Data**: Native support for Plutus data structures - -## Quick Start - -```bash -npm install @evolution-sdk/evolution -``` - -```typescript -import { Address, Network } from "@evolution-sdk/evolution" - -// Create a base address -const baseAddr = Address.Base.make({ - network: Network.Mainnet, - paymentCredential: paymentCred, - stakeCredential: stakeCred -}) -``` - -## Features - -- 🏗️ **Address Utilities** - Create and validate all Cardano address types -- 🔐 **Cryptographic Primitives** - Ed25519 signatures, VRF, KES -- 📦 **CBOR Encoding** - RFC 8949 compliant CBOR implementation -- 🏛️ **Governance** - DRep, committee, and voting procedure support -- 🌐 **Network Configuration** - Support for all Cardano networks -- 🪙 **Native Tokens** - Multi-asset and minting utilities - ## Architecture Evolution SDK is designed around functional programming principles: diff --git a/docs/pages/reference/index.mdx b/docs/pages/reference/index.mdx deleted file mode 100644 index d77a4411..00000000 --- a/docs/pages/reference/index.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Home -nav_order: 1 ---- diff --git a/docs/pages/reference/test.mdx b/docs/pages/reference/test.mdx deleted file mode 100644 index 30f50e67..00000000 --- a/docs/pages/reference/test.mdx +++ /dev/null @@ -1,11 +0,0 @@ -# Test API Module - -This is a test to see if the API navigation is working. - -## Test Function - -```typescript -function test() { - return "Hello from the API docs!"; -} -```