service_layer

module

v1.0.0 Latest Latest Go to latest Published: Jan 28, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/R3E-Network/service_layer

Links

Open Source Insights

README ¶

The Multi-Chain MiniApp Platform for the Neo Economy

English · Documentation · Report Bug · Request Feature

NeoHub is a TEE-powered multi-chain MiniApp platform that combines a user-facing Gateway (Supabase Edge) with enclave workloads (MarbleRun + EGo) for secure signing and confidential computation. Powered by Neo and supporting Neo N3, NeoX, and Ethereum networks.

🚀 Multi-Chain Support - 🔒 TEE Security - 🎲 Provable Randomness

✅ Multi-Chain - Native support for Neo N3, NeoX, and Ethereum
✅ Secure - Intel SGX Enclaves for Trusted Execution Environments (TEE)
✅ Fair - Verifiable Random Function (VRF) with on-chain attestation
✅ Automation - Cron-based task scheduling and execution
✅ Confidential - Privacy-preserving computation for sensitive logic

Table of Contents

Overview
Architecture
Services
Platform Contracts
MiniApps
Quick Start
Repository Structure
Documentation
License

Overview

The NeoHub MiniApp Platform provides infrastructure for building decentralized MiniApps with multi-chain support:

60+ Production MiniApps across Gaming, DeFi, Social, NFT, and Governance categories
TEE Security via Intel SGX enclaves for confidential computation
Provable Randomness through VRF with on-chain attestation
Real-time Price Feeds from multiple oracle sources
Automated Workflows with cron-based task scheduling

Supported Chains

Chain	Type	Status
Neo N3	Native	✅ Production
NeoX	EVM-Compatible	✅ Production
Ethereum	EVM	✅ Production

Architecture

graph TD
    User[UserId / MiniApp Frontend] --> Gateway[Supabase Edge Gateway]
    Gateway --> VRF[TEE Services: VRF/Oracle]
    Gateway --> Compute[TEE Services: Compute/Auto]
    Gateway --> Signer[TEE Services: GlobalSigner]
    VRF --> Blockchain[Neo N3 Blockchain]
    Compute --> Blockchain
    Signer --> Blockchain
    Blockchain --> Contracts[Platform & MiniApp Contracts]

For detailed architecture, see docs/ARCHITECTURE.md.

Services

Service	ID	Description
VRF	`neovrf`	Verifiable random function with on-chain attestation
DataFeed	`neofeeds`	Real-time price feeds from multiple sources
Automation	`neoflow`	Cron-based task scheduling and execution
Compute	`neocompute`	Confidential computation in TEE
Oracle	`neooracle`	External data queries with TEE verification
TxProxy	`txproxy`	Transaction submission and gas management
GasBank	`neogasbank`	User GAS balance management
Simulation	`neosimulation`	Development and testing environment

Infrastructure:

globalsigner - Enclave-held signing keys
neoaccounts - HD-derived account pool (10,000+ accounts)

Platform Contracts

Deployed on Neo N3 Testnet:

Contract	Address	Description
PaymentHub	`NZLGNdQUa5jQ2VC1r3MGoJFGm3BW8Kv81q`	GAS payment processing
Governance	`NLRGStjsRpN3bk71KNoKe74fNxUT72gfpe`	NEO staking and voting
PriceFeed	`NTdJ7XHZtYXSRXnWGxV6TcyxiSRCcjP4X1`	Oracle price data
RandomnessLog	`NR9urKR3FZqAfvowx2fyWjtWHBpqLqrEPP`	VRF attestation anchoring
AppRegistry	`NXZNTXiPuBRHnEaKFV3tLHhitkbt3XmoWJ`	MiniApp registration
AutomationAnchor	`NcVrd4Z7W8sxv9jvdBF72xfiWBnvRsgVkx`	Periodic task scheduling
ServiceLayerGateway	`NTWh6auSz3nvBZSbXHbZz4ShwPhmpkC5Ad`	Service request routing

Mainnet addresses live in deploy/config/mainnet_contracts.json.

MiniApps (62 Apps)

All MiniApp contracts use the shared MiniAppContract partial class pattern and communicate with platform services via ServiceLayerGateway.

🎮 Gaming (15 Apps)

App	Contract	Description
Lottery	`MiniAppLottery`	Provable VRF lottery with jackpot
Coin Flip	`MiniAppCoinFlip`	50/50 double-or-nothing
Dice Game	`MiniAppDiceGame`	Roll dice, win up to 6x
Scratch Card	`MiniAppScratchCard`	Instant win scratch cards
Neo Crash	`MiniAppNeoCrash`	Multiplier crash game
No-Loss Lottery	`MiniAppNoLossLottery`	Stake to win, keep principal
Fog Chess	`MiniAppFogChess`	Chess with fog of war
Fog Puzzle	`MiniAppFogPuzzle`	Hidden puzzle solving
Secret Poker	`MiniAppSecretPoker`	TEE Texas Hold'em
Algo Battle	`MiniAppAlgoBattle`	Algorithm competition
Puzzle Mining	`MiniAppPuzzleMining`	Solve puzzles to earn
Crypto Riddle	`MiniAppCryptoRiddle`	Cryptographic puzzles
On-Chain Tarot	`MiniAppOnChainTarot`	VRF-based tarot readings
World Piano	`MiniAppWorldPiano`	Collaborative music creation
Scream to Earn	`MiniAppScreamToEarn`	Voice-activated rewards

💰 DeFi (14 Apps)

App	Contract	Description
Flash Loan	`MiniAppFlashLoan`	Instant borrow and repay
Grid Bot	`MiniAppGridBot`	Automated grid trading
AI Trader	`MiniAppAITrader`	Autonomous trading agent
Price Ticker	`MiniAppPriceTicker`	Real-time price feeds
Prediction Market	`MiniAppPredictionMarket`	Price movement predictions
IL Guard	`MiniAppILGuard`	Impermanent loss protection
Candle Wars	`MiniAppCandleWars`	Price candle predictions
Dark Pool	`MiniAppDarkPool`	Anonymous large trades
Dutch Auction	`MiniAppDutchAuction`	Descending price auctions
Self Loan	`MiniAppSelfLoan`	Self-collateralized loans
Compound Capsule	`MiniAppCompoundCapsule`	Auto-compounding yields
Quantum Swap	`MiniAppQuantumSwap`	Atomic token swaps
Melting Asset	`MiniAppMeltingAsset`	Time-decaying tokens
NeoBurger	External Integration	NEO staking for GAS rewards

App	Contract	Description
Red Envelope	`MiniAppRedEnvelope`	Social GAS red packets
Gas Circle	`MiniAppGasCircle`	Daily savings circle
Secret Vote	`MiniAppSecretVote`	Privacy-preserving voting
Whisper Chain	`MiniAppWhisperChain`	Anonymous messaging
Dev Tipping	`MiniAppDevTipping`	Developer appreciation
Bounty Hunter	`MiniAppBountyHunter`	Bug bounty platform
Breakup Contract	`MiniAppBreakupContract`	Relationship agreements
Ex Files	`MiniAppExFiles`	Shared memory vault
AI Soulmate	`MiniAppAISoulmate`	AI companion matching
Geo Spotlight	`MiniAppGeoSpotlight`	Location-based discovery
Masquerade DAO	`MiniAppMasqueradeDAO`	Anonymous governance
Dark Radio	`MiniAppDarkRadio`	Anonymous broadcasting

🎨 NFT (8 Apps)

App	Contract	Description
Canvas	`MiniAppCanvas`	Collaborative pixel art NFT
NFT Evolve	`MiniAppNFTEvolve`	Dynamic NFT evolution
NFT Chimera	`MiniAppNFTChimera`	NFT fusion and breeding
Schrodinger NFT	`MiniAppSchrodingerNFT`	Quantum state NFTs
Garden of Neo	`MiniAppGardenOfNeo`	Virtual garden NFTs
Million Piece Map	`MiniAppMillionPieceMap`	Collaborative world map
Pay to View	`MiniAppPayToView`	Gated content access
Graveyard	`MiniAppGraveyard`	NFT memorial

🏛️ Governance (6 Apps)

App	Contract	Description
Gov Booster	`MiniAppGovBooster`	NEO governance tools
Candidate Vote	`MiniAppCandidateVote`	Vote for consensus nodes
Gov Merc	`MiniAppGovMerc`	Governance delegation
Guardian Policy	`MiniAppGuardianPolicy`	TEE transaction security
Bridge Guardian	`MiniAppBridgeGuardian`	Cross-chain asset bridge
Burn League	`MiniAppBurnLeague`	Token burning competition

🔧 Utility (7 Apps)

App	Contract	Description
Time Capsule	`MiniAppTimeCapsule`	Time-locked messages
Dead Switch	`MiniAppDeadSwitch`	Dead man's switch
Heritage Trust	`MiniAppHeritageTrust`	Digital inheritance
Unbreakable Vault	`MiniAppUnbreakableVault`	Secure asset storage
ZK Badge	`MiniAppZKBadge`	Zero-knowledge credentials
Doomsday Clock	`MiniAppDoomsdayClock`	Countdown events
Parasite	`MiniAppParasite`	Token attachment protocol

Quick Start

Prerequisites

Go 1.21+
Docker & Docker Compose
Node.js 18+
Neo N3 wallet with testnet GAS

Local Development

# Start infrastructure
make docker-up

# Run a service locally
SERVICE_TYPE=neovrf go run ./cmd/marble

# Start the host app
cd platform/host-app && npm run dev

Full Stack (K3s)

./scripts/bootstrap_k3s_dev.sh --env-file .env --edge-env-file .env.local

See docs/LOCAL_DEV.md for detailed setup.

Environment Variables

Variable	Description
`SUPABASE_URL`	Supabase project URL
`SUPABASE_SERVICE_ROLE_KEY`	Supabase service role key
`SECRETS_MASTER_KEY`	Encryption key for secrets
`NEO_RPC_URL`	Neo N3 RPC endpoint
`NEO_NETWORK_MAGIC`	Network magic number
`CONTRACT_*_ADDRESS`	Platform contract addresses

See .env.example for complete list and the deploy/config/{testnet,mainnet}_contracts.json files for canonical addresses.

Repository Structure

├── cmd/                    # Binary entrypoints
├── contracts/              # Neo N3 smart contracts (C#)
├── infrastructure/         # Shared infrastructure (Go)
│   ├── globalsigner/       # TEE signing service
│   └── accountpool/        # HD account management
├── services/               # Product services (Go)
│   ├── vrf/                # Verifiable random function
│   ├── datafeed/           # Price feed aggregation
│   ├── automation/         # Task scheduling
│   └── ...
├── platform/               # Frontend & Gateway
│   ├── edge/               # Supabase Edge functions
│   ├── host-app/           # Next.js host application
│   └── sdk/                # MiniApp JavaScript SDK
├── docs/                   # Documentation
└── scripts/                # Build and deploy scripts

Documentation

Document	Description
ARCHITECTURE.md	System architecture and TEE boundary
WORKFLOWS.md	MiniApp lifecycle and callbacks
DATAFLOWS.md	Request flows and audit tables
API_DOCUMENTATION.md	Gateway and service APIs
DEPLOYMENT_GUIDE.md	Deployment paths
sdk-guide.md	MiniApp SDK integration

License

Proudly powered by

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
configure-miniapps command Command configure-miniapps configures all MiniApps in the PaymentHubV2 contract.	Command configure-miniapps configures all MiniApps in the PaymentHubV2 contract.
create-wallet command Command create-wallet creates a Neo N3 wallet from WIF.	Command create-wallet creates a Neo N3 wallet from WIF.
deploy-contracts command Command deploy-contracts provides a comprehensive CLI for managing Neo N3 smart contracts.	Command deploy-contracts provides a comprehensive CLI for managing Neo N3 smart contracts.
deploy-fairy command Package main provides a tool to deploy and test Service Layer contracts using Fairy.	Package main provides a tool to deploy and test Service Layer contracts using Fairy.
deploy-miniapps command Command deploy-miniapps deploys new MiniApp contracts to Neo N3 testnet.	Command deploy-miniapps deploys new MiniApp contracts to Neo N3 testnet.
deploy-miniapps-live command Command deploy-miniapps-live deploys MiniApp contracts to Neo N3 testnet.	Command deploy-miniapps-live deploys MiniApp contracts to Neo N3 testnet.
deploy-new-miniapps command Command deploy-new-miniapps deploys new MiniApp contracts to Neo N3 testnet.	Command deploy-new-miniapps deploys new MiniApp contracts to Neo N3 testnet.
deploy-paymenthub command Command deploy-paymenthub deploys a new PaymentHub contract to testnet using the master wallet.	Command deploy-paymenthub deploys a new PaymentHub contract to testnet using the master wallet.
deploy-testnet command Command deploy-testnet deploys Service Layer contracts to Neo N3 testnet.	Command deploy-testnet deploys Service Layer contracts to Neo N3 testnet.
indexer command
marble command Package main provides the generic Marble entry point for all Neo services.	Package main provides the generic Marble entry point for all Neo services.
master-bundle command
update-contract command Command update-contract updates a Neo N3 contract on testnet.	Command update-contract updates a Neo N3 contract on testnet.
update-paymenthub command Command update-paymenthub updates the PaymentHub contract on testnet.	Command update-paymenthub updates the PaymentHub contract on testnet.
verify-bundle command
contracts
cmd/update-paymenthub command Command update-paymenthub updates the PaymentHub contract on testnet.	Command update-paymenthub updates the PaymentHub contract on testnet.
deploy
testnet Package testnet provides Neo N3 testnet contract deployment.	Package testnet provides Neo N3 testnet contract deployment.
infrastructure
accountpool/client Package client provides a client SDK for the NeoAccounts service.	Package client provides a client SDK for the NeoAccounts service.
accountpool/marble Package neoaccounts provides API routes for the neoaccounts service.	Package neoaccounts provides API routes for the neoaccounts service.
accountpool/supabase Package supabase provides NeoAccounts-specific database operations.	Package supabase provides NeoAccounts-specific database operations.
accountpool/types Package types defines the shared API types for the neoaccounts service.	Package types defines the shared API types for the neoaccounts service.
chain Package chain provides base contract wrapper for service-specific contracts.	Package chain provides base contract wrapper for service-specific contracts.
chains
config Package config provides unified configuration loading helpers for service layer services.	Package config provides unified configuration loading helpers for service layer services.
crypto Package crypto provides cryptographic operations for the service layer.	Package crypto provides cryptographic operations for the service layer.
database Package database provides Supabase database integration.	Package database provides Supabase database integration.
datafeed Package datafeed provides Chainlink price feed integration for Arbitrum.	Package datafeed provides Chainlink price feed integration for Arbitrum.
errors Package errors provides unified error handling for the service layer	Package errors provides unified error handling for the service layer
execution Package execution provides MiniApp execution tracking via Supabase.	Package execution provides MiniApp execution tracking via Supabase.
gasbank/client Package client provides a client for the NeoGasBank service.	Package client provides a client for the NeoGasBank service.
globalsigner/client Package client provides a client for interacting with the GlobalSigner service.	Package client provides a client for interacting with the GlobalSigner service.
globalsigner/marble Package globalsigner provides the TEE master key management service.	Package globalsigner provides the TEE master key management service.
globalsigner/supabase
globalsigner/types Package types provides shared types for the GlobalSigner service.	Package types provides shared types for the GlobalSigner service.
hex Package hex provides unified hexadecimal string handling utilities.	Package hex provides unified hexadecimal string handling utilities.
httputil Package httputil provides common HTTP utilities for service handlers.	Package httputil provides common HTTP utilities for service handlers.
logging Package logging provides structured logging with trace ID support	Package logging provides structured logging with trace ID support
marble Package marble provides attestation utilities for TEE services.	Package marble provides attestation utilities for TEE services.
metrics Package metrics provides Prometheus metrics collection	Package metrics provides Prometheus metrics collection
middleware Package middleware provides HTTP middleware for the service layer.	Package middleware provides HTTP middleware for the service layer.
runtime Package runtime provides environment/runtime detection helpers shared across the service layer.	Package runtime provides environment/runtime detection helpers shared across the service layer.
secrets
secrets/supabase Package supabase provides Secrets-specific database operations.	Package supabase provides Secrets-specific database operations.
security Package security provides security utilities for the service layer	Package security provides security utilities for the service layer
service Package service provides common service infrastructure.	Package service provides common service infrastructure.
serviceauth Package serviceauth provides shared helpers for service-to-service authentication.	Package serviceauth provides shared helpers for service-to-service authentication.
testutil
txproxy/client Package client provides an HTTP client for the TxProxy service.	Package client provides an HTTP client for the TxProxy service.
txproxy/types Package types provides shared request/response types for the TxProxy service.	Package types provides shared request/response types for the TxProxy service.
utils Package utils provides common utility functions shared across all service layer services	Package utils provides common utility functions shared across all service layer services
scripts
services
automation/marble Package neoflow provides API routes for the task neoflow service.	Package neoflow provides API routes for the task neoflow service.
automation/supabase Package supabase provides NeoFlow-specific database operations.	Package supabase provides NeoFlow-specific database operations.
confcompute/marble Package neocompute provides API routes for the neocompute service.	Package neocompute provides API routes for the neocompute service.
conforacle/marble Package neooracle provides API routes for the neooracle service.	Package neooracle provides API routes for the neooracle service.
datafeed/marble Package neofeeds provides API routes for the price feed aggregation service.	Package neofeeds provides API routes for the price feed aggregation service.
gasbank/marble Package neogasbank provides GasBank service for managing user gas balances.	Package neogasbank provides GasBank service for managing user gas balances.
indexer Package indexer provides Neo N3 blockchain transaction indexing with VM execution tracing.	Package indexer provides Neo N3 blockchain transaction indexing with VM execution tracing.
requests/marble Package neorequests provides on-chain service request dispatch.	Package neorequests provides on-chain service request dispatch.
requests/supabase Package supabase provides NeoRequests-specific database operations.	Package supabase provides NeoRequests-specific database operations.
simulation/contracts Package contracts provides contract invocation utilities for the simulation service.	Package contracts provides contract invocation utilities for the simulation service.
simulation/marble Package neosimulation provides simulation service for automated transaction testing.	Package neosimulation provides simulation service for automated transaction testing.
txproxy/marble
vrf/marble Package neovrf provides verifiable randomness service.	Package neovrf provides verifiable randomness service.
test
e2e Package e2e holds end-to-end tests that require external dependencies (Docker, neo-express, Supabase, etc.).	Package e2e holds end-to-end tests that require external dependencies (Docker, neo-express, Supabase, etc.).
fairy Package fairy provides a Go client for Neo Fairy RPC.	Package fairy provides a Go client for Neo Fairy RPC.