Merge pull request #98 from IntersectMBO/feat/add-utxo-core

feat: create core utxo

Author: solidsnakedev

.changeset/cruel-rice-sort.md

@@ -0,0 +1,50 @@
+---
+"@evolution-sdk/devnet": patch
+"@evolution-sdk/evolution": patch
+---
+
+Migrate transaction builder and provider layer to use Core UTxO types throughout the SDK.
+
+### New Core Types
+
+- **`Core.UTxO`** — Schema-validated UTxO with branded types (`TransactionHash`, `Address`, `Assets`)
+- **`Core.Assets`** — Enhanced with `merge`, `subtract`, `negate`, `getAsset`, `setAsset`, `hasAsset` operations
+- **`Core.Time`** — New module for slot/time conversions with `SlotConfig`, `Slot`, `UnixTime`
+- **`Core.Address`** — Added `getAddressDetails`, `getPaymentCredential`, `getStakingCredential` utilities
+
+### SDK Changes
+
+- Provider methods (`getUtxos`, `getUtxoByUnit`, `getUtxosWithUnit`) now return `Core.UTxO.UTxO[]`
+- Client methods (`getWalletUtxos`, `newTx`) use Core UTxO internally
+- Transaction builder accepts `Core.UTxO.UTxO[]` for `availableUtxos`
+- `Genesis.calculateUtxosFromConfig` and `Genesis.queryUtxos` return Core UTxOs
+
+### Rationale
+
+The SDK previously used a lightweight `{ txHash, outputIndex, address, assets }` record for UTxOs, requiring constant conversions when interfacing with the Core layer (transaction building, CBOR serialization). This caused:
+
+1. **Conversion overhead** — Every transaction build required converting SDK UTxOs to Core types
+2. **Type ambiguity** — `txHash: string` vs `TransactionHash`, `address: string` vs `Address` led to runtime errors
+3. **Inconsistent APIs** — Some methods returned Core types, others SDK types
+
+By standardizing on Core UTxO:
+
+- **Zero conversion** — UTxOs flow directly from provider → wallet → builder → transaction
+- **Type safety** — Branded types prevent mixing up transaction hashes, addresses, policy IDs
+- **Unified model** — Single UTxO representation across the entire SDK
+
+### Migration
+
+```typescript
+// Before
+const lovelace = Assets.getAsset(utxo.assets, "lovelace")
+const txId = utxo.txHash
+const idx = utxo.outputIndex
+const addr = utxo.address // string
+
+// After  
+const lovelace = utxo.assets.lovelace
+const txId = Core.TransactionHash.toHex(utxo.transactionId)
+const idx = utxo.index // bigint
+const addr = Core.Address.toBech32(utxo.address) // or use Address directly
+```

docs/content/docs/clients/architecture.mdx

@@ -34,25 +34,27 @@ interface ReadOnlyWalletConfig {
 ```typescript twoslash
 import { createClient, Core } from "@evolution-sdk/evolution";
 
-// Backend: read-only wallet with user's address (from frontend)
-const backendClient = createClient({
+// Backend: Create provider client, then attach read-only wallet
+const providerClient = createClient({
   network: "mainnet",
   provider: {
     type: "blockfrost",
     baseUrl: "https://cardano-mainnet.blockfrost.io/api/v0",
     projectId: process.env.BLOCKFROST_PROJECT_ID!
-  },
-  wallet: {
-    type: "read-only",
-    address: "addr1qz8eg0aknl96hd3v6x3qfmmz5zhtrq5hn8hmq0x4qd6m2qdppx88rnw3eumv9zv2ctjns05c8jhsqwg98qaxcz2qh45qhjv39c"
   }
 });
 
+// Attach user's address as read-only wallet (expects bech32 string)
+const backendClient = providerClient.attachWallet({
+  type: "read-only",
+  address: "addr1qz8eg0aknl96hd3v6x3qfmmz5zhtrq5hn8hmq0x4qd6m2qdppx88rnw3eumv9zv2ctjns05c8jhsqwg98qaxcz2qh45qhjv39c"
+});
+
 // Build unsigned transaction
 const builder = backendClient.newTx();
 builder.payToAddress({
-  address: "addr1...",
-  assets: { lovelace: 5000000n }
+  address: Core.Address.fromBech32("addr1qz8eg0aknl96hd3v6x3qfmmz5zhtrq5hn8hmq0x4qd6m2qdppx88rnw3eumv9zv2ctjns05c8jhsqwg98qaxcz2qh45qhjv39c"),
+  assets: Core.Assets.fromLovelace(5_000_000n)
 });
 
 // Build returns result, get transaction and serialize
@@ -157,8 +159,8 @@ export async function buildTransaction(userAddress: string) {
   // Build unsigned transaction
   const builder = client.newTx();
   builder.payToAddress({
-    address: "addr1...",
-    assets: { lovelace: 5000000n }
+    address: Core.Address.fromBech32("addr1qz8eg0aknl96hd3v6x3qfmmz5zhtrq5hn8hmq0x4qd6m2qdppx88rnw3eumv9zv2ctjns05c8jhsqwg98qaxcz2qh45qhjv39c"),
+    assets: Core.Assets.fromLovelace(5_000_000n)
   });
 
   // Returns unsigned transaction
@@ -191,7 +193,7 @@ export type BuildPaymentResponse = { txCbor: string };
 
 // @filename: frontend.ts
 // ===== Frontend (Browser) =====
-import { createClient } from "@evolution-sdk/evolution";
+import { Core, createClient } from "@evolution-sdk/evolution";
 import type { BuildPaymentResponse } from "./shared";
 
 declare const cardano: any;
@@ -204,8 +206,8 @@ async function sendPayment(recipientAddress: string, lovelace: bigint) {
     wallet: { type: "api", api: walletApi }
   });
 
-  // 2. Get user address
-  const userAddress = await walletClient.address();
+  // 2. Get user address (returns Core Address, convert to bech32 for backend)
+  const userAddress = Core.Address.toBech32(await walletClient.address());
 
   // 3. Request backend to build transaction
   const response = await fetch("/api/build-payment", {
@@ -233,29 +235,34 @@ async function sendPayment(recipientAddress: string, lovelace: bigint) {
 import { createClient, Core } from "@evolution-sdk/evolution";
 
 export async function buildPayment(
-  userAddress: string,
-  recipientAddress: string,
+  userAddressBech32: string,
+  recipientAddressBech32: string,
   lovelace: bigint
 ) {
-  // Create read-only client with user's address
-  const client = createClient({
+  // Convert bech32 addresses from frontend to Core Address
+  const recipientAddress = Core.Address.fromBech32(recipientAddressBech32);
+
+  // Create provider client first, then attach read-only wallet
+  const providerClient = createClient({
     network: "mainnet",
     provider: {
       type: "blockfrost",
       baseUrl: "https://cardano-mainnet.blockfrost.io/api/v0",
       projectId: process.env.BLOCKFROST_PROJECT_ID!
-    },
-    wallet: {
-      type: "read-only",
-      address: userAddress
     }
   });
 
+  // Attach user's address as read-only wallet
+  const client = providerClient.attachWallet({
+    type: "read-only",
+    address: userAddressBech32
+  });
+
   // Build unsigned transaction
   const builder = client.newTx();
   builder.payToAddress({
     address: recipientAddress,
-    assets: { lovelace }
+    assets: Core.Assets.fromLovelace(lovelace)
   });
 
   // Return unsigned CBOR for frontend to sign

docs/content/docs/clients/architecture/frontend-backend.mdx

@@ -83,8 +83,8 @@ Backend services use read-only clients configured with user addresses to build u
 ```typescript twoslash
 import { createClient, Core } from "@evolution-sdk/evolution";
 
-export async function buildTransaction(userAddress: string) {
-  // Create read-only client with user's address
+export async function buildTransaction(userAddressBech32: string) {
+  // Create read-only client with user's address (bech32 string)
   const client = createClient({
     network: "mainnet",
     provider: {
@@ -94,15 +94,15 @@ export async function buildTransaction(userAddress: string) {
     },
     wallet: {
       type: "read-only",
-      address: userAddress
+      address: userAddressBech32
     }
   });
 
   // Build unsigned transaction
   const builder = client.newTx();
   builder.payToAddress({
-    address: "addr1qz8eg0aknl96hd3v6x3qfmmz5zhtrq5hn8hmq0x4qd6m2qdppx88rnw3eumv9zv2ctjns05c8jhsqwg98qaxcz2qh45qhjv39c",
-    assets: { lovelace: 5000000n }
+    address: Core.Address.fromBech32("addr1qz8eg0aknl96hd3v6x3qfmmz5zhtrq5hn8hmq0x4qd6m2qdppx88rnw3eumv9zv2ctjns05c8jhsqwg98qaxcz2qh45qhjv39c"),
+    assets: Core.Assets.fromLovelace(5000000n)
   });
 
   // Build and return unsigned transaction
@@ -142,7 +142,7 @@ export type BuildPaymentResponse = {
 
 // @filename: frontend.ts
 // ===== Frontend (Browser) =====
-import { createClient } from "@evolution-sdk/evolution";
+import { Core, createClient } from "@evolution-sdk/evolution";
 import type { BuildPaymentRequest, BuildPaymentResponse } from "./shared";
 
 declare const cardano: any;
@@ -157,8 +157,8 @@ async function sendPayment(recipientAddress: string, lovelace: bigint) {
     wallet: { type: "api", api: walletApi }
   });
 
-  // 3. Get user address
-  const userAddress = await walletClient.address();
+  // 3. Get user address (returns Core Address, convert to bech32 for backend)
+  const userAddress = Core.Address.toBech32(await walletClient.address());
 
   // 4. Request backend to build transaction
   const requestBody: BuildPaymentRequest = {
@@ -190,11 +190,14 @@ import { createClient, Core } from "@evolution-sdk/evolution";
 import type { BuildPaymentResponse } from "./shared";
 
 export async function buildPayment(
-  userAddress: string,
-  recipientAddress: string,
+  userAddressBech32: string,
+  recipientAddressBech32: string,
   lovelace: bigint
 ): Promise<BuildPaymentResponse> {
-  // Create read-only client with user's address
+  // Convert recipient to Core Address for payToAddress
+  const recipientAddress = Core.Address.fromBech32(recipientAddressBech32);
+
+  // Create read-only client with user's address (bech32 string)
   const client = createClient({
     network: "mainnet",
     provider: {
@@ -204,15 +207,15 @@ export async function buildPayment(
     },
     wallet: {
       type: "read-only",
-      address: userAddress
+      address: userAddressBech32
     }
   });
 
   // Build unsigned transaction
   const builder = client.newTx();
   builder.payToAddress({
     address: recipientAddress,
-    assets: { lovelace }
+    assets: Core.Assets.fromLovelace(lovelace)
   });
 
   // Return unsigned CBOR for frontend to sign

docs/content/docs/clients/client-basics.mdx

@@ -40,7 +40,7 @@ Evolution SDK follows a three-stage pattern: build, sign, submit. Each stage ret
 Start with `client.newTx()` and chain operations to specify outputs, metadata, or validity ranges:
 
 ```ts twoslash
-import { createClient } from "@evolution-sdk/evolution";
+import { createClient, Core } from "@evolution-sdk/evolution";
 
 const client = createClient({
   network: "preprod",
@@ -51,8 +51,8 @@ const client = createClient({
 const builder = client.newTx();
 
 builder.payToAddress({
-  address: "addr_test1qzx9hu8j4ah3auytk0mwcupd69hpc52t0cw39a65ndrah86djs784u92a3m5w475w3w35tyd6v3qumkze80j8a6h5tuqq5xe8y",
-  assets: { lovelace: 2000000n }
+  address: Core.Address.fromBech32("addr_test1qzx9hu8j4ah3auytk0mwcupd69hpc52t0cw39a65ndrah86djs784u92a3m5w475w3w35tyd6v3qumkze80j8a6h5tuqq5xe8y"),
+  assets: Core.Assets.fromLovelace(2000000n)
 });
 
 const signBuilder = await builder.build();
@@ -63,7 +63,7 @@ const signBuilder = await builder.build();
 Call `.sign()` on the built transaction to create signatures with your wallet:
 
 ```ts twoslash
-import { createClient } from "@evolution-sdk/evolution";
+import { createClient, Core } from "@evolution-sdk/evolution";
 
 const client = createClient({
   network: "preprod",
@@ -72,7 +72,7 @@ const client = createClient({
 });
 
 const builder = client.newTx();
-builder.payToAddress({ address: "", assets: { lovelace: 2000000n } });
+builder.payToAddress({ address: Core.Address.fromBech32("addr_test1qzx9hu8j4ah3auytk0mwcupd69hpc52t0cw39a65ndrah86djs784u92a3m5w475w3w35tyd6v3qumkze80j8a6h5tuqq5xe8y"), assets: Core.Assets.fromLovelace(2000000n) });
 const signBuilder = await builder.build();
 
 const submitBuilder = await signBuilder.sign();
@@ -83,7 +83,7 @@ const submitBuilder = await signBuilder.sign();
 Finally, `.submit()` broadcasts the signed transaction to the blockchain and returns the transaction hash:
 
 ```ts twoslash
-import { createClient } from "@evolution-sdk/evolution";
+import { createClient, Core } from "@evolution-sdk/evolution";
 
 const client = createClient({
   network: "preprod",
@@ -92,7 +92,7 @@ const client = createClient({
 });
 
 const builder = client.newTx();
-builder.payToAddress({ address: "", assets: { lovelace: 2000000n } });
+builder.payToAddress({ address: Core.Address.fromBech32("addr_test1qzx9hu8j4ah3auytk0mwcupd69hpc52t0cw39a65ndrah86djs784u92a3m5w475w3w35tyd6v3qumkze80j8a6h5tuqq5xe8y"), assets: Core.Assets.fromLovelace(2000000n) });
 const signBuilder = await builder.build();
 const submitBuilder = await signBuilder.sign();
 
@@ -105,7 +105,7 @@ console.log("Transaction submitted:", txId);
 Here's the complete workflow in a single example—from client creation through transaction submission:
 
 ```ts twoslash
-import { createClient } from "@evolution-sdk/evolution";
+import { createClient, Core } from "@evolution-sdk/evolution";
 
 const client = createClient({
   network: "preprod",
@@ -124,8 +124,8 @@ const client = createClient({
 // Build transaction
 const builder = client.newTx();
 builder.payToAddress({
-  address: "addr_test1qzx9hu8j4ah3auytk0mwcupd69hpc52t0cw39a65ndrah86djs784u92a3m5w475w3w35tyd6v3qumkze80j8a6h5tuqq5xe8y",
-  assets: { lovelace: 2000000n }
+  address: Core.Address.fromBech32("addr_test1qzx9hu8j4ah3auytk0mwcupd69hpc52t0cw39a65ndrah86djs784u92a3m5w475w3w35tyd6v3qumkze80j8a6h5tuqq5xe8y"),
+  assets: Core.Assets.fromLovelace(2000000n)
 });
 
 // Build, sign, and submit

docs/content/docs/devnet/configuration.mdx

@@ -35,11 +35,11 @@ const client = createClient({
   }
 });
 
-// Get the address in Bech32 format
-const addressBech32 = await client.address();
+// Get the address
+const address = await client.address();
 
 // Convert to hex for genesis configuration
-const addressHex = Core.Address.toHex(Core.Address.fromBech32(addressBech32));
+const addressHex = Core.Address.toHex(address);
 
 // Create custom genesis with funded address
 const genesisConfig = {
@@ -91,8 +91,8 @@ const client2 = createClient({
   }
 });
 
-const address1 = Core.Address.toHex(Core.Address.fromBech32(await client1.address()));
-const address2 = Core.Address.toHex(Core.Address.fromBech32(await client2.address()));
+const address1 = Core.Address.toHex(await client1.address());
+const address2 = Core.Address.toHex(await client2.address());
 
 const genesisConfig = {
   ...Config.DEFAULT_SHELLEY_GENESIS,
@@ -121,6 +121,7 @@ After creating a genesis configuration, calculate the resulting UTxOs to verify
 
 ```typescript twoslash
 import { Config, Genesis } from "@evolution-sdk/devnet";
+import { Core } from "@evolution-sdk/evolution";
 declare const addressHex: string;
 
 const genesisConfig = {
@@ -135,10 +136,10 @@ const genesisUtxos = await Genesis.calculateUtxosFromConfig(genesisConfig);
 
 console.log("Genesis UTxOs:", genesisUtxos.length);
 genesisUtxos.forEach(utxo => {
-  console.log("Address:", utxo.address);
+  console.log("Address:", Core.Address.toBech32(utxo.address));
   console.log("Amount:", utxo.assets.lovelace, "lovelace");
-  console.log("TxHash:", utxo.txHash);
-  console.log("OutputIndex:", utxo.outputIndex);
+  console.log("TxHash:", Core.TransactionHash.toHex(utxo.transactionId));
+  console.log("OutputIndex:", utxo.index);
 });
 ```
 
@@ -324,8 +325,8 @@ const wallet2 = createClient({
   }
 });
 
-const addr1 = Core.Address.toHex(Core.Address.fromBech32(await wallet1.address()));
-const addr2 = Core.Address.toHex(Core.Address.fromBech32(await wallet2.address()));
+const addr1 = Core.Address.toHex(await wallet1.address());
+const addr2 = Core.Address.toHex(await wallet2.address());
 
 // Custom genesis configuration
 const genesisConfig = {
@@ -453,7 +454,7 @@ With custom genesis configuration, you can now:
 
 ## Troubleshooting
 
-**Address format errors**: Ensure addresses are in hexadecimal format, not Bech32. Use `Core.Address.toHex(Core.Address.fromBech32(addr))` to convert.
+**Address format errors**: Ensure addresses are in hexadecimal format, not Bech32. Use `Core.Address.toHex(address)` to convert from an Address object.
 
 **Genesis UTxO not found**: Wait 3-5 seconds after cluster start for full initialization. Query timing matters for fast block configurations.