RPC-API-Referenz

Die HTTP-Schnittstelle, die ein Knoten Wallets bereitstellt: vier Endpunkte, JSON für Status und Fehler, eine kompakte binäre Kodierung für Blöcke und Zahlungen.

Die Basis-URL des öffentlichen Testknotens ist https://node.tint.top. Die Schnittstelle sieht nie einen Schlüssel oder einen Betrag: Eine Wallet sendet fertige Zahlungen und liest ganze Blöcke, die sie selbst entschlüsselt.

Endpunkte

Methode und Pfad	Antwortet mit
`GET /v1/status`	Wo die Chain steht, als JSON.
`GET /v1/blocks/{height}`	Ein endgültiger Block, in der Wire-Kodierung.
`GET /v1/blocks?from=N`	Die Blöcke mit Zahlungen ab Höhe N, als Block-Batch.
`POST /v1/transactions`	Nimmt eine Zahlung in der Wire-Kodierung entgegen; antwortet mit ihrer Kennung als JSON.

GET /v1/status

Anfrage

curl -s https://node.tint.top/v1/status

Antwort (Beispielwerte)

{
  "chain_id": 6073471695170043905,
  "height": 128431,
  "tip": "9f3c…e21a",
  "genesis": "04b7…c9d0",
  "queued": 0,
  "pools": [
    { "asset": 1, "native": 20000000000000, "other": 10000000000000, "fee_bps": 30 }
  ]
}

Feld	Bedeutung
`chain_id`	Kennung des Netzwerks, in jede Signatur und jeden Block-Hash eingebunden.
`height`	Höhe des neuesten endgültigen Blocks.
`tip`	Hash des neuesten endgültigen Blocks, als Hex.
`genesis`	Hash des ersten Blocks, als Hex. Zwei Testnetze können sich eine `chain_id` teilen; hiermit lassen sie sich unterscheiden.
`queued`	Zahlungen, die auf einen Block warten.
`pools[].asset`	Der Coin, den der Pool gegen den nativen handelt (1 ist `TUSD`).
`pools[].native`, `pools[].other`	Was der Pool hält, in Einheiten (1 Coin = 100,000,000 Einheiten), Stand des neuesten endgültigen Blocks.
`pools[].fee_bps`	Die Gebühr des Pools in Zehntausendsteln; 30 sind 0,3 %.

GET /v1/blocks/{height}

Gibt einen endgültigen Block als application/octet-stream zurück. Ein endgültiger Block ändert sich nie, daher trägt die Antwort Cache-Control: public, max-age=31536000, immutable. Eine nicht numerische Höhe ergibt invalid_height, eine unbekannte not_found.

GET /v1/blocks?from=N

Gibt die Blöcke, die Zahlungen enthalten, ab Höhe N als einen Block-Batch zurück (application/octet-stream), zusammen mit der letzten Höhe, die die Antwort abdeckt (through). Eine Wallet, die aufholt, fragt erneut ab der Höhe nach through. Die Antwort wächst mit der Chain und wird daher mit Cache-Control: no-store gesendet. from muss eine ganze Zahl sein.

POST /v1/transactions

Senden Sie eine fertige Zahlung in der Wire-Kodierung als Anfragetext. Die Wallet erstellt sie; das Format ist im Modul wire.rs von tint-core definiert: Felder fester Breite, eine gültige Kodierung pro Wert, keine nachfolgenden Bytes.

Anfrage

curl -s -X POST https://node.tint.top/v1/transactions \
  -H 'content-type: application/octet-stream' \
  --data-binary @payment.bin

Antwort

{ "txid": "5be1…07af" }

Eine Transaktion beginnt mit dem Asset (u32), einer Ablaufhöhe (u64) und einer Art (0 für eine Zahlung, 1 für einen Tausch), gefolgt von einem Bundle: Flags, einer Wertbilanz, einem Anker, der Anzahl der Aktionen und den Aktionen mit ihrem Beweis. Ein Tausch fügt den gekauften Coin, den eingezahlten Betrag und ein zweites Bundle hinzu.

Fehler

Fehler sind JSON: {"error":{"code":"...","message":"..."}}.

HTTP	code	Bedeutung
400	`malformed`	Der Inhalt ist keine Zahlung.
400	`invalid_height`	Die Höhe oder `from` ist keine ganze Zahl.
404	`not_found`	Kein endgültiger Block bei dieser Höhe oder keine solche Ressource.
409	`double_spend`	Eine Note dieser Zahlung ist bereits ausgegeben.
409	`conflict`	Eine andere wartende Zahlung gibt eine derselben Noten aus.
409	`price_moved`	Der Pool liefert nicht mehr, was dieser Tausch verlangt.
413	`too_large`	Die Zahlung ist größer, als die Chain erlaubt.
422	`rejected`	Die Zahlung verletzt eine Regel der Chain; die Meldung nennt welche.
429	`rate_limited`	Diese Client-Adresse hat ihr Anfragebudget aufgebraucht. Wiederholen Sie nach dem Header `Retry-After`.
500	`internal`	Der Knoten konnte nicht prüfen oder kodieren.
503	`busy`, `queue_full`	Der Knoten prüft andere Zahlungen, oder seine Warteschlange ist voll. Versuchen Sie es erneut; `Retry-After: 1`.

Ratenbegrenzung

Standardmäßig darf jede Client-Adresse dauerhaft 50 Anfragen pro Sekunde stellen, mit einem Burst von 100, und höchstens 4 Zahlungen werden über alle Clients hinweg gleichzeitig geprüft. Betreiber können beides ändern. Hinter einem Reverse-Proxy zählt der Knoten Clients nach der letzten Adresse, die der Proxy in X-Forwarded-For geschrieben hat; frühere Einträge glaubt er nicht.

Beispiel: der Chain folgen

python (serverseitig)

import json, time, urllib.request

BASE = "https://node.tint.top"

while True:
    with urllib.request.urlopen(f"{BASE}/v1/status", timeout=10) as r:
        status = json.load(r)
    print(status["height"], status["queued"])
    time.sleep(5)

Was ein Knotenbetreiber über diese Schnittstelle noch erfahren kann, ist die Netzwerkadresse, von der eine Zahlung kam. Beträge, Sender und Empfänger stecken im Beweis und in den verschlüsselten Noten.