# Contributing to libantpeer

## Architecture

```
antpeer.hpp (public API)

  Bus              Abstract transport base class
    membus_open()  Factory: shared memory transport
    sockbus_open() Factory: TCP socket transport

  Server           Service endpoint (pimpl)
    on_request()   Request handler callback
    on_session()   Session message handler
    on_finish()    Session close handler
    on_notify()    N-verb broadcast handler
    on_accept()    V-verb identity handler
    on_verify()    Verify response handler
    on_auth()      Z-verb auth handler
    require_auth() Enable Ed25519 authentication
    add_route()    Multi-hop relay routing
    run()          Poll loop

  Client           Service consumer (pimpl)
    discover()     Find service on bus
    call()         Synchronous RPC (bytes or string)
    fire()         One-shot message (no reply)
    set_auth_key() Load Ed25519 private key
    set_route()    Multi-hop relay routing
    set_required() Mark peer as mandatory

  FrameExtractor   Protocol-correct frame extraction from byte streams

Ed25519Utils.hpp (crypto primitives)

  keygen()         Generate Ed25519 keypair
  sign() / verify() Signature operations
  nonce()          Random nonce generation
  save_key() / load_key() / load_trusted_keys()
```

## Source Files

| File | Purpose |
|------|---------|
| antpeer.cpp | Full implementation: Bus subclasses, Server::Impl, Client::Impl, FrameExtractor::Impl |
| Ed25519Utils.cpp | Ed25519 crypto via OpenSSL 3.0 EVP API |

## Build

```bash
make              # Build libantpeer.a + libantpeer.so
make test         # Build and run all 135 tests (87 + 48)
make install      # Install library + headers to /usr/local (sudo)
make uninstall    # Remove installed files (sudo)
make clean        # Remove build artifacts
```

## Dependencies

- [libantheos](https://langsyn.org/libantheos/latest/) — Antheos protocol codec
- [libmembus](https://langsyn.org/libmembus/latest/) — Shared memory transport
- [libsockbus](https://langsyn.org/libsockbus/latest/) — TCP socket transport
- OpenSSL 3.0 — Ed25519 cryptographic operations
- POSIX — pthreads, rt

## Coding Standards

- **C++17**, compiled with `-Wall -Wextra -Werror -O2 -fPIC`
- **Two public headers**: `antpeer.hpp` and `Ed25519Utils.hpp`
- Error handling: exceptions for lifecycle, return codes for operations
- Handler API: `std::function` callbacks with explicit reply
- Pimpl pattern for Server and Client (stable ABI)
- No commented-out code, no bare TODOs, no debug prints
- No trace, no protocol-specific logic beyond Antheos

## Test Suites

| Suite | Tests | What It Tests |
|-------|------:|---------------|
| unit_test | 87 | Bus, Server, Client, FrameExtractor, integration, identity, threaded dispatch, auth, relay |
| test_ed25519 | 48 | Keygen, sign/verify, nonce, key persistence, trusted key store, hex encoding |

## Before Submitting

- Run `make clean && make test` — all 135 tests must pass
- New public API requires documentation in header comments