@blinklabs/dingo 0.20.0 → 0.23.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +115 -0
- package/ARCHITECTURE.md +839 -0
- package/README.md +457 -42
- package/RELEASE_NOTES.md +91 -0
- package/{devnet.sh → devmode.sh} +5 -5
- package/dingo.yaml.example +185 -7
- package/docker-compose.yml +51 -0
- package/package.json +1 -1
- package/PLUGIN_DEVELOPMENT.md +0 -306
package/AGENTS.md
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Concise guide for AI agents working with Dingo. For full details, see `ARCHITECTURE.md`.
|
|
4
|
+
|
|
5
|
+
## Quick Reference
|
|
6
|
+
|
|
7
|
+
**Dingo**: Go-based Cardano blockchain node by Blink Labs (Ouroboros protocol, UTxO tracking, pluggable storage).
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
make # Format, test, build
|
|
11
|
+
make test # Tests with race detection
|
|
12
|
+
make bench # Run benchmarks
|
|
13
|
+
go run ./cmd/dingo/ # Run without building
|
|
14
|
+
go test -v -race -run TestName ./path/to/package/ # Single test
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Key Packages
|
|
18
|
+
|
|
19
|
+
| Package | Purpose |
|
|
20
|
+
|---------|---------|
|
|
21
|
+
| `chain/` | Blockchain state, fork detection, rollback |
|
|
22
|
+
| `chainselection/` | Multi-peer chain comparison (Ouroboros Praos) |
|
|
23
|
+
| `chainsync/` | Block sync state tracking |
|
|
24
|
+
| `connmanager/` | Network connection lifecycle |
|
|
25
|
+
| `database/` | Storage plugins (badger, sqlite, postgres, mysql, gcs, s3) |
|
|
26
|
+
| `event/` | Event bus (async pub/sub, 4 workers) |
|
|
27
|
+
| `ledger/` | UTxO state, protocol params, Plutus execution |
|
|
28
|
+
| `mempool/` | Transaction pool & validation |
|
|
29
|
+
| `ouroboros/` | Protocol handlers (N2N, N2C) |
|
|
30
|
+
| `peergov/` | Peer governance, churn, quotas |
|
|
31
|
+
| `utxorpc/` | UTxO RPC gRPC server |
|
|
32
|
+
|
|
33
|
+
## Code Quality (Run Before Committing)
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
golangci-lint run ./... # Linters (39 via .golangci.yml)
|
|
37
|
+
nilaway ./... # Nil-safety analyzer
|
|
38
|
+
modernize ./... # Modern Go idioms
|
|
39
|
+
make golines # 80 char line limit
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Essential Patterns
|
|
43
|
+
|
|
44
|
+
### Error Handling
|
|
45
|
+
```go
|
|
46
|
+
// Wrap errors with context
|
|
47
|
+
return fmt.Errorf("failed to process block: %w", err)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Event-Driven Communication
|
|
51
|
+
```go
|
|
52
|
+
// Subscribe to events (never call components directly)
|
|
53
|
+
eventBus.SubscribeFunc(chain.ChainForkEventType, handler)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Database Queries
|
|
57
|
+
```go
|
|
58
|
+
// GOOD: Batch fetch (single query)
|
|
59
|
+
db.Where("id IN ?", ids).Find(&records)
|
|
60
|
+
|
|
61
|
+
// BAD: N+1 queries
|
|
62
|
+
for _, id := range ids {
|
|
63
|
+
db.Where("id = ?", id).First(&record)
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// Certificate ordering: use cert_index as tie-breaker
|
|
67
|
+
Order("added_slot DESC, cert_index DESC")
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Rollback Handling
|
|
71
|
+
- `Chain.Rollback(point)` emits `ChainRollbackEvent`
|
|
72
|
+
- State restoration in `database/plugin/metadata/sqlite/`
|
|
73
|
+
- Use `TransactionEvent.Rollback` field to detect undo operations
|
|
74
|
+
|
|
75
|
+
### CBOR Storage
|
|
76
|
+
- UTxOs/TXs stored as 52-byte `CborOffset` (magic "DOFF" + slot + hash + offset + length)
|
|
77
|
+
- `TieredCborCache` resolves: hot cache → block LRU → cold extraction
|
|
78
|
+
|
|
79
|
+
### Stake Snapshots
|
|
80
|
+
- Mark/Set/Go rotation at epoch boundaries (Ouroboros Praos)
|
|
81
|
+
- `LedgerView.GetStakeDistribution(epoch)` for leader election queries
|
|
82
|
+
- `PoolStakeSnapshot` model stores per-pool stake
|
|
83
|
+
- `EpochSummary` stores network aggregates
|
|
84
|
+
|
|
85
|
+
## Key Event Types
|
|
86
|
+
|
|
87
|
+
| Event | Purpose |
|
|
88
|
+
|-------|---------|
|
|
89
|
+
| `chain.update` | Block added to chain |
|
|
90
|
+
| `chain.fork-detected` | Fork detected |
|
|
91
|
+
| `chainselection.chain_switch` | Active peer changed |
|
|
92
|
+
| `epoch.transition` | Epoch boundary crossed (triggers stake snapshot) |
|
|
93
|
+
| `mempool.add_tx` / `mempool.remove_tx` | Transaction lifecycle |
|
|
94
|
+
| `connmanager.conn-closed` | Connection lifecycle |
|
|
95
|
+
| `peergov.peer-churn` | Peer rotation |
|
|
96
|
+
|
|
97
|
+
## Configuration
|
|
98
|
+
|
|
99
|
+
Priority: CLI flags > Env vars > YAML config > Defaults
|
|
100
|
+
|
|
101
|
+
Key env vars: `CARDANO_NETWORK`, `CARDANO_DATABASE_PATH`, `DINGO_DATABASE_BLOB_PLUGIN`, `DINGO_DATABASE_METADATA_PLUGIN`
|
|
102
|
+
|
|
103
|
+
## Critical Anti-Patterns
|
|
104
|
+
|
|
105
|
+
1. **Don't bypass EventBus** - Components communicate via events, not direct calls
|
|
106
|
+
2. **Don't use N+1 queries** - Batch fetch with `WHERE id IN ?`
|
|
107
|
+
3. **Don't forget cert_index** - Multiple certs in same slot need ordering
|
|
108
|
+
4. **Don't ignore rollbacks** - Check `TransactionEvent.Rollback` field
|
|
109
|
+
5. **Don't skip linting** - Run `golangci-lint`, `nilaway`, `modernize` before commits
|
|
110
|
+
|
|
111
|
+
## Testing
|
|
112
|
+
|
|
113
|
+
- Integration tests: `internal/integration/`
|
|
114
|
+
- Test data: `database/immutable/testdata/` (real blocks slots 0-1.3M)
|
|
115
|
+
- Benchmarks: `make bench` (28+ benchmarks)
|