zenith-docs/docs/api/janus.md

Janus Server API

The Janus server provides HTTP endpoints for accepting transaction bundles and scry bindings. The Janus server runs in-process for galaxy validators and as part of zenithd in star mode. Endpoints are available based on the node's operational mode.

Galaxy Endpoints

Galaxy endpoints are only available when zenithd is running in galaxy mode. These endpoints accept protobuf-encoded data.

Submit Transaction Bundle

# Submit a protobuf-encoded bundle from a star
# The bundle includes star ID, transactions, and star signature
curl -X POST http://localhost:8080/api/galaxy/submit/bundle \
  -H "Content-Type: application/octet-stream" \
  --data-binary @bundle.pb

Response:

{
  "success": true,
  "message": "Bundle processed successfully",
  "bundle_id": "bundle-uuid"
}

Submit Scry Binding Batch

# Submit a protobuf-encoded scry batch from a star
# Includes star ID, scry bindings with individual signatures
curl -X POST http://localhost:8080/api/galaxy/submit/scry \
  -H "Content-Type: application/octet-stream" \
  --data-binary @scry_batch.pb

Response:

{
  "success": true,
  "message": "Scry bindings processed successfully",
  "star_id": "12345",
  "bindings_processed": 10
}

Queue Status

# Get current bundle queue status (galaxy mode only)
curl http://localhost:8080/api/galaxy/queue/status

Response:

{
  "pending_bundles": 5,
  "size_mb": 2.3,
  "max_size_mb": 100
}

Galaxy Health Check

# Check galaxy Janus server health
curl http://localhost:8080/api/galaxy/health

Response:

{
  "status": "healthy",
  "server": "janus",
  "node_mode": "galaxy"
}

Star Endpoints

Star endpoints are available when zenithd is running in star or galaxy mode. These endpoints accept transactions and scry bindings from planets.

Submit Transaction

# Submit a protobuf-encoded transaction from a planet
curl -X POST http://localhost:8080/api/star/submit/tx \
  -H "Content-Type: application/octet-stream" \
  --data-binary @transaction.pb

Response:

{
  "success": true,
  "message": "Transaction queued for bundling"
}

Submit Scry Binding

# Submit a scry binding with Ed25519 signature
curl -X POST http://localhost:8080/api/star/submit/scry \
  -H "Content-Type: application/json" \
  -d '{
    "scry-binding": {
      "path": "/~sampel-palnet/app/data",
      "hash": "0xabc123...",
      "signature": "0xdef456...",
      "life": 1
    }
  }'

Response:

{
  "success": true,
  "message": "Scry binding queued for submission"
}

Star Status

# Get star node operational status
curl http://localhost:8080/api/star/status

Response:

{
  "success": true,
  "data": {
    "node_type": "star",
    "star_id": 12345,
    "timestamp": "2024-01-01T00:00:00Z",
    "pending_transactions": 5,
    "pending_scry_bindings": 3,
    "galaxy_url": "https://galaxy.example.com",
    "max_tx_per_bundle": 100,
    "bundle_timeout": "30s",
    "scry_batch_size": 50,
    "scry_batch_timeout": "60s",
    "require_signatures": true
  }
}

Star Health Check

# Check star Janus server health
curl http://localhost:8080/api/star/health

Response:

{
  "status": "healthy",
  "server": "janus",
  "node_mode": "star",
  "zenith_key_loaded": true
}

!!! note "Janus Configuration" The Janus server configuration (port, endpoints, etc.) is managed through the zenithd configuration file. See the Janus documentation for more details on the transaction aggregation architecture.

!!! warning "Mode Restrictions" - Galaxy endpoints (/api/galaxy/*) only work in galaxy mode - Star endpoints (/api/star/*) work in both star and galaxy modes - Attempting to access galaxy endpoints in star mode returns a 403 Forbidden error