docs: add docs

Author: solidsnakedev

docs/content/docs/encoding/data.mdx

@@ -0,0 +1,330 @@
+---
+title: PlutusData
+description: On-chain data structures for Cardano smart contracts
+---
+
+import { Card, Cards } from 'fumadocs-ui/components/card'
+
+# PlutusData
+
+PlutusData is the serialization format for all on-chain data in Cardano smart contracts. Every datum attached to a UTxO, every redeemer that unlocks a script, and every parameter passed to a validator must be encoded as PlutusData.
+
+The Evolution SDK's Data module gives you type-safe PlutusData creation without touching raw CBOR bytes.
+
+## The Five Types
+
+PlutusData consists of five primitive types:
+
+| Type | TypeScript | Use For |
+|------|-----------|---------|
+| **Integer** | `bigint` | Amounts, indices, timestamps, quantities |
+| **ByteArray** | `Uint8Array` | Hashes, addresses, policy IDs, asset names |
+| **Constructor** | `{ index: bigint, fields: Data[] }` | Variants, tagged unions, structured data |
+| **Map** | `Map<Data, Data>` | Metadata, key-value stores |
+| **List** | `ReadonlyArray<Data>` | Arrays of values |
+
+## Quick Start
+
+Create PlutusData using TypeScript primitives:
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// Integer (bigint)
+const lovelaceAmount: Core.Data.Data = 5000000n
+
+// ByteArray (Uint8Array)
+const tokenName = Core.Text.toBytes("HOSKY")
+const policyId = Core.Bytes.fromHex("a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8")
+
+// Constructor (variant with fields)
+const unlockAction = Core.Data.constr(0n, []) // variant 0, no fields
+
+// Map (key-value pairs)
+const metadata = Core.Data.map([
+  [Core.Text.toBytes("name"), Core.Text.toBytes("My NFT")],
+  [Core.Text.toBytes("image"), Core.Text.toBytes("ipfs://Qm...")]
+])
+
+// List (array)
+const quantities: Core.Data.Data = [100n, 200n, 300n]
+```
+
+## Integers
+
+Use `bigint` directly—no wrapper needed:
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// Lovelace amounts
+const fee: Core.Data.Data = 170000n
+const deposit: Core.Data.Data = 2000000n
+
+// Token quantities  
+const nftQuantity: Core.Data.Data = 1n
+const ftQuantity: Core.Data.Data = 1000000n
+
+// Negative values supported
+const delta: Core.Data.Data = -500n
+
+// Large numbers
+const totalSupply: Core.Data.Data = 45000000000000000n
+```
+
+## Byte Arrays
+
+Raw bytes for hashes, addresses, and binary data:
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// Transaction hash (32 bytes)
+const txHash = Core.Bytes.fromHex(
+  "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
+)
+
+// Policy ID (28 bytes)
+const policyId = Core.Bytes.fromHex(
+  "1234567890abcdef1234567890abcdef1234567890abcdef12345678"
+)
+
+// Asset name (readable string)
+const assetName = Core.Text.toBytes("MyToken")
+
+// Empty byte array (ada-only policyId)
+const adaPolicyId = new Uint8Array()
+```
+
+**When to use `Bytes.fromHex` vs `Text.toBytes`:**
+
+- **`Bytes.fromHex`**: For hashes, policy IDs, credential hashes (hexadecimal data)
+- **`Text.toBytes`**: For asset names, metadata values (human-readable strings)
+
+## Constructors
+
+Tagged unions representing variants or structured data:
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// Simple variant (no data)
+const claimAction = Core.Data.constr(0n, [])
+const cancelAction = Core.Data.constr(1n, [])
+
+// Variant with single field
+const verificationKeyCred = Core.Data.constr(0n, [
+  Core.Bytes.fromHex("abc123def456abc123def456abc123def456abc123def456abc123de")
+])
+
+const scriptCred = Core.Data.constr(1n, [
+  Core.Bytes.fromHex("def456abc123def456abc123def456abc123def456abc123def456ab")
+])
+
+// Multiple fields
+const outputRef = Core.Data.constr(0n, [
+  Core.Bytes.fromHex("a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"), // tx hash
+  2n // output index
+])
+```
+
+**Constructor index** determines which variant you're creating. Your Plutus validator defines what each index means.
+
+## Maps
+
+Key-value pairs where both keys and values are PlutusData:
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// NFT metadata
+const nftMetadata = Core.Data.map([
+  [Core.Text.toBytes("name"), Core.Text.toBytes("CryptoKitty #1234")],
+  [Core.Text.toBytes("image"), Core.Text.toBytes("ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco")],
+  [Core.Text.toBytes("description"), Core.Text.toBytes("A rare cryptokitty with rainbow fur")]
+])
+
+// Nested maps
+const tokenMetadata = Core.Data.map([
+  [Core.Text.toBytes("name"), Core.Text.toBytes("MyToken")],
+  [Core.Text.toBytes("ticker"), Core.Text.toBytes("MTK")],
+  [Core.Text.toBytes("decimals"), 6n],
+  [Core.Text.toBytes("properties"), Core.Data.map([
+    [Core.Text.toBytes("mintable"), 1n], // boolean as 0/1
+    [Core.Text.toBytes("burnable"), 1n]
+  ])]
+])
+```
+
+## Lists
+
+Ordered arrays of PlutusData:
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// List of integers
+const prices: Core.Data.Data = [100n, 250n, 500n, 1000n]
+
+// List of byte arrays (hashes)
+const approvedSigners: Core.Data.Data = [
+  Core.Bytes.fromHex("abc123def456abc123def456abc123def456abc123def456abc123de"),
+  Core.Bytes.fromHex("def456abc123def456abc123def456abc123def456abc123def456ab"),
+  Core.Bytes.fromHex("123456789abc123456789abc123456789abc123456789abc12345678")
+]
+
+// List of constructors
+const actions: Core.Data.Data = [
+  Core.Data.constr(0n, []), // Claim
+  Core.Data.constr(1n, []), // Cancel
+  Core.Data.constr(2n, [5000000n]) // PartialClaim(amount)
+]
+```
+
+## CBOR Encoding
+
+Convert PlutusData to CBOR for blockchain submission:
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+const datum = Core.Data.constr(0n, [
+  Core.Data.map([
+    [Core.Text.toBytes("beneficiary"), Core.Text.toBytes("addr1...")],
+    [Core.Text.toBytes("deadline"), 1735689600000n]
+  ]),
+  5000000n, // amount
+  1n // version
+])
+
+// Encode to hex string
+const cborHex = Core.Data.toCBORHex(datum)
+// "d8799fa2646265..."
+
+// Encode to bytes  
+const cborBytes = Core.Data.toCBORBytes(datum)
+// Uint8Array [216, 121, 159, ...]
+
+// Decode from CBOR
+const decoded = Core.Data.fromCBORHex(cborHex)
+// Returns original PlutusData structure
+```
+
+## Equality Comparison
+
+Check if two PlutusData structures are equal:
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+const map1 = Core.Data.map([
+  [Core.Text.toBytes("name"), Core.Text.toBytes("Alice")],
+  [Core.Text.toBytes("age"), 30n]
+])
+
+const map2 = Core.Data.map([
+  [Core.Text.toBytes("name"), Core.Text.toBytes("Alice")],
+  [Core.Text.toBytes("age"), 30n]
+])
+
+// Deep equality check
+const isEqual = Core.Data.equals(map1, map2)
+// true
+```
+
+## Real-World Examples
+
+### Escrow Datum
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// Escrow locked until deadline
+const escrowDatum = Core.Data.constr(0n, [
+  Core.Bytes.fromHex("abc123def456abc123def456abc123def456abc123def456abc123de"), // beneficiary
+  1735689600000n, // deadline (Unix timestamp)
+  10000000n // locked lovelace amount
+])
+
+const cborHex = Core.Data.toCBORHex(escrowDatum)
+// Attach to UTxO as inline datum
+```
+
+### CIP-68 NFT Metadata
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// Reference NFT metadata (label 100)
+const metadata = Core.Data.map([
+  [Core.Text.toBytes("name"), Core.Text.toBytes("SpaceAce #4242")],
+  [Core.Text.toBytes("image"), Core.Text.toBytes("ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco")],
+  [Core.Text.toBytes("rarity"), Core.Text.toBytes("legendary")],
+  [Core.Text.toBytes("attributes"), Core.Data.map([
+    [Core.Text.toBytes("class"), Core.Text.toBytes("explorer")],
+    [Core.Text.toBytes("power"), 9000n]
+  ])]
+])
+
+const cip68Datum = Core.Data.constr(0n, [
+  metadata,
+  1n, // version
+  [] // extra fields
+])
+```
+
+### Redeemer with Multiple Actions
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+// Action variants
+const claim = Core.Data.constr(0n, [])
+const cancel = Core.Data.constr(1n, [])
+const update = Core.Data.constr(2n, [
+  1735776000000n // new deadline
+])
+
+// Use in transaction
+const redeemer = claim
+```
+
+### Multi-Sig Validator Redeemer
+
+```typescript twoslash
+import { Core } from "@evolution-sdk/evolution"
+
+const multiSigRedeemer = Core.Data.constr(0n, [
+  // Required signers (list of key hashes)
+  [
+    Core.Bytes.fromHex("abc123def456abc123def456abc123def456abc123def456abc123de"),
+    Core.Bytes.fromHex("def456abc123def456abc123def456abc123def456abc123def456ab")
+  ] as Core.Data.Data,
+  2n // threshold (2 of N)
+])
+```
+
+## When to Use PlutusData Directly
+
+Use the Data module directly when:
+
+- Quick prototyping or testing
+- Working with dynamic data structures
+- Debugging CBOR encoding issues
+- Building tooling or explorers
+
+For production smart contract integration, use [TSchema](/docs/encoding/tschema) for type-safe schema definitions with automatic validation.
+
+## Next Steps
+
+<Cards>
+  <Card title="TSchema" href="/docs/encoding/tschema">
+    Type-safe schema definitions with automatic validation
+  </Card>
+  <Card title="Plutus Types" href="/docs/encoding/plutus">
+    Pre-built types for addresses, credentials, values, and CIP-68
+  </Card>
+  <Card title="CBOR" href="/docs/encoding/cbor">
+    Low-level CBOR encoding and decoding
+  </Card>
+</Cards>

docs/content/docs/encoding/meta.json

@@ -5,6 +5,9 @@
     "cbor",
     "bech32",
     "hex",
-    "json"
+    "json",
+    "data",
+    "tschema",
+    "plutus"
   ]
 }