Skip to content

Commit 056ba9d

Browse files
Ranchhand87Ranchhand87
authored
Merge pull request #122 from danbaruka/docs/cardano-api
docs: Add Core Cardano repository documentation - cardano-api
2 parents dd08626 + 2489726 commit 056ba9d

File tree

3 files changed

+185
-64
lines changed

3 files changed

+185
-64
lines changed

‎DA Milestones/Uche/Q4 2025/IRL_event.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
`# Introduction to Cardano Physical Meetup, Enugu
2+
3+
![Intro to cardano physical meetup banner](./images/cardano-workshop.png)
4+
5+
The Introduction to Cardano IRL/Community event was successfully held in Enugu, Nigeria bringing together blockchain enthusiasts, students, developers, and professionals interested in learning about the Cardano ecosystem. The session aimed to introduce the fundamentals of Cardano, its unique architecture, real-world applications, and opportunities within the ecosystem. The event had a total of over 25 attendees. The event helped raise awareness about Cardano in the South-East region and motivated several attendees to explore further learning paths, developer tools, and community involvement.
6+
7+
## Picture highlights from the event
8+
9+
![Uche presenting](./images/IMG_3036.jpg)
10+
![Another angle of uche presenting](./images/IMG_3038.jpg)
11+
![Group photo](./images/IMG_3044.jpg)

‎website/docs/how-to-guide/advanced/README.md‎

Lines changed: 0 additions & 64 deletions
This file was deleted.

‎website/docs/how-to-guide/advanced/cardano-api.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# Cardano API
2+
3+
## Overview
4+
5+
Cardano API is a Haskell library that provides the core Cardano API interface used by Cardano tools like the node, CLI, and other Haskell-based services. It exposes high-level functions to build and interact with Cardano types (transactions, addresses, queries) without dealing with low-level internals.
6+
7+
**Important**: `cardano-api` is not a REST API or external HTTP API — it's a library you import into Haskell code.
8+
9+
## Repository
10+
11+
[github.com/IntersectMBO/cardano-api](https://github.com/IntersectMBO/cardano-api)
12+
13+
## What It Does
14+
15+
Cardano API provides a unified interface that integrates ledger, consensus, and networking repositories into a single API. It serves as essential building blocks for Cardano node and application development with strongly-typed Haskell interfaces for reliable blockchain interactions.
16+
17+
## Key Components
18+
19+
| Component | Description |
20+
|-----------|-------------|
21+
| `cardano-api` | Main API library |
22+
| `cardano-api-gen` | Code generation utilities |
23+
| `cardano-rpc` | Remote Procedure Call interface |
24+
| `cardano-wasm` | WebAssembly bindings |
25+
26+
## When to Use It
27+
28+
Use `cardano-api` when building Haskell applications that need to:
29+
30+
- Build and sign transactions programmatically
31+
- Work with addresses, keys, and ledger types
32+
- Query chain data via a connected Cardano node
33+
- Serialize/deserialize Cardano data (CBOR/JSON)
34+
- Interact with multiple Cardano eras (Byron, Shelley, etc.)
35+
- Include smart contract (Plutus) functionality
36+
37+
This library provides consistent types and helpers to work with the blockchain without rewriting Cardano internals.
38+
39+
## Use Cases
40+
41+
| Use Case | Example Applications |
42+
|----------|---------------------|
43+
| Node Development | Full nodes, relay nodes, block producers |
44+
| Wallet Development | Desktop wallets, mobile wallets, hardware wallet integrations |
45+
| CLI Tools | Transaction builders, query tools, governance utilities |
46+
| DApp Backends | DeFi platforms, NFT marketplaces, governance systems |
47+
| Blockchain Explorers | Block explorers, analytics dashboards, monitoring tools |
48+
| Infrastructure Services | Indexers, oracles, bridge services, staking pools |
49+
| Smart Contract Tools | Contract compilers, testing frameworks, deployment tools |
50+
| Governance Systems | Catalyst voting, on-chain governance, treasury management |
51+
52+
## Technical Details
53+
54+
| Aspect | Details |
55+
|--------|---------|
56+
| Language | Haskell (96.6%) |
57+
| License | Apache-2.0 |
58+
| Build System | Cabal, Nix |
59+
| Documentation | Haddock |
60+
61+
## Getting Started
62+
63+
### Prerequisites
64+
65+
- GHC (Glasgow Haskell Compiler) version 9.2 or later
66+
- Cabal or Stack as build tool
67+
- Nix (recommended for Cardano development)
68+
69+
### Adding as a Dependency
70+
71+
**Using Cabal:**
72+
73+
Add to your `.cabal` file:
74+
75+
```cabal
76+
build-depends:
77+
base >= 4.14 && < 4.22,
78+
cardano-api >= 10.0
79+
```
80+
81+
Or add to `cabal.project`:
82+
83+
```cabal
84+
source-repository-package
85+
type: git
86+
location: https://github.com/IntersectMBO/cardano-api.git
87+
tag: <version-tag>
88+
```
89+
90+
**Using Stack:**
91+
92+
Add to `stack.yaml`:
93+
94+
```yaml
95+
extra-deps:
96+
- git: https://github.com/IntersectMBO/cardano-api.git
97+
commit: <commit-hash>
98+
```
99+
100+
**Note**: Align versions with what's published on CHaP (Cardano Haskell Package index).
101+
102+
### Basic Usage
103+
104+
Import the library:
105+
106+
```haskell
107+
import Cardano.Api
108+
import Cardano.Api.Shelley
109+
```
110+
111+
Key modules provide:
112+
- Transaction building and signing
113+
- Address handling and validation
114+
- Protocol parameter queries
115+
- Serialization/CBOR helpers
116+
- Chain querying functions
117+
118+
## Common Modules
119+
120+
| Module | Purpose |
121+
|--------|---------|
122+
| `Cardano.Api` | Core API types and functions |
123+
| `Cardano.Api.Shelley` | Shelley-era specific functionality |
124+
| `Cardano.Api.Byron` | Byron-era compatibility |
125+
| `Cardano.Api.Address` | Address creation and validation |
126+
| `Cardano.Api.TxBody` | Transaction body building |
127+
| `Cardano.Api.Tx` | Transaction construction and signing |
128+
| `Cardano.Api.Query` | Chain querying functions |
129+
130+
## Best Practices
131+
132+
1. **Error Handling**: Always handle `Maybe` and `Either` types returned by API functions
133+
2. **Network IDs**: Use appropriate network identifiers (Mainnet, Testnet, etc.)
134+
3. **Type Safety**: Leverage Haskell's type system for compile-time safety
135+
4. **Resource Management**: Properly close connections and handle exceptions
136+
5. **Testing**: Use testnet for development before mainnet deployment
137+
138+
## When NOT to Use It
139+
140+
If you don't want to write Haskell or don't want to run a node, consider these alternatives:
141+
142+
- **Blockfrost** - REST API for JS/Python/any language
143+
- **Koios** - Community-driven REST API for Cardano
144+
- **Cardano GraphQL** - GraphQL API for querying Cardano data
145+
- **Ogmios** - WebSocket API for Cardano node interaction
146+
147+
`cardano-api` is specifically for Haskell development and local node interaction.
148+
149+
## Summary
150+
151+
| Feature | Supported |
152+
|---------|-----------|
153+
| Build transactions | Yes |
154+
| Serialize/Deserialize | Yes |
155+
| Chain queries | Yes (with node connection) |
156+
| REST endpoint | No |
157+
| JavaScript/Python use | Not directly |
158+
159+
## Workflow
160+
161+
1. Run a Cardano node (locally or via service)
162+
2. Import `cardano-api` in your Haskell project
163+
3. Use its types/functions to build transactions, query ledger state, and process keys/addresses
164+
4. Submit transactions via `cardano-submit-api` or direct submission through the node
165+
166+
## Deeper Documentation
167+
168+
- [Haddock Documentation](https://cardano-api.cardano.intersectmbo.org/)
169+
170+
171+
## Contributing
172+
173+
This repository welcomes contributions. See the [Contributing Guide](https://github.com/IntersectMBO/cardano-api/blob/master/CONTRIBUTING.md) for details on code of conduct, development workflow, pull request process, and testing requirements.
174+

0 commit comments

Comments
 (0)