184 lines
3.9 KiB
Markdown
184 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Bundle processed successfully",
|
|
"bundle_id": "bundle-uuid"
|
|
}
|
|
```
|
|
|
|
### Submit Scry Binding Batch
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Scry bindings processed successfully",
|
|
"star_id": "12345",
|
|
"bindings_processed": 10
|
|
}
|
|
```
|
|
|
|
### Queue Status
|
|
|
|
```bash
|
|
# Get current bundle queue status (galaxy mode only)
|
|
curl http://localhost:8080/api/galaxy/queue/status
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"pending_bundles": 5,
|
|
"size_mb": 2.3,
|
|
"max_size_mb": 100
|
|
}
|
|
```
|
|
|
|
### Galaxy Health Check
|
|
|
|
```bash
|
|
# Check galaxy Janus server health
|
|
curl http://localhost:8080/api/galaxy/health
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Transaction queued for bundling"
|
|
}
|
|
```
|
|
|
|
### Submit Scry Binding
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Scry binding queued for submission"
|
|
}
|
|
```
|
|
|
|
### Star Status
|
|
|
|
```bash
|
|
# Get star node operational status
|
|
curl http://localhost:8080/api/star/status
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
# Check star Janus server health
|
|
curl http://localhost:8080/api/star/health
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"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](../documentation/janus.md) 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
|