Skip to content

Directory API

Endpoints for the decentralised account directory. The directory maps account addresses to libp2p peer IDs, enabling nodes to discover how to reach a specific account over the network.

Register Account

POST /directory/register

Registers an account in the directory, associating it with a libp2p peer ID.

Request Body

{
  "account": "a1b2c3d4...",
  "node_peer": "12D3KooWAbCdEfGhIjKlMnOpQrStUvWxYz...",
  "timestamp": 1709500000000000000,
  "signature": "b8c9d0e1..."
}
Field Type Description
account string Hex-encoded ed25519 public key
node_peer string libp2p peer ID of the node hosting this account
timestamp integer Unix nanosecond timestamp
signature string ed25519 signature over account + timestamp

Signature Verification

The signature is computed over the concatenation of the account public key bytes and the timestamp bytes (big-endian int64):

message   = account_bytes || timestamp_bytes
signature = ed25519.Sign(private_key, message)

This proves the registrant controls the account's private key.

Response

{
  "ok": true
}

Errors

Status Description
400 Invalid registration (bad signature, missing fields)

TTL and Pruning

Registrations expire

Directory entries have a 30-minute TTL. Entries older than 30 minutes are automatically pruned. Nodes must re-register periodically to remain discoverable.

Registrations are propagated to other nodes via gossip.

Example

curl -X POST http://localhost:8080/directory/register \
  -H "Content-Type: application/json" \
  -d '{
    "account": "a1b2c3d4...",
    "node_peer": "12D3KooWAbCdEfGhIjKlMnOpQrStUvWxYz...",
    "timestamp": 1709500000000000000,
    "signature": "b8c9d0e1..."
  }'

List All Registrations

GET /directory

Returns all current directory registrations (those within the TTL window).

Response

[
  {
    "account": "a1b2c3d4...",
    "node_peer": "12D3KooWAbCdEfGhIjKlMnOpQrStUvWxYz...",
    "timestamp": 1709500000000000000,
    "signature": "b8c9d0e1..."
  },
  {
    "account": "e5f6a7b8...",
    "node_peer": "12D3KooWZyXwVuTsRqPo...",
    "timestamp": 1709500060000000000,
    "signature": "d5e6f7a8..."
  }
]

Example

curl http://localhost:8080/directory

Lookup Account Registration

GET /directory/{account}

Returns the directory registration for a specific account.

Path Parameters

Parameter Type Description
account string Hex-encoded ed25519 public key

Response

{
  "account": "a1b2c3d4...",
  "node_peer": "12D3KooWAbCdEfGhIjKlMnOpQrStUvWxYz...",
  "timestamp": 1709500000000000000,
  "signature": "b8c9d0e1..."
}

Errors

Status Description
404 Account not found in directory

Example

curl http://localhost:8080/directory/a1b2c3d4...