Skip to content

Commit 0b4c0ab

Browse files
solidsnakedevsolidsnakedev
committed
feat: create devnet package
1 parent e4b48cb commit 0b4c0ab

File tree

14 files changed

+288
-48
lines changed

14 files changed

+288
-48
lines changed

‎packages/evolution-devnet/CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# @evolution-sdk/devnet
2+
3+
## 0.2.5
4+
5+
### Minor Changes
6+
7+
- Initial release of @evolution-sdk/devnet as a standalone package
8+
- Extracted from @evolution-sdk/evolution for better modularity
9+
- Full Docker-based local Cardano devnet support
10+
- Configurable genesis parameters and network settings
11+
- Optional Kupo and Ogmios service integration
12+
- Effect-based API for type-safe async operations
13+
- Deterministic genesis UTxO calculation
14+
- Comprehensive test suite included

‎packages/evolution-devnet/README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# @evolution-sdk/devnet
2+
3+
Docker-based local Cardano network for testing and development.
4+
5+
## Installation
6+
7+
```bash
8+
pnpm add -D @evolution-sdk/devnet @evolution-sdk/evolution
9+
```
10+
11+
**Prerequisites**: Docker must be installed and running.
12+
13+
## Usage
14+
15+
```typescript
16+
import { Devnet } from "@evolution-sdk/devnet"
17+
18+
// Create and start devnet
19+
const cluster = await Devnet.Cluster.make()
20+
await Devnet.Cluster.start(cluster)
21+
22+
// Cleanup
23+
await Devnet.Cluster.stop(cluster)
24+
await Devnet.Cluster.remove(cluster)
25+
```
26+
27+
### With Pre-funded Address
28+
29+
```typescript
30+
const cluster = await Devnet.Cluster.make({
31+
shelleyGenesis: {
32+
initialFunds: {
33+
"addr_test1...": 1_000_000_000_000 // 1000 ADA
34+
}
35+
}
36+
})
37+
await Devnet.Cluster.start(cluster)
38+
```
39+
40+
### With Kupo and Ogmios
41+
42+
```typescript
43+
const cluster = await Devnet.Cluster.make({
44+
kupo: { enabled: true, port: 1442 },
45+
ogmios: { enabled: true, port: 1337 }
46+
})
47+
await Devnet.Cluster.start(cluster)
48+
```
49+
50+
## Configuration
51+
52+
```typescript
53+
interface DevNetConfig {
54+
clusterName?: string
55+
networkMagic?: number
56+
ports?: { node: number; submit: number }
57+
shelleyGenesis?: Partial<ShelleyGenesis>
58+
kupo?: KupoConfig
59+
ogmios?: OgmiosConfig
60+
}
61+
```
62+
63+
### Accelerated Block Production
64+
65+
```typescript
66+
const cluster = await Devnet.Cluster.make({
67+
shelleyGenesis: {
68+
slotLength: 0.02, // 20ms slots (50x faster)
69+
activeSlotsCoeff: 1.0 // 100% block density
70+
}
71+
})
72+
```
73+
74+
## API
75+
76+
### Cluster
77+
- `Cluster.make(config?)` - Create cluster
78+
- `Cluster.start(cluster)` - Start containers
79+
- `Cluster.stop(cluster)` - Stop containers
80+
- `Cluster.remove(cluster)` - Remove containers
81+
82+
### Container
83+
- `Container.execCommand(container, command)` - Execute command in container
84+
- `Container.getStatus(container)` - Get container status
85+
86+
### Genesis
87+
- `Genesis.calculateUtxosFromConfig(config)` - Calculate genesis UTxOs
88+
- `Genesis.queryUtxos(cluster)` - Query UTxOs from running node
89+
90+
## Testing
91+
92+
```typescript
93+
import { Devnet } from "@evolution-sdk/devnet"
94+
95+
describe("tests", () => {
96+
let cluster
97+
98+
beforeAll(async () => {
99+
cluster = await Devnet.Cluster.make()
100+
await Devnet.Cluster.start(cluster)
101+
})
102+
103+
afterAll(async () => {
104+
await Devnet.Cluster.remove(cluster)
105+
})
106+
})
107+
```

‎packages/evolution-devnet/package.json‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
{
2+
"name": "@evolution-sdk/devnet",
3+
"version": "0.2.5",
4+
"description": "Local Cardano devnet for testing and development with Docker",
5+
"type": "module",
6+
"main": "./dist/index.js",
7+
"module": "./dist/index.js",
8+
"types": "./dist/index.d.ts",
9+
"sideEffects": [],
10+
"tags": [
11+
"typescript",
12+
"cardano",
13+
"blockchain",
14+
"devnet",
15+
"docker",
16+
"testing"
17+
],
18+
"exports": {
19+
"./package.json": "./package.json",
20+
".": "./src/index.ts",
21+
"./*": "./src/*.ts",
22+
"./internal/*": null,
23+
"./*/index": null
24+
},
25+
"files": [
26+
"src/**/*.ts",
27+
"dist/**/*.js",
28+
"dist/**/*.js.map",
29+
"dist/**/*.d.ts",
30+
"dist/**/*.d.ts.map"
31+
],
32+
"scripts": {
33+
"build": "tsc -b tsconfig.build.json && babel dist --plugins annotate-pure-calls --out-dir dist --source-maps",
34+
"dev": "tsc -b tsconfig.build.json --watch",
35+
"type-check": "tsc --noEmit",
36+
"lint": "eslint \"src/**/*.{ts,mjs}\" \"test/**/*.{ts,mjs}\"",
37+
"test": "vitest run",
38+
"clean": "rm -rf dist .turbo"
39+
},
40+
"devDependencies": {
41+
"@types/dockerode": "^3.3.43",
42+
"tsx": "^4.20.4",
43+
"typescript": "^5.9.2"
44+
},
45+
"dependencies": {
46+
"dockerode": "^4.0.7"
47+
},
48+
"peerDependencies": {
49+
"@evolution-sdk/evolution": "workspace:*",
50+
"@effect/platform": "^0.90.10",
51+
"@effect/platform-node": "^0.96.1",
52+
"@noble/hashes": "^1.8.0",
53+
"effect": "^3.19.3"
54+
},
55+
"keywords": [
56+
"cardano",
57+
"blockchain",
58+
"devnet",
59+
"docker",
60+
"testing",
61+
"development",
62+
"local-network",
63+
"typescript",
64+
"sdk"
65+
],
66+
"homepage": "https://github.com/IntersectMBO/evolution-sdk",
67+
"repository": {
68+
"type": "git",
69+
"url": "git+https://github.com/IntersectMBO/evolution-sdk.git",
70+
"directory": "packages/evolution-devnet"
71+
},
72+
"bugs": {
73+
"url": "https://github.com/IntersectMBO/evolution-sdk/issues"
74+
},
75+
"license": "MIT",
76+
"publishConfig": {
77+
"access": "public",
78+
"provenance": true,
79+
"exports": {
80+
"./package.json": "./package.json",
81+
".": "./dist/index.js",
82+
"./*": "./dist/*.js",
83+
"./internal/*": null,
84+
"./*/index": null
85+
}
86+
}
87+
}

packages/evolution/src/sdk/Devnet/Devnet.ts renamed to packages/evolution-devnet/src/Devnet.ts

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
import { NodeStream } from "@effect/platform-node"
2+
import * as Address from "@evolution-sdk/evolution/core/AddressEras"
3+
import * as TransactionHash from "@evolution-sdk/evolution/core/TransactionHash"
4+
import * as Assets from "@evolution-sdk/evolution/sdk/Assets"
5+
import type * as UTxO from "@evolution-sdk/evolution/sdk/UTxO"
26
import { blake2b } from "@noble/hashes/blake2"
37
import Docker from "dockerode"
48
import { Data, Effect, Stream } from "effect"
@@ -7,10 +11,6 @@ import * as os from "os"
711
import * as path from "path"
812
import { PassThrough } from "stream"
913

10-
import * as Address from "../../core/AddressEras.js"
11-
import * as TransactionHash from "../../core/TransactionHash.js"
12-
import * as Assets from "../Assets.js"
13-
import type * as UTxO from "../UTxO.js"
1414
import * as DevnetDefault from "./DevnetDefault.js"
1515

1616
export class CardanoDevNetError extends Data.TaggedError("CardanoDevNetError")<{

packages/evolution/src/sdk/Devnet/DevnetDefault.ts renamed to packages/evolution-devnet/src/DevnetDefault.ts

File renamed without changes.

‎packages/evolution-devnet/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
export * as Devnet from "./Devnet.js"
2+
export * as DevnetDefault from "./DevnetDefault.js"

packages/evolution/test/Client.Devnet.test.ts renamed to packages/evolution-devnet/test/Client.Devnet.test.ts

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
import { describe, expect, it } from "@effect/vitest"
2+
import * as Devnet from "@evolution-sdk/devnet/Devnet"
3+
import * as DevnetDefault from "@evolution-sdk/devnet/DevnetDefault"
4+
import * as Address from "@evolution-sdk/evolution/core/AddressEras"
5+
import * as Assets from "@evolution-sdk/evolution/sdk/Assets"
6+
import { createClient } from "@evolution-sdk/evolution/sdk/client/ClientImpl"
7+
import type { ProtocolParameters } from "@evolution-sdk/evolution/sdk/ProtocolParameters"
8+
import type { UTxO } from "@evolution-sdk/evolution/sdk/UTxO"
29
import { afterAll, beforeAll } from "vitest"
310

4-
import * as Address from "../src/core/AddressEras.js"
5-
import * as Assets from "../src/sdk/Assets.js"
6-
import { createClient } from "../src/sdk/client/ClientImpl.js"
7-
import * as Devnet from "../src/sdk/Devnet/Devnet.js"
8-
import * as DevnetDefault from "../src/sdk/Devnet/DevnetDefault.js"
9-
import type { ProtocolParameters } from "../src/sdk/ProtocolParameters.js"
10-
import type { UTxO } from "../src/sdk/UTxO.js"
11-
1211
/**
1312
* Client integration tests with local Devnet
1413
*/

packages/evolution/test/Devnet.Genesis.test.ts renamed to packages/evolution-devnet/test/Devnet.Genesis.test.ts

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
import { describe, expect, it } from "@effect/vitest"
2+
import * as Devnet from "@evolution-sdk/devnet/Devnet"
3+
import * as DevnetDefault from "@evolution-sdk/devnet/DevnetDefault"
24
import { afterAll, beforeAll } from "vitest"
35

4-
import * as Devnet from "../src/sdk/Devnet/Devnet.js"
5-
import * as DevnetDefault from "../src/sdk/Devnet/DevnetDefault.js"
6-
76
/**
87
* Tests for Devnet.Genesis module
98
* Verifies that calculated genesis UTxOs match actual chain UTxOs

packages/evolution/test/Devnet.integration.test.ts renamed to packages/evolution-devnet/test/Devnet.integration.test.ts

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
import { afterAll, describe, expect, it } from "@effect/vitest"
2+
import * as Devnet from "@evolution-sdk/devnet/Devnet"
3+
import * as AddressEras from "@evolution-sdk/evolution/core/AddressEras"
4+
import * as EnterpriseAddress from "@evolution-sdk/evolution/core/EnterpriseAddress"
5+
import * as KeyHash from "@evolution-sdk/evolution/core/KeyHash"
6+
import * as PrivateKey from "@evolution-sdk/evolution/core/PrivateKey"
7+
import * as VKey from "@evolution-sdk/evolution/core/VKey"
28
import Docker from "dockerode"
39
import { Effect } from "effect"
410

5-
import * as AddressEras from "../src/core/AddressEras.js"
6-
import * as EnterpriseAddress from "../src/core/EnterpriseAddress.js"
7-
import * as KeyHash from "../src/core/KeyHash.js"
8-
import * as PrivateKey from "../src/core/PrivateKey.js"
9-
import * as VKey from "../src/core/VKey.js"
10-
import * as Devnet from "../src/sdk/Devnet/Devnet.js"
11-
1211
/**
1312
* Fast Shelley genesis config for testing.
1413
* Produces blocks every 20ms instead of default 1s (50x faster).

‎packages/evolution-devnet/tsconfig.build.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"$schema": "http://json.schemastore.org/tsconfig",
3+
"extends": "./tsconfig.src.json",
4+
"compilerOptions": {
5+
"tsBuildInfoFile": ".tsbuildinfo/build.tsbuildinfo",
6+
"outDir": "dist",
7+
"types": ["node"],
8+
"stripInternal": true
9+
}
10+
}

0 commit comments

Comments
 (0)