Garuda Utility Engine¶

Status: Fase 5 — Voucher Garuda Pay (signed/API) live di monorepo
Terakhir diperbarui: 2026-07-05

Ringkasan¶

Garuda Utility Engine adalah lapisan terpusat untuk hak dan manfaat di ekosistem Garuda Chain. NFT (Garuda Digital Card) adalah salah satu carrier entitlement — bukan satu-satunya modul utilitas.

Wallet / Garuda Pay / Community
              ↓
    GET /api/v1/utility/entitlements/:address
              ↓
    @garuda-chain/utility-engine
              ↓
    Resolvers (on-chain GNFT) → Effect handlers (check-in, MDR)

Paket¶

Path	Peran
`packages/utility-engine/`	Logika murni: entitlements, effects, registry
`apps/api/src/utility/resolve.ts`	Adapter RPC → engine
`apps/api/src/routes/utility.ts`	REST API
`apps/wallet/src/lib/utilityEngine.ts`	Klien Wallet

Entitlement (Fase 1)¶

ID	Utilitas	Implemented	Handler
`membership.garuda-card`	Keanggotaan on-chain	✅	Resolver GNFT balance
`reward.check-in-boost`	+15% check-in	✅	`applyCheckInBoost` → community reward
`pay.mdr-discount`	−25% fee MDR merchant	✅	`computeGarudaPayMdr` di charge
`access.gnft-marketplace`	Pasar GNFT	✅	Akses fitur Wallet
`access.cultural-drop`	Whitelist drop budaya	❌	Belum — UI tidak aktif
`certificate.digital`	Sertifikat verifiable on-chain	✅	Resolver kategori CERTIFICATE (1)
`loyalty.stamp`	Cap loyalitas Garuda Pay	✅	`GarudaMultiToken` ID 1
`voucher.merchant`	Voucher merchant Garuda Pay	✅	`GarudaMultiToken` ID 2
`access.event-ticket`	Tiket event on-chain	❌	ID 3 — panel Wallet saja, belum gate event
`identity.verified`	KYC on-chain Garuda Identity	✅	`GarudaIdentity` level ≥ Standard
`identity.reputation`	Skor reputasi on-chain	✅	`GarudaIdentity.reputationScore`
`identity.soulbound-card`	GIDC soulbound	✅	`GarudaIdentity` GIDC NFT (soft soulbound)
`voucher.signed-pay`	Voucher diskon Garuda Pay	✅	EIP-712 API + redeem di charge

Fase 2 — Sertifikat Digital¶

Kategori on-chain NFTCategory.CERTIFICATE = 1 pada kontrak GarudaNFTMarketplace yang sama — tanpa deploy kontrak baru.

Komponen	Path
Portfolio split	`apps/api/src/nft/read.ts` — `membershipBalance` vs `certificates[]`
Metadata	`apps/api/src/nft/metadata.ts` — Program, Recipient, Issued, Verification URL
Store admin	`apps/api/src/nft/certificateStore.ts` — `data/gnft-certificates.json`
Mint admin	`POST /api/v1/admin/certificates/mint` (header `x-admin-key`)
Entitlements	`GET /api/v1/utility/certificates/:address`
Wallet UI	Tab Cards → panel Sertifikat Digital + link Explorer

Membership (kategori 0) dan sertifikat (kategori 1) dipisah di Wallet — sertifikat tidak muncul di grid GNFT kartu keanggotaan.

Fase 3 — ERC-1155 (Stamp, Voucher, Tiket)¶

Kontrak GarudaMultiToken sudah deployed — tanpa deploy kontrak baru.

Token Type ID	Utilitas	Kontrak
`1`	Loyalty Stamp	`GarudaMultiToken`
`2`	Merchant Voucher	`GarudaMultiToken`
`3`	Event Ticket	`GarudaMultiToken` (UI only, entitlement belum aktif)

Komponen	Path
Read balances	`apps/api/src/nft/multiTokenRead.ts`
Metadata	`apps/api/src/nft/multiTokenMetadata.ts`
Store admin	`apps/api/src/nft/multiTokenStore.ts` — `data/gnft-multi-token.json`
Mint admin	`POST /api/v1/admin/multi-token/mint`
Entitlements	`GET /api/v1/utility/multi-token/:address`
Wallet UI	Tab Cards → panel Stamp & Voucher

# Mint loyalty stamp (admin)
curl -X POST https://api.garudachain.id/api/v1/admin/multi-token/mint \
  -H "Content-Type: application/json" \
  -H "x-admin-key: $ADMIN_KEY" \
  -d '{"address":"0x...","tokenId":1,"amount":5,"note":"10 transaksi Garuda Pay"}'

Fase 4 — Identitas Soulbound (GarudaIdentity)¶

Carrier: kontrak GarudaIdentity (GIDC ERC-721 + DID + KYC + reputasi) — tanpa deploy kontrak baru.

Komponen	Path
Read identity	`apps/api/src/identity/read.ts`
Entitlements	`GET /api/v1/utility/identity/:address`
Wallet UI	Tab Cards → panel Identitas Soulbound
Wallet on-chain	`apps/wallet/src/lib/identity.ts` — DID register

Pemisahan peran: - GIDC (GarudaIdentity) = identitas soulbound + reputasi (non-transferable by policy) - GNFT cat 0 = kartu keanggotaan transferable (check-in, MDR, marketplace)

Catatan: On-chain transfer lock belum di-enforce di bytecode — Phase 4 = integrasi utilitas + soft soulbound (Wallet/API tidak menawarkan transfer GIDC).

Fase 5 — Voucher Signed/API¶

Voucher off-chain bertanda tangan EIP-712 — dipakai saat checkout Garuda Pay (tanpa mint on-chain).

Komponen	Path
Store	`apps/api/src/voucher/signedVoucherStore.ts`
Engine	`apps/api/src/voucher/signedVoucherEngine.ts`
Issue admin	`POST /api/v1/admin/vouchers/issue`
List / verify	`GET /api/v1/utility/vouchers/:address` · `.../verify/:id`
Redeem	`POST /api/v1/garuda-pay/charge` + body `voucherId`
Wallet	Cards → Voucher Garuda Pay + selector merchant pay

Pemisahan: voucher.merchant (Phase 3) = ERC-1155 inventory · voucher.signed-pay (Phase 5) = diskon checkout API.

API¶

`GET /api/v1/utility/entitlements/:address`¶

Response: UtilitySnapshot — membership, entitlements[], display[], checkInMultiplier.

`GET /api/v1/utility/definitions`¶

Daftar definisi entitlement (dokumentasi).

Backward compatible¶

GET /api/v1/network/gnft/perks/:address tetap ada — memakai engine di belakang layar.

Menambah utilitas baru¶

Tambah EntitlementId di packages/utility-engine/src/types.ts
Daftarkan di registry.ts dengan implemented: true hanya jika handler siap
Update resolveEntitlements() dengan resolver baru
Tambah effect handler (mis. effects/certificate.ts)
Panggil handler dari route API yang relevan
Wallet otomatis menampilkan via display[] setelah fetch entitlements

Tidak perlu modul NFT terpisah per fitur.

Fase 6 — Governance & Otomatisasi¶

Komponen	Path
Program store	`apps/api/src/utility/programStore.ts`
Audit log	`apps/api/src/utility/auditLog.ts`
Admin roles	`apps/api/src/middleware/adminAuth.ts` — `super` / `ops` / `marketing`
Aturan otomatis	`apps/api/src/utility/automationStore.ts` + `automationEngine.ts`
Batch sertifikat	`POST /api/v1/admin/utility-engine/certificates/batch`
Admin UI	`UtilityGovernanceSection` di admin Utilitas

Role admin (env)¶

Env	Role	Izin
`ADMIN_API_KEY`	super	Semua
`ADMIN_OPS_KEY`	ops	Sertifikat, program, batch, audit, aturan
`ADMIN_MARKETING_KEY`	marketing	ERC-1155, voucher signed, audit, aturan

Header: x-admin-key

Aturan otomatis (default aktif)¶

loyalty-stamp-on-payment — setiap transaksi merchant Garuda Pay → +1 stamp ERC-1155
voucher-gnft-min-tx — GNFT + min Rp500.000 → voucher signed Rp50.000
stamp-full-reward — stamp 10/10 → voucher Rp25.000 (sekali per wallet)

Hook: apps/api/src/routes/garudaPay.ts setelah charge sukses.

Program sertifikat¶

# Buat program
curl -X POST https://api.garudachain.id/api/v1/admin/utility-engine/programs \
  -H "x-admin-key: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Pelatihan UMKM Go Digital","issuer":"Garuda Chain"}'

# Mint dengan programId
curl -X POST https://api.garudachain.id/api/v1/admin/certificates/mint \
  -H "x-admin-key: $KEY" -d '{"address":"0x...","programId":"pelatihan-umkm-go-digital","recipientName":"Nama"}'

Roadmap engine¶

Fase	Carrier	Contoh
1 ✅	ERC-721 GNFT	Membership, check-in, MDR
2 ✅	ERC-721 Certificate	Sertifikat pelatihan UMKM, verifikasi Explorer
3 ✅	ERC-1155	Loyalty stamp, voucher merchant (tiket: UI saja)
4 ✅	Soulbound (GarudaIdentity)	GIDC, KYC, reputasi on-chain
5 ✅	Signed / API	Voucher diskon Garuda Pay (EIP-712)
6 ✅	Governance	Program, audit, role admin, otomatisasi Garuda Pay

Prinsip¶

Lihat UTILITY_NFT_PRINCIPLES.md.

Referensi kode¶

Engine: packages/utility-engine/src/engine.ts
MDR: packages/utility-engine/src/effects/mdr.ts
Check-in: packages/utility-engine/src/effects/checkIn.ts
Charge: apps/api/src/routes/garudaPay.ts (merchant MDR discount)