BUILD
WITH HIVE.

01 / QUICKSTART

From source to Colony.

Most developers publish two inscriptions: a Drone containing Starlark source, then a Colony containing the interface. The existing Hive master is reused.

1. 01WriteDefine main(params)
2. 02TestValidate inputs and output
3. 03InscribePublish the Drone as text
4. 04ComposeInsert both IDs into the Colony
5. 05LaunchInscribe the Colony as HTML

02 / SYSTEM MODEL

Know what runs where.

03 / DRONE DEVELOPMENT

One function. Strict output.

Every Drone must define main(params). Parameters arrive as JSON-compatible Starlark values; the returned value must also be JSON-compatible.

CURRENCIES = {"USD": "usd", "GBP": "gbp", "EUR": "eur"}

def main(params):
    currency = params.get("currency", "USD")
    if currency not in CURRENCIES:
        fail("Unsupported currency")

    quote = CURRENCIES[currency]
    response = http_request(
        "https://api.coingecko.com/api/v3/simple/price",
        query = {"ids": "bitcoin", "vs_currencies": quote},
    )
    if response["status"] != 200 or response["encoding"] != "utf-8":
        fail("Price API returned an unsuccessful response")

    data = json.decode(response["body"])
    return {
        "asset": "Bitcoin",
        "currency": currency,
        "price": data["bitcoin"][quote],
    }

Available capabilities

04 / TESTING

Prove the boundary before you inscribe.

Run the Drone in a Hive-compatible Starlark test environment. Test accepted values, rejected values, upstream failures, and the exact JSON shape your Colony expects.

{
  "params": {"currency": "USD"},
  "expect": {
    "asset": "Bitcoin",
    "currency": "USD",
    "price": "number"
  }
}

Keep fixtures independent of one indexer implementation. A conforming test runner should supply JSON-compatible parameters, enforce Hive limits, and expose the same result or structured-error envelope used by a Colony.

05 / EXTERNAL DATA

Call any public HTTPS API.

Drones can call public APIs on port 443. Query values, headers, and request bodies must be strings. Redirects are returned but never followed automatically.

def main(params):
    authorization = params.get("authorization")
    if authorization == None:
        fail("Missing API authorization")

    response = http_request(
        "https://api.example.com/v1/items",
        method = "POST",
        headers = {
            "Authorization": authorization,
            "Content-Type": "application/json",
        },
        body = json.encode({"limit": 10}),
    )
    if response["status"] < 200 or response["status"] >= 300:
        fail("API request failed")
    return json.decode(response["body"])

HTTP response object

{
  "status": 200,
  "headers": {"content-type": "application/json"},
  "encoding": "utf-8",
  "body": "{...}",
  "body_base64": ""
}

06 / DEPLOYMENT

Inscribe the logic, then the interface.

1. 01

   Prepare the Drone

   Save plain UTF-8 Starlark with a top-level main(params). Keep it below 64 KB.

   text/plain;charset=utf-8
2. 02

   Inscribe the Drone

   Use your preferred ordinal inscription tool and record the canonical <64 hex>i<index> inscription ID.

3. 03

   Build the Colony

   Insert the existing Hive ID and your new Drone ID into the supplied Colony template.

4. 04

   Test the built HTML

   Confirm ready, success, error, timeout, and narrow-screen states before spending an inscription fee.

5. 05

   Inscribe the Colony

   Publish the finalized single-file interface as HTML. The existing Hive does not need to be reinscribed.

   text/html;charset=utf-8

{
  "drone": {
    "contentType": "text/plain;charset=utf-8",
    "inscriptionId": "<YOUR_DRONE_INSCRIPTION_ID>"
  },
  "colony": {
    "contentType": "text/html;charset=utf-8",
    "hiveId": "1bbda8d0717d18ce2626b500d9ba7b428defc39a3df1bbb58e369181955bb52ci0",
    "droneId": "<YOUR_DRONE_INSCRIPTION_ID>"
  }
}

07 / COLONY INTEGRATION

Load Hive. Call the Drone. Render.

The Colony recursively loads Hive in a script-only sandbox. Hive announces readiness, accepts a versioned request, and returns a correlated result through postMessage.

<output id="result">Waiting for Hive…</output>

<iframe
  id="hive"
  title="Hive gateway"
  sandbox="allow-scripts"
  src="/content/1bbda8d0717d18ce2626b500d9ba7b428defc39a3df1bbb58e369181955bb52ci0">
</iframe>

<script>
const DRONE_ID = "<YOUR_DRONE_INSCRIPTION_ID>";
const hive = document.querySelector("#hive");
const pending = new Map();

function randomId() {
  return Array.from(crypto.getRandomValues(new Uint8Array(12)),
    byte => byte.toString(16).padStart(2, "0")).join("");
}

function callDrone(params) {
  const requestId = randomId();
  return new Promise((resolve, reject) => {
    const timeout = setTimeout(() => {
      pending.delete(requestId);
      reject(new Error("Drone call timed out"));
    }, 25000);
    pending.set(requestId, {resolve, reject, timeout});
    hive.contentWindow.postMessage({
      type: "ordinal-starlark-call", // legacy v1 wire identifier
      version: 1,
      requestId,
      inscriptionId: DRONE_ID,
      params,
    }, "*");
  });
}

addEventListener("message", async event => {
  if (event.source !== hive.contentWindow) return;
  const message = event.data;

  if (message?.type === "ordinal-starlark-contract-ready" &&
      message.version === 1) {
    const response = await callDrone({currency: "USD"});
    document.querySelector("#result").textContent = response.result.price;
    return;
  }

  if (message?.type !== "ordinal-starlark-result" ||
      message.version !== 1) return;
  const request = pending.get(message.requestId);
  if (!request) return;
  pending.delete(message.requestId);
  clearTimeout(request.timeout);
  if (message.ok) request.resolve(message);
  else request.reject(new Error(
    `${message.error?.code || "error"}: ${message.error?.message || "Drone failed"}`
  ));
});
</script>

Successful result envelope

{
  "type": "ordinal-starlark-result",
  "version": 1,
  "requestId": "...",
  "ok": true,
  "result": {"price": 63531},
  "sourceSha256": "...",
  "steps": 1413
}

08 / SAFETY CONTRACT

Design for the boundary.

Current production ceilings

09 / REFERENCE COLONIES

Start from working organisms.