/api/drd/user/post

GET

Creates or updates the caller's record in the Distributed Resource Directory (DRD) — the public, RAIDA-wide user directory keyed by coin (denomination + serial number). The record carries the owner's display name, optional profile description, two avatar symbols, the inbox fee senders must pay to deliver QMail to this address, and an optional class rejection (the minimum coin denomination a sender's address must have). Posting is how client software sets its own spam controls.

http://localhost:8080/api/drd/user/post?sn=9840&fee=0.5&first_name=Alice&last_name=Example

Parameters

Name Type Required Description
sn integer No Serial number of the coin that authenticates the request. The coin is loaded from the wallet's Bank or Fracked folder. Omit to use the QMail identity coin instead.
denomination integer No Optional safety check when sn is given: must match the denomination of the coin found for that serial number (-8 to 6).
wallet_path string No Wallet holding the auth coin. Defaults to the Default wallet. Only used together with sn.
fee string No Inbox fee in CC as a decimal string, e.g. 10992.934002. Up to 8 fractional digits, must be ≥ 0. Parsed exactly (no floating point). Default 0 = free inbox.
first_name string No First name, UTF-8, at most 63 bytes. Default empty.
last_name string No Last name, UTF-8, at most 63 bytes. Default empty.
description string No Profile description, transported as websafe base64 (base64url alphabet A-Za-z0-9-_, padding optional; standard +/ also accepted). The decoded payload is UTF-8, max 512 bytes. Omit or empty = no description. Undecodable input → 400; decoded length > 512 → 400 Description too long (max 512 bytes).
first_symbol integer No First avatar symbol code, 0-255. Default 0.
second_symbol integer No Second avatar symbol code, 0-255. Default 0.
class_rejection integer No Minimum denomination a sender's address coin must have, as a SIGNED denomination code (-8 to 6). 0 (default) accepts all denominations. Example: 1 requires 10 CC-class senders; -1 allows 0.1 CC and up. Senders below the minimum are rejected with Tell status 237.

Responses

Success Response (200)

At least one RAIDA server accepted the record.

The fan-out fields are shared by every DRD endpoint: pass_count (RAIDAs reporting success), fail_count (responded but did not succeed), no_response_count (attempted but no answer — timeout / network error), and skipped_count (not attempted: the availability echo marked the RAIDA offline, so the client skipped it — distinct from a network failure). Together these total 25. quorum is true when 13 or more RAIDA servers accepted, and raida_results holds one entry per server (25 entries; truncated in the examples below). Status 250 is success; failed entries include an error string.

{
    "command": "drd-user-post",
    "success": true,
    "denomination": 1,
    "serial_number": 9840,
    "fee": "0.5",
    "pass_count": 24,
    "fail_count": 0,
    "no_response_count": 0,
    "skipped_count": 1,
    "quorum": true,
    "raida_results": [
        { "raida": 0, "success": true, "status": 250 },
        { "raida": 1, "success": true, "status": 250 }
    ]
}

Error Responses

400 Bad Request

Invalid fee (negative, malformed, or more than 8 fractional digits), invalid class_rejection, a name longer than 63 bytes, invalid description (not websafe base64, or decoded length > 512), or an invalid sn.

{
    "error": true,
    "message": "Invalid fee (decimal CC amount, >= 0, max 8 fractional digits)",
    "code": 400
}
{
    "error": true,
    "message": "Description too long (max 512 bytes)",
    "code": 400
}

404 Not Found

The auth coin was not found in the wallet.

{
    "error": true,
    "message": "Auth coin not found in wallet (Bank/Fracked)",
    "code": 404
}

502 Bad Gateway

No RAIDA server accepted the request. The body names the dominant failure status and includes the full per-server detail.

{
    "error": true,
    "message": "No RAIDA accepted the post",
    "code": 502,
    "raida_status_code": 200,
    "detail": "Invalid AN",
    "pass_count": 0,
    "fail_count": 25,
    "no_response_count": 0,
    "skipped_count": 0,
    "quorum": false,
    "raida_results": [
        { "raida": 0, "success": false, "status": 200, "error": "Invalid AN" }
    ]
}

Examples

cURL Example

curl -X GET "http://localhost:8080/api/drd/user/post?sn=9840&fee=0.5&first_name=Alice&last_name=Example&description=Q2xvdWRDb2luIGRldmVsb3Blcg"

JavaScript Example

// description is websafe base64 of the UTF-8 profile text
const description = btoa('CloudCoin developer').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
const params = new URLSearchParams({
    sn: 9840,
    fee: '0.5',
    first_name: 'Alice',
    last_name: 'Example',
    description,
    class_rejection: 0
});

fetch(`http://localhost:8080/api/drd/user/post?${params}`)
    .then(r => r.json())
    .then(data => {
        if (data.success) {
            console.log(`Posted to ${data.pass_count}/25 RAIDA (quorum: ${data.quorum})`);
        } else {
            console.error('Error:', data.message, data.detail ?? '');
        }
    });

Python Example

import requests

url = 'http://localhost:8080/api/drd/user/post'
params = {
    'sn': 9840, 'fee': '0.5',
    'first_name': 'Alice', 'last_name': 'Example',
    'description': 'Q2xvdWRDb2luIGRldmVsb3Blcg'  # websafe base64 of UTF-8 text
}

data = requests.get(url, params=params).json()
if data.get('success'):
    print(f"Posted to {data['pass_count']}/25 RAIDA, quorum={data['quorum']}")
else:
    print(f"Error: {data.get('message')} ({data.get('detail')})")

Notes

  • Requests fan out to all 25 RAIDA servers in parallel; the client owns consistency. On partial success (pass_count < 25), re-issue the same request to bring stragglers up to date.
  • This operation is AN-authenticated: the auth coin's per-RAIDA Authenticity Numbers are sent with the request, and each server verifies them against its coin database (status 200 = wrong AN, 40 = unknown coin).
  • Without an sn parameter the QMail identity coin from the Mail wallet is used, so QMail users manage their directory entry with their mail identity.
  • Posting again updates the record. created_at is set on the first post and preserved by updates — it is the directory's anti-scam signal (old accounts are harder to fake). Only delete + repost resets it.
  • Fees are exact decimals stored as 10-8 CC integer units on the wire; never send floats.
  • description is encoded as websafe base64 on the REST boundary; the core decodes to raw UTF-8 before the RAIDA post. Max decoded size is 512 bytes.
  • Whitelisted senders (see /api/drd/list/set) bypass both the inbox fee and class rejection.