README
¶
ARES Core
ARES Core is a cryptographic framework for blind ranking, sealed-bid auctions, and selective-reveal protocols. It composes N-party cryptographic sessions from pluggable units called phases:
- Threshold CKKS keygen, FHE scoring, and threshold decrypt — out of the box.
- Pluggable input shapes, scoring circuits, and post-result phases.
- Pluggable trust models — multi-party threshold, single-party trusted, plaintext (for testing), or pre-shared / amortized keygen.
The framework intentionally ships no opinionated default pipeline.
Applications compose their own via phase.Compose(...) from generic
primitives in pkg/ares/phase/defaults/ and pkg/ares/phase/keygen/,
plus their own input-submission / scoring / post-result phases.
Status: pre-1.0. Minor version bumps may include breaking API changes. See CHANGELOG.md for the migration path.
Reference apps
Four worked examples ship under examples/:
| App | Path | Pipeline | Depth |
|---|---|---|---|
| Sealed-bid auction | examples/sealed_bid_auction/ |
6 phases — scalar bid + argmax | 10 |
| Ride share | examples/ride_share/ |
6 phases — composite score (price × proximity) | 12 |
| Recurring cohort ranking | examples/recurring_cohort_ranking/ |
10 phases across 2 runners — amortized keygen | 10 |
| Blind voting | examples/voting/ |
5 phases — PlaintextKeygen + sum-weighted tally |
n/a |
The dating-app reference implementation built on this framework lives at fheya.de — it's not open-source, but exists as proof the framework supports the most complex shape it's designed for (cosine + location + reputation scoring across 6 parties at depth 30).
Quickstart
import auction "github.com/Fheyalabs/ARES-core/examples/sealed_bid_auction"
runner, err := auction.Pipeline()
ctx, err := runner.BeginSession("auction-1", "")
// Route messages through runner.HandleMessage(...)
For a hand-composed pipeline see
pkg/ares/phase/README.md.
Install
Go dependency
go get github.com/Fheyalabs/ARES-core@latest
OpenFHE prerequisite
ARES Core links the OpenFHE 1.5.x C++ library for its CKKS primitives. Pin to 1.5.1 — earlier versions choose different cyclotomic primes for the same nominal parameters and ciphertexts won't interoperate across versions (the framework detects this and refuses to proceed).
git clone --branch v1.5.1 --depth 1 https://github.com/openfheorg/openfhe-development.git
cd openfhe-development
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
make -j$(nproc) # or `sysctl -n hw.ncpu` on macOS
sudo make install
ARES Core's cgo paths search /usr/local, /opt/homebrew, and
/usr/local/lib64 by default. For other prefixes, override via
CGO_CXXFLAGS / CGO_LDFLAGS — see
pkg/ares/crypto/cgo/bridge.go for the
exact override pattern, and pkg-config/openfhe.pc.in for a
pkg-config template.
Build the helper binary
git clone https://github.com/Fheyalabs/ARES-core.git
cd ARES-core
go build -tags openfhe -o bin/openfhe-helper ./cmd/openfhe-contract-helper
./bin/openfhe-helper --version # should print v1.5.1
Run tests
go test ./... # Go-only tests; no OpenFHE needed
go test -tags openfhe ./... # full suite; requires OpenFHE
Documentation
- Framework concepts and customizing recipes
- Reference apps overview above
- Python smoke scripts
- Deployment recipes for homelab
- CHANGELOG.md
Contributing
Pull requests welcome — see CONTRIBUTING.md. Security issues: please follow SECURITY.md rather than filing public issues.
All participants are expected to follow the Code of Conduct.
License
Apache License 2.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
openfhe-contract-helper
command
|
|
|
examples
|
|
|
recurring_cohort_ranking
Package cohort demonstrates the amortized-keygen fast path: the same N participants form a long-lived cohort and run MANY sessions against one collective key bundle.
|
Package cohort demonstrates the amortized-keygen fast path: the same N participants form a long-lived cohort and run MANY sessions against one collective key bundle. |
|
recurring_cohort_ranking/cmd/session-service
command
Command session-service runs the recurring-cohort-ranking example as a standalone HTTP+WebSocket service.
|
Command session-service runs the recurring-cohort-ranking example as a standalone HTTP+WebSocket service. |
|
ride_share
Package rideshare demonstrates an inDrive-style ride-sharing application on ARES: one rider and N drivers submit encrypted bids reflecting price and location.
|
Package rideshare demonstrates an inDrive-style ride-sharing application on ARES: one rider and N drivers submit encrypted bids reflecting price and location. |
|
ride_share/cmd/session-service
command
Command session-service runs the ride-share example as a standalone HTTP+WebSocket service.
|
Command session-service runs the ride-share example as a standalone HTTP+WebSocket service. |
|
sealed_bid_auction
Package auction is a worked example showing how to build a non-Fheya application on top of the ARES framework.
|
Package auction is a worked example showing how to build a non-Fheya application on top of the ARES framework. |
|
sealed_bid_auction/cmd/session-service
command
Command session-service runs the sealed-bid auction example as a standalone HTTP+WebSocket service.
|
Command session-service runs the sealed-bid auction example as a standalone HTTP+WebSocket service. |
|
voting
Package voting is a worked example showing how to build a non-FHE application on top of the ARES framework.
|
Package voting is a worked example showing how to build a non-FHE application on top of the ARES framework. |
|
pkg
|
|
|
ares/authclient
Package authclient implements the credential-issuance and verification primitives an ARES auth-service needs.
|
Package authclient implements the credential-issuance and verification primitives an ARES auth-service needs. |
|
ares/crypto/helperclient
Package helperclient is the Go-side IPC client for cmd/openfhe-contract-helper.
|
Package helperclient is the Go-side IPC client for cmd/openfhe-contract-helper. |
|
ares/phase
Package phase defines the core abstractions for composing ARES sessions out of pluggable units of work.
|
Package phase defines the core abstractions for composing ARES sessions out of pluggable units of work. |
|
ares/phase/defaults
Package defaults provides generic phase implementations the ARES framework ships out of the box.
|
Package defaults provides generic phase implementations the ARES framework ships out of the box. |
|
ares/phase/keygen
Package keygen provides alternative key-generation Phase implementations that slot into the same LOCKED → GOSSIP arc as defaults.Phase0aThresholdKeygen.
|
Package keygen provides alternative key-generation Phase implementations that slot into the same LOCKED → GOSSIP arc as defaults.Phase0aThresholdKeygen. |
|
ares/transport
Package transport provides the WebSocket hub, auth middleware, artifact store, HTTP admin surface, and session-lifecycle plumbing that an ARES application needs to host a SessionRunner over the network.
|
Package transport provides the WebSocket hub, auth middleware, artifact store, HTTP admin surface, and session-lifecycle plumbing that an ARES application needs to host a SessionRunner over the network. |