You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Session 14: Repository Walkthrough: Offchain and SDK building - Notes
7
+
# Repository Walkthrough: Offchain and SDK building
8
8
9
-
Notes and resources exploring the offchain architecture of a production smart contract and SDK integration.
9
+
## Introduction
10
10
11
-
## Overview
11
+
This session is a continuation of the Q4 2025 walkthrough, shifting focus from the onchain code to the **offchain integration and SDK building**. We explore how to interact with the Payment Subscription Smart Contract built by Anastasia Labs, how to structure an SDK, and how to build transactions to interact with Cardano smart contracts using Lucid Evolution.
12
12
13
-
In this session, we explored the Cardano SDK ecosystem, repositories, and architecture.
13
+
## Recap: The Smart Contract Architecture
14
14
15
-
## Additional Resources
15
+
Before diving into the offchain code, we briefly recapped the three main validators of the contract:
16
+
1.**Account Validator**: Acts as authentication. Uses CIP-68 standards to mint a paired reference token (sent to the contract) and user token (sent to the user's wallet).
17
+
2.**Service Validator**: Used by merchants to define subscription services (e.g., Netflix-like plans) with specific fees and intervals.
18
+
3.**Payment Validator**: Handles linear vesting, locking funds, and allowing merchants to withdraw fees periodically while letting users cancel or extend subscriptions.
16
19
17
-
-*(Links and resources will be added here after the session)*
20
+
## The Offchain SDK Structure
21
+
22
+
A well-structured SDK is critical to lower the barrier to entry for Cardano developers. The project is organized into clear directories:
23
+
-**`docs/`**: API endpoints documentation (in partnership with Maestro).
24
+
-**`src/`**: The main source code.
25
+
-**`core/`**: Contains helper functions and compiled contract blueprints (`plutus.json`).
26
+
-**`endpoints/`**: Contains the transaction building logic for each contract action (e.g., `createService`, `updateService`).
27
+
-**`examples/`**: Code snippets demonstrating how a third-party developer can use the SDK.
28
+
29
+
## Transaction Building Walkthrough
30
+
31
+
Using **Lucid Evolution** (though MashJS or others are viable), we walked through the `createService` endpoint to understand transaction building:
32
+
33
+
### 1. Extracting the Validator
34
+
The `plutus.json` blueprint is parsed to extract the specific validator needed. Helper functions abstract this process to quickly get the required endpoints and policy IDs.
35
+
36
+
### 2. Collecting UTXOs and Minting
37
+
The user's wallet is connected to select the necessary UTXOs. For creating a service:
38
+
- The SDK mints two NFTs (Service Reference NFT and Service NFT) adhering to the CIP-68 standard.
39
+
- The reference NFT is sent to the smart contract, and the user NFT goes to the merchant's wallet.
40
+
41
+
### 3. Configuring the Datum
42
+
The SDK wraps all required parameters (e.g., service fee, interval length, penalty fee) into a `Config` object. This config is then formatted to match the exact `Datum` structure expected by the onchain code.
43
+
44
+
### 4. Building the Transaction
45
+
```typescript
46
+
lucid.newTx()
47
+
.collectFrom(...)
48
+
.mintAssets(...)
49
+
.payToAddress(merchantAddress, ...)
50
+
.payToContract(contractAddress, { inline: datum }, ...)
51
+
.attachMintingPolicy(...)
52
+
.complete()
53
+
```
54
+
*Note: The codebase utilizes the **Effect Library** in TypeScript (often seen via the `yield*` and `Effect.gen` syntax) to enforce robust type-safety, error handling, and standard execution flows.*
55
+
56
+
## Testing the SDK
57
+
58
+
Testing offchain code is just as important as the onchain code. The repository contains extensive tests:
59
+
- Tests populate dummy configurations (simulating what a user would input).
60
+
- Tests run the endpoint logic to ensure transactions build correctly.
61
+
- Helper functions sign and submit these test transactions to ensure end-to-end reliability.
62
+
63
+
## Key Takeaways
64
+
-**SDKs Drive Adoption**: Wrapping complex smart contracts into clean, well-documented SDKs is one of the biggest opportunities in the Cardano ecosystem. It allows frontend developers to build without needing to write or understand Plutus.
65
+
-**Blueprint Alignment**: The offchain code's main job is exactly mirroring the constraints, datums, and redeemers defined in the onchain design specification.
0 commit comments