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 (member) · +25% (collector ≥3 kartu)	✅	`applyCheckInBoost` → community check-in only
`reward.soft-staking-boost`	+5% estimasi APR tampilan (member) · +10% (collector)	✅	`applySoftStakingApr` → Staking Hub UI only · bukan APY kontrak
`reward.soft-gas-discount`	−5% estimasi gas Bridge (member) · −10% (collector)	✅	`applySoftGasEstimate` → Bridge ringkasan only · bukan fee GDC / gas-aid
`pay.mdr-discount`	−25% fee MDR merchant	✅	`computeGarudaPayMdr` di charge
`access.gnft-marketplace`	Pasar GNFT	✅	Akses fitur Wallet
`access.cultural-drop`	Whitelist drop budaya (Batik/Wayang/Nusa)	✅	Join API + Cards CTA untuk holder GNFT
`certificate.digital`	Sertifikat verifiable on-chain	✅	Resolver kategori CERTIFICATE (1)
`certificate.property-umkm`	Bukti aset UMKM (catatan on-chain)	✅	Resolver kategori PROPERTY (2) · admin mint · Cards + Explorer
`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 + QR check-in	✅	ERC-1155 id 3 · `POST /utility/event-ticket/verify`
`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

Terakhir diperbarui: 2026-07-08

Cultural Drop Whitelist¶

Endpoint	Auth	Fungsi
`GET /api/v1/utility/cultural-drop/status/:address`	Wallet	Status eligible / joined
`POST /api/v1/utility/cultural-drop/join`	Wallet	Daftar whitelist (idempotent)
`GET /api/v1/utility/cultural-drop/count`	Public	Jumlah entri
`GET /api/v1/admin/cultural-drop/whitelist`	Admin	Export list
`POST /api/v1/admin/cultural-drop/whitelist`	Admin	Tambah manual

Store: data/gnft-cultural-drop.json · Wallet CTA di Cards → Koleksi Garuda.

Event Ticket Gate¶

Endpoint	Auth	Fungsi
`GET /api/v1/utility/event-ticket/events`	Public	Event aktif
`GET /api/v1/utility/event-ticket/status/:address`	Wallet	Saldo tiket + QR payload
`POST /api/v1/utility/event-ticket/verify`	Public	Scanner pintu (admitted jika balance id 3 > 0)
`GET/POST /api/v1/admin/event-ticket/events`	Admin	Kelola event

Mint: POST /api/v1/admin/multi-token/mint { tokenId: 3, amount: 1, address } · Store check-in: data/gnft-event-tickets.json (belum burn on-chain).

Merchant Trust Badge (Sertifikat)¶

Endpoint	Auth	Fungsi
`GET /api/v1/utility/merchant-trust/:address`	Public	`{ trustBadge, certificateCount, primary, label }` dari `certificate.digital`

Wallet: chip di Preview QR Merchant, Receive QR, dan header bayar merchant (display-only: tidak mengubah charge/MDR).

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` · verify API + Cards QR
`4`	Stamp Jakarta Café	`GarudaMultiToken` · otomasi pay jika kota merchant = Jakarta
`5`	Stamp Bandung Mitra	`GarudaMultiToken` · otomasi pay jika kota merchant = Bandung

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)
regional-stamp-jakarta: charge dengan merchantCity mengandung jakarta → +1 token id 4; penuh → voucher mitra daerah
regional-stamp-bandung: sama untuk bandung → token id 5

Kota diambil dari field opsional merchantCity pada body /garuda-pay/charge (dari lokasi QR merchant). Tidak mengubah MDR/nominal.

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, tiket event, stamp regional Jakarta/Bandung
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)