Skip to content

HTTP_API.md

Latest commit

 

History

History
389 lines (345 loc) · 10.2 KB

HTTP_API.md

File metadata and controls

389 lines (345 loc) · 10.2 KB
Raw

Basis Tracker HTTP API

This document provides instructions for running the Basis Tracker HTTP API server.

Prerequisites

  • Rust and Cargo installed (latest stable version)
  • Clone the basis-tracker repository

Running the HTTP API Server

Method 1: From the workspace root

cd /home/kushti/bml/basis-tracker

# Build and run the server
cargo run -p basis_server

# The server will start and display: "DEBUG basis_server: listening on 127.0.0.1:3048"

Method 2: From the server crate directory

cd /home/kushti/bml/basis-tracker/crates/basis_server

# Build and run the server
cargo run

Method 3: Build and run separately

cd /home/kushti/bml/basis-tracker

# Build the server
cargo build -p basis_server

# Run the built binary
./target/debug/basis_server

Server Information

Current Endpoints

GET /

  • Description: Basic health check endpoint
  • Response: "Hello, Basis Tracker API!"
  • Example: 
    curl http://localhost:3000/

POST /notes

  • Description: Create a new IOU note
  • Request Body: 
    {
  "recipient_pubkey": [byte array (33 bytes)],
  "amount": 1000,
  "timestamp": 1234567890,
  "signature": [byte array (64 bytes)],
  "issuer_pubkey": [byte array (33 bytes)]
}
  • Response: 
    {
  "success": true,
  "data": null,
  "error": null
}
  • Example: 
    curl -X POST http://localhost:3000/notes \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_pubkey": [2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2],
    "amount": 1000,
    "timestamp": 1234567890,
    "signature": [3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3],
    "issuer_pubkey": [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1]
  }'

GET /notes/issuer/{pubkey}

  • Description: Get all notes for a specific issuer
  • Path Parameter: pubkey - Hex-encoded issuer public key (66 characters)
  • Response: 
    {
  "success": true,
  "data": [
    {
      "recipient_pubkey": "hex-encoded public key",
      "amount": 1000,
      "timestamp": 1234567890,
      "signature": "hex-encoded signature"
    }
  ],
  "error": null
}
  • Example: 
    curl http://localhost:3000/notes/issuer/010101010101010101010101010101010101010101010101010101010101010101

GET /notes/issuer/{issuer_pubkey}/recipient/{recipient_pubkey}

  • Description: Get a specific note by issuer and recipient public keys
  • Path Parameters:
    • issuer_pubkey - Hex-encoded issuer public key (66 characters)
    • recipient_pubkey - Hex-encoded recipient public key (66 characters)
  • Response: 
    {
  "success": true,
  "data": {
    "recipient_pubkey": "hex-encoded public key",
    "amount": 1000,
    "timestamp": 1234567890,
    "signature": "hex-encoded signature"
  },
  "error": null
}
  • Example: 
    curl http://localhost:3000/notes/issuer/010101010101010101010101010101010101010101010101010101010101010101/recipient/020202020202020202020202020202020202020202020202020202020202020202

POST /reserves/create

  • Description: Create a new reserve creation payload for Ergo node's /wallet/payment/send API
  • Request Body: 
    {
  "nft_id": "hex-encoded tracker NFT ID",
  "owner_pubkey": "hex-encoded 33-byte public key",
  "erg_amount": 1000000000
}
  • Response: 
    {
  "success": true,
  "data": {
    "requests": [
      {
        "address": "ergo P2S address of the reserve contract",
        "value": 1000000000,
        "assets": [
          {
            "token_id": "hex-encoded NFT token ID",
            "amount": 1
          }
        ],
        "registers": {
          "R4": "owner public key",
          "R5": "tracker NFT ID"
        }
      }
    ],
    "fee": 1000000,
    "change_address": "default"
  },
  "error": null
}
  • Example: 
    curl -X POST http://localhost:3000/reserves/create \
  -H "Content-Type: application/json" \
  -d '{
    "nft_id": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "owner_pubkey": "010101010101010101010101010101010101010101010101010101010101010101",
    "erg_amount": 1000000000
  }'

GET /reserves/issuer/{pubkey}

  • Description: Get all reserves for a specific issuer
  • Path Parameter: pubkey - Hex-encoded issuer public key (66 characters)
  • Response: 
    {
  "success": true,
  "data": [
    {
      "box_id": "hex-encoded reserve box id",
      "owner_pubkey": "hex-encoded public key",
      "collateral_amount": 1000000000,
      "total_debt": 500000000,
      "tracker_nft_id": "hex-encoded tracker nft id",
      "last_updated_height": 1000,
      "last_updated_timestamp": 1234567890,
      "collateralization_ratio": 2.0
    }
  ],
  "error": null
}
  • Example: 
    curl http://localhost:3000/reserves/issuer/010101010101010101010101010101010101010101010101010101010101010101

GET /events

  • Description: Get recent tracker events (all event types)
  • Response: Returns the 50 most recent events
  • Response Format: 
    {
  "success": true,
  "data": [
    {
      "id": 1,
      "type": "NoteUpdated",
      "timestamp": 1234567890,
      "issuer_pubkey": "hex-encoded public key",
      "recipient_pubkey": "hex-encoded public key",
      "amount": 1000,
      "reserve_box_id": "box1234567890abcdef",
      "collateral_amount": 1000000000,
      "redeemed_amount": 500000000,
      "height": 1000
    }
  ],
  "error": null
}
  • Event Types:
    • NoteUpdated - IOU note created or updated
    • ReserveCreated - New reserve created
    • ReserveToppedUp - Reserve collateral increased
    • ReserveRedeemed - Note redeemed from reserve
    • ReserveSpent - Reserve spent/closed
    • Commitment - Tracker state committed to blockchain
    • CollateralAlert - Collateral ratio alert (contains ratio field)
  • Example: 
    # Get recent events
curl http://localhost:3000/events

GET /events/paginated

  • Description: Get paginated tracker events with custom page size
  • Query Parameters:
    • page - Page number (default: 0)
    • page_size - Number of items per page (default: 20, max: 100)
  • Examples: 
    # Get page 2 with 10 items per page
curl http://localhost:3000/events/paginated?page=2&page_size=10

# Get page 5 with default page size
curl http://localhost:3000/events/paginated?page=5

GET /key-status/{pubkey}

  • Description: Get comprehensive status information for a specific public key
  • Path Parameter: pubkey - Hex-encoded public key (66 characters)
  • Response: 
    {
  "success": true,
  "data": {
    "total_debt": 1500000000,
    "collateral": 3000000000,
    "collateralization_ratio": 2.0,
    "note_count": 5,
    "last_updated": 1672531200,
    "issuer_pubkey": "010101010101010101010101010101010101010101010101010101010101010101"
  },
  "error": null
}
  • Example: 
    curl http://localhost:3000/key-status/010101010101010101010101010101010101010101010101010101010101010101

POST /redeem

  • Description: Initiate redemption of an IOU note from a reserve
  • Request Body: 
    {
  "issuer_pubkey": "010101010101010101010101010101010101010101010101010101010101010101",
  "recipient_pubkey": "020202020202020202020202020202020202020202020202020202020202020202",
  "amount": 500000000,
  "timestamp": 1234567890
}
  • Response: 
    {
  "success": true,
  "data": {
    "redemption_id": "redeem_0101010101010101_0202020202020202",
    "amount": 500000000,
    "timestamp": 1672531200,
    "proof_available": true,
    "transaction_pending": false
  },
  "error": null
}
  • Example: 
    curl -X POST http://localhost:3000/redeem \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_pubkey": "010101010101010101010101010101010101010101010101010101010101010101",
    "recipient_pubkey": "020202020202020202020202020202020202020202020202020202020202020202",
    "amount": 500000000,
    "timestamp": 1234567890
  }'

GET /proof

  • Description: Generate proof for a specific note against current tracker state
  • Query Parameters:
    • issuer_pubkey - Hex-encoded issuer public key (66 characters)
    • recipient_pubkey - Hex-encoded recipient public key (66 characters)
  • Response: 
    {
  "success": true,
  "data": {
    "issuer_pubkey": "010101010101010101010101010101010101010101010101010101010101010101",
    "recipient_pubkey": "020202020202020202020202020202020202020202020202020202020202020202",
    "proof_data": "proof_0101010101010101_0202020202020202",
    "tracker_state_digest": "mock_digest_1234567890abcdef",
    "block_height": 1500,
    "timestamp": 1672531200
  },
  "error": null
}
  • Example: 
    curl "http://localhost:3000/proof?issuer_pubkey=010101010101010101010101010101010101010101010101010101010101010101&recipient_pubkey=020202020202020202020202020202020202020202020202020202020202020202"

Environment Variables

  • RUST_LOG: Set logging level (default: basis_server=debug,tower_http=debug)

Example:

RUST_LOG=info cargo run -p basis_server

Testing the API

Once the server is running, you can test it using curl:

curl http://localhost:3000/

Expected response:

Hello, Basis Tracker API!

Stopping the Server

Press Ctrl+C in the terminal where the server is running to stop it gracefully.

Next Steps

This is currently a stub implementation. Future development will add:

  • RESTful endpoints for IOU note management
  • Authentication and authorization
  • Integration with the persistence layer
  • WebSocket support for real-time updates
  • OpenAPI/Swagger documentation

Development

To add new endpoints, modify the crates/basis_server/src/main.rs file and add new route handlers using Axum's routing system.