@runonflux/flux-cloud-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InFlux Technologies Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# Flux Cloud MCP server
+
+An [MCP](https://modelcontextprotocol.io) server that lets any AI agent use
+[Flux Cloud](https://runonflux.com), the decentralized cloud: quote an app in
+US dollars, deploy it, pay for it, watch it come up, read its logs, update it,
+and cancel it. Works with Claude Code, Claude Desktop, Cursor, Windsurf,
+OpenCode and every other MCP host.
+
+There is no account. Two keys are the whole identity:
+
+| Key                        | Address               | Role                                                                 |
+| -------------------------- | --------------------- | -------------------------------------------------------------------- |
+| `FLUX_ID_PRIVATE_KEY`      | Flux ID, `1...`       | Owns apps. Signs specifications and API sessions. Never holds funds. |
+| `FLUX_PAYMENT_PRIVATE_KEY` | Flux address, `t1...` | Holds FLUX and pays deployment fees on-chain.                        |
+
+The server generates a pair for you (`flux_generate_keys`); fund the payment
+address with FLUX and deploy.
+
+## Pricing policy
+
+Every price this server shows is the **Flux Cloud USD price**, the same one
+[home.runonflux.io](https://home.runonflux.io) charges, converted to FLUX at the
+live market rate with the 5 percent pay-in-FLUX discount. Quotes come from the
+network itself (`/apps/calculatefiatandfluxprice`), so they include the $0.99
+minimum, hardware and term discounts, and update credits.
+
+The blockchain's own acceptance threshold is several times lower. It is never
+shown as a price; it is only checked as a guard before a payment is broadcast.
+
+## Install
+
+```bash
+npm install -g @runonflux/flux-cloud-mcp     # or: yarn global add @runonflux/flux-cloud-mcp
+```
+
+Or run it without installing: `npx @runonflux/flux-cloud-mcp`.
+
+### Claude Code
+
+```bash
+claude mcp add flux-cloud -s user \
+  -e FLUX_ID_PRIVATE_KEY=<wif> -e FLUX_PAYMENT_PRIVATE_KEY=<wif> \
+  -- npx -y @runonflux/flux-cloud-mcp
+```
+
+### Claude Desktop, Cursor, Windsurf (JSON config)
+
+```json
+{
+  "mcpServers": {
+    "flux-cloud": {
+      "command": "npx",
+      "args": ["-y", "@runonflux/flux-cloud-mcp"],
+      "env": {
+        "FLUX_ID_PRIVATE_KEY": "<wif of the Flux ID>",
+        "FLUX_PAYMENT_PRIVATE_KEY": "<wif of the payment address>"
+      }
+    }
+  }
+}
+```
+
+Keys are optional. Without them every read-only tool works, and
+`flux_generate_keys` will create a pair to put into the config.
+
+### OpenCode
+
+```json
+{
+  "mcp": {
+    "flux-cloud": {
+      "type": "local",
+      "command": ["npx", "-y", "@runonflux/flux-cloud-mcp"],
+      "environment": {
+        "FLUX_ID_PRIVATE_KEY": "<wif>",
+        "FLUX_PAYMENT_PRIVATE_KEY": "<wif>"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool                    | What it does                                                             | Spends FLUX    |
+| ----------------------- | ------------------------------------------------------------------------ | -------------- |
+| `flux_get_identity`     | Flux ID, payment address, balance in FLUX and USD                        | no             |
+| `flux_generate_keys`    | New Flux ID + payment key pair with setup instructions                   | no             |
+| `flux_get_pricing`      | USD rate card, FLUX/USD rate, discounts, reference sizes                 | no             |
+| `flux_build_spec`       | Simple description (image, ports, cpu/ram/hdd, months) to a full v8 spec | no             |
+| `flux_validate_spec`    | Local rules plus verification on a FluxOS node                           | no             |
+| `flux_quote_app`        | USD price and FLUX to pay, for a registration or an update               | no             |
+| `flux_deploy_app`       | Plan (default) or, with `confirm=true`, sign, broadcast and pay          | with `confirm` |
+| `flux_wait_for_app`     | Poll until accepted and instances run; returns URLs                      | no             |
+| `flux_get_app`          | Any app's spec, expiry, instances, URLs                                  | no             |
+| `flux_list_my_apps`     | Apps owned by the Flux ID, with instance counts and days left            | no             |
+| `flux_get_app_logs`     | Container logs from a running instance (owner only)                      | no             |
+| `flux_get_app_stats`    | Live CPU/memory/network of an instance (owner only)                      | no             |
+| `flux_control_app`      | Restart, redeploy or remove instances, per node or globally              | no             |
+| `flux_cancel_app`       | End an app early by shortening its term                                  | with `confirm` |
+| `flux_get_network_info` | Node counts, height, FLUX/USD, deployment address                        | no             |
+
+Resources `flux://guide/overview`, `flux://guide/spec-format`,
+`flux://guide/pricing` and `flux://guide/gotchas` give the agent the domain
+knowledge; the `deploy_on_flux` prompt walks it through a deployment.
+
+## A typical session
+
+```
+> deploy nginx on flux, 3 instances, one month
+
+flux_get_identity      -> Flux ID 1Ab..., payer t1Cd..., 996.98 FLUX ($48.74)
+flux_build_spec        -> v8 spec, port 39978 -> 80, r:/data, valid
+flux_quote_app         -> $0.99 for 1 month, pay 19.24 FLUX (5% FLUX discount)
+   user agrees
+flux_deploy_app confirm=true
+                       -> message hash 8d2f..., paid 19.24 FLUX, txid 0c41...
+flux_wait_for_app      -> accepted at height 2941560, 3/3 instances running
+                          https://myapp.app.runonflux.io
+```
+
+## How a deployment works
+
+1. The spec is verified by a FluxOS node exactly as it will be at
+   registration (image reachable, architecture, ports, name free).
+2. The network quotes the USD price; the server checks the payer's balance.
+3. With `confirm=true` the Flux ID signs the spec, one node broadcasts it to
+   the network and returns a 64-character message hash.
+4. The payment address sends the quoted FLUX to the network deployment
+   address with the hash in an OP_RETURN output. Right before signing, the
+   amount is re-checked against a freshly fetched price table, because an
+   underpaid message is dropped silently and the FLUX is not refunded.
+5. Nodes pair the confirmed payment with the message and publish the app.
+   Instances then spawn and pull the image.
+
+Updates use the same tool: an existing app of the same owner gets a
+`fluxappupdate` message and the network credits the unused part of the old
+term. Private (enterprise) apps are supported through the `enterprise`
+argument: components are encrypted for the network and only ArcaneOS nodes
+can run them.
+
+## Configuration
+
+| Variable                   | Default                                            | Purpose                                       |
+| -------------------------- | -------------------------------------------------- | --------------------------------------------- |
+| `FLUX_ID_PRIVATE_KEY`      |                                                    | WIF of the Flux ID (owner)                    |
+| `FLUX_PAYMENT_PRIVATE_KEY` |                                                    | WIF of the paying address                     |
+| `FLUX_API_URL`             | `https://api.runonflux.io`                         | Load-balanced FluxOS API for reads and quotes |
+| `FLUX_NODE_URL`            | auto                                               | Pin one FluxOS node for registrations         |
+| `FLUX_EXPLORER_URLS`       | `explorer.runonflux.io,flux-explorer.sspwallet.io` | Insight explorers for UTXOs and broadcast     |
+| `FLUX_STATS_URL`           | `https://stats.runonflux.io`                       | USD rate card                                 |
+| `FLUX_RATES_URL`           | `https://viprates.runonflux.io`                    | FLUX market rate                              |
+
+## Security notes
+
+- Private keys stay in the server process. No tool ever returns a configured
+  key; `flux_generate_keys` returns only the keys it just created.
+- Nothing is spent unless a tool is called with `confirm=true`. Hosts that
+  ask before tool calls will show the USD amount in the arguments' context.
+- FluxOS sessions are self-issued signed phrases valid for a few hours; no
+  password or token is stored anywhere.
+- Use a dedicated payment address holding only what you intend to spend.
+
+## Development
+
+```bash
+yarn install
+yarn type-check && yarn lint && yarn format:check && yarn build && yarn test
+yarn test:live      # differential test of the USD estimator against the network
+```
+
+The USD estimator, the specification formatter and the consensus guard mirror
+the FluxOS code (`appSpecHelpers.js`, `appUtilities.js`, `messageVerifier.js`)
+and the live test checks the estimator against the network on every run.
+
+## License
+
+MIT

package/dist/chain.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Flux blockchain access over the public Insight explorer API, plus
+ * construction of the deployment payment.
+ *
+ * A registration payment is an ordinary transparent transaction with two
+ * outputs that matter: `amount` FLUX to the network deployment address, and an
+ * OP_RETURN carrying the 64-character message hash. Nodes index exactly that
+ * pair; nothing else about the payer is consulted, which is why the payment
+ * key and the owner Flux ID are independent.
+ */
+export declare const DUST_LIMIT = 546;
+export declare const SATOSHIS = 100000000;
+export interface Utxo {
+    txid: string;
+    vout: number;
+    satoshis: number;
+    confirmations: number;
+    coinbase: boolean;
+}
+export interface Balance {
+    total: number;
+    spendable: number;
+    utxos: Utxo[];
+    spendableUtxos: Utxo[];
+}
+export declare function toFlux(satoshis: number): number;
+export declare class Explorer {
+    private readonly urls;
+    private readonly timeoutMs;
+    constructor(urls: string[], timeoutMs?: number);
+    private request;
+    height(): Promise<number>;
+    utxos(address: string): Promise<Utxo[]>;
+    balance(address: string): Promise<Balance>;
+    broadcast(rawtx: string): Promise<string>;
+    transaction(txid: string): Promise<{
+        confirmations?: number;
+        blockheight?: number;
+    }>;
+}
+/** Coinbase outputs are unspendable until mature; unconfirmed inputs are avoided. */
+export declare function selectSpendable(utxos: Utxo[]): Utxo[];
+/** 148 bytes per p2pkh input, 34 per standard output, 10 overhead, plus the OP_RETURN. */
+export declare function estimateSize(inputCount: number, outputCount: number, opReturnBytes: number): number;
+export interface InputSelection {
+    inputs: Utxo[];
+    total: number;
+    fee: number;
+    change: number;
+}
+/** Greedily pick the fewest inputs covering amount + fee, recomputing the fee as inputs are added. */
+export declare function selectInputs(utxos: Utxo[], amountSat: number, opReturnBytes: number): InputSelection;
+export interface PaymentParams {
+    wif: string;
+    to: string;
+    amountSat: number;
+    message: string;
+    utxos: Utxo[];
+    height: number;
+    maxFeeSat?: number;
+}
+export interface SignedPayment {
+    hex: string;
+    txid: string;
+    fee: number;
+    change: number;
+    inputs: number;
+    sizeBytes: number;
+}
+/** Build and sign the deployment payment. */
+export declare function buildPayment({ wif, to, amountSat, message, utxos, height, maxFeeSat, }: PaymentParams): SignedPayment;

package/dist/chain.js

@@ -0,0 +1,144 @@
+/**
+ * Flux blockchain access over the public Insight explorer API, plus
+ * construction of the deployment payment.
+ *
+ * A registration payment is an ordinary transparent transaction with two
+ * outputs that matter: `amount` FLUX to the network deployment address, and an
+ * OP_RETURN carrying the 64-character message hash. Nodes index exactly that
+ * pair; nothing else about the payer is consulted, which is why the payment
+ * key and the owner Flux ID are independent.
+ */
+import utxolib from '@runonflux/utxo-lib';
+const NETWORK = utxolib.networks.flux;
+const TX_VERSION = 4; // sapling
+const TX_VERSION_GROUP_ID = 0x892f2085;
+const TX_EXPIRY_DELTA = 30; // blocks
+export const DUST_LIMIT = 546;
+const FEE_PER_BYTE = 1;
+const COINBASE_MATURITY = 100;
+export const SATOSHIS = 1e8;
+export function toFlux(satoshis) {
+    return Number((satoshis / SATOSHIS).toFixed(8));
+}
+export class Explorer {
+    urls;
+    timeoutMs;
+    constructor(urls, timeoutMs = 30000) {
+        this.urls = urls;
+        this.timeoutMs = timeoutMs;
+    }
+    async request(method, pathname, body) {
+        let lastError;
+        for (const base of this.urls) {
+            try {
+                const response = await fetch(`${base}${pathname}`, {
+                    method,
+                    headers: body === undefined ? {} : { 'Content-Type': 'application/json' },
+                    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+                const text = await response.text();
+                if (!response.ok)
+                    throw new Error(`HTTP ${response.status} ${text.slice(0, 200)}`);
+                return JSON.parse(text);
+            }
+            catch (error) {
+                lastError = new Error(`${base}${pathname}: ${error.message}`);
+            }
+        }
+        throw lastError ?? new Error('No explorer configured');
+    }
+    async height() {
+        const status = (await this.request('GET', '/api/sync'));
+        const height = Number(status.blockChainHeight ?? status.height);
+        if (!Number.isFinite(height))
+            throw new Error('Explorer returned no block height');
+        return height;
+    }
+    async utxos(address) {
+        const list = (await this.request('GET', `/api/addr/${address}/utxo`));
+        return (Array.isArray(list) ? list : []).map((u) => ({
+            txid: String(u.txid),
+            vout: Number(u.vout),
+            satoshis: Number(u.satoshis),
+            confirmations: Number(u.confirmations ?? 0),
+            coinbase: Boolean(u.coinbase),
+        }));
+    }
+    async balance(address) {
+        const utxos = await this.utxos(address);
+        const spendable = selectSpendable(utxos);
+        const sum = (list) => list.reduce((acc, u) => acc + u.satoshis, 0);
+        return { total: sum(utxos), spendable: sum(spendable), utxos, spendableUtxos: spendable };
+    }
+    async broadcast(rawtx) {
+        const result = (await this.request('POST', '/api/tx/send', { rawtx }));
+        const txid = typeof result?.txid === 'object' ? result.txid?.result : (result?.txid ?? result?.result);
+        if (!txid)
+            throw new Error(`Broadcast returned no txid: ${JSON.stringify(result)}`);
+        return String(txid);
+    }
+    async transaction(txid) {
+        return (await this.request('GET', `/api/tx/${txid}`));
+    }
+}
+/** Coinbase outputs are unspendable until mature; unconfirmed inputs are avoided. */
+export function selectSpendable(utxos) {
+    return utxos.filter((u) => {
+        if (u.coinbase && u.confirmations < COINBASE_MATURITY)
+            return false;
+        return u.confirmations >= 1;
+    });
+}
+/** 148 bytes per p2pkh input, 34 per standard output, 10 overhead, plus the OP_RETURN. */
+export function estimateSize(inputCount, outputCount, opReturnBytes) {
+    const opReturn = opReturnBytes ? 9 + opReturnBytes + 2 : 0;
+    return inputCount * 148 + outputCount * 34 + 10 + opReturn;
+}
+/** Greedily pick the fewest inputs covering amount + fee, recomputing the fee as inputs are added. */
+export function selectInputs(utxos, amountSat, opReturnBytes) {
+    const sorted = [...utxos].sort((a, b) => b.satoshis - a.satoshis);
+    const chosen = [];
+    let total = 0;
+    for (const utxo of sorted) {
+        chosen.push(utxo);
+        total += utxo.satoshis;
+        const withChange = estimateSize(chosen.length, 2, opReturnBytes) * FEE_PER_BYTE;
+        const withoutChange = estimateSize(chosen.length, 1, opReturnBytes) * FEE_PER_BYTE;
+        if (total >= amountSat + withChange) {
+            return { inputs: chosen, total, fee: withChange, change: total - amountSat - withChange };
+        }
+        if (total >= amountSat + withoutChange && total - amountSat - withoutChange < DUST_LIMIT) {
+            return { inputs: chosen, total, fee: total - amountSat, change: 0 };
+        }
+    }
+    const needed = amountSat + estimateSize(Math.max(chosen.length, 1), 2, opReturnBytes) * FEE_PER_BYTE;
+    throw new Error(`Insufficient funds: have ${toFlux(total)} FLUX spendable, need about ${toFlux(needed)} FLUX`);
+}
+/** Build and sign the deployment payment. */
+export function buildPayment({ wif, to, amountSat, message, utxos, height, maxFeeSat = 1000000, }) {
+    const keyPair = utxolib.ECPair.fromWIF(wif, NETWORK);
+    const changeAddress = keyPair.getAddress();
+    const opReturnBytes = Buffer.byteLength(message, 'utf8');
+    if (opReturnBytes > 80)
+        throw new Error('OP_RETURN payload exceeds 80 bytes');
+    const { inputs, fee, change } = selectInputs(utxos, amountSat, opReturnBytes);
+    if (fee > maxFeeSat)
+        throw new Error(`Refusing to sign: fee ${fee} sat exceeds cap ${maxFeeSat} sat`);
+    const builder = new utxolib.TransactionBuilder(NETWORK, fee);
+    builder.setVersion(TX_VERSION);
+    builder.setVersionGroupId(TX_VERSION_GROUP_ID);
+    builder.setExpiryHeight(height + TX_EXPIRY_DELTA);
+    inputs.forEach((utxo) => builder.addInput(utxo.txid, utxo.vout));
+    builder.addOutput(to, amountSat);
+    if (change >= DUST_LIMIT)
+        builder.addOutput(changeAddress, change);
+    builder.addOutput(utxolib.script.nullData.output.encode(Buffer.from(message, 'utf8')), 0);
+    inputs.forEach((utxo, index) => {
+        builder.sign(index, keyPair, undefined, utxolib.Transaction.SIGHASH_ALL, utxo.satoshis);
+    });
+    const tx = builder.build();
+    const hex = tx.toHex();
+    return { hex, txid: tx.getId(), fee, change, inputs: inputs.length, sizeBytes: hex.length / 2 };
+}
+//# sourceMappingURL=chain.js.map

package/dist/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../src/chain.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime configuration, read from the environment the MCP host passes in.
+ *
+ * Two independent keys are used, exactly as the Flux network models them:
+ *
+ *   FLUX_ID_PRIVATE_KEY       WIF of the Flux ID (ZelID). It is the app owner:
+ *                             it signs registration messages and API sessions.
+ *                             It never holds funds.
+ *   FLUX_PAYMENT_PRIVATE_KEY  WIF of a Flux transparent address (t1...). It
+ *                             holds FLUX and pays deployment fees on-chain.
+ *
+ * Both are optional: without them every read-only tool still works, and the
+ * server can generate a fresh pair for the user.
+ */
+export interface Config {
+    ownerWif: string | undefined;
+    payerWif: string | undefined;
+    /** Load-balanced FluxOS API, fine for reads and price quotes. */
+    apiUrl: string;
+    /** A specific FluxOS node to use for sessions and registrations, if pinned. */
+    nodeUrl: string | undefined;
+    explorerUrls: string[];
+    statsUrl: string;
+    ratesUrl: string;
+    /** Deployment address override, only for testing. */
+    requestTimeoutMs: number;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,36 @@
+/**
+ * Runtime configuration, read from the environment the MCP host passes in.
+ *
+ * Two independent keys are used, exactly as the Flux network models them:
+ *
+ *   FLUX_ID_PRIVATE_KEY       WIF of the Flux ID (ZelID). It is the app owner:
+ *                             it signs registration messages and API sessions.
+ *                             It never holds funds.
+ *   FLUX_PAYMENT_PRIVATE_KEY  WIF of a Flux transparent address (t1...). It
+ *                             holds FLUX and pays deployment fees on-chain.
+ *
+ * Both are optional: without them every read-only tool still works, and the
+ * server can generate a fresh pair for the user.
+ */
+const DEFAULT_EXPLORERS = ['https://explorer.runonflux.io', 'https://flux-explorer.sspwallet.io'];
+function optional(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function loadConfig(env = process.env) {
+    const explorers = optional(env.FLUX_EXPLORER_URLS)
+        ?.split(',')
+        .map((url) => url.trim().replace(/\/$/, ''))
+        .filter(Boolean);
+    return {
+        ownerWif: optional(env.FLUX_ID_PRIVATE_KEY),
+        payerWif: optional(env.FLUX_PAYMENT_PRIVATE_KEY),
+        apiUrl: (optional(env.FLUX_API_URL) ?? 'https://api.runonflux.io').replace(/\/$/, ''),
+        nodeUrl: optional(env.FLUX_NODE_URL)?.replace(/\/$/, ''),
+        explorerUrls: explorers && explorers.length ? explorers : DEFAULT_EXPLORERS,
+        statsUrl: (optional(env.FLUX_STATS_URL) ?? 'https://stats.runonflux.io').replace(/\/$/, ''),
+        ratesUrl: (optional(env.FLUX_RATES_URL) ?? 'https://viprates.runonflux.io').replace(/\/$/, ''),
+        requestTimeoutMs: Number(optional(env.FLUX_REQUEST_TIMEOUT_MS) ?? 60000),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgBH,MAAM,iBAAiB,GAAG,CAAC,+BAA+B,EAAE,oCAAoC,CAAC,CAAC;AAElG,SAAS,QAAQ,CAAC,KAAyB;IACzC,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IAC9B,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC;QAChD,EAAE,KAAK,CAAC,GAAG,CAAC;SACX,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;SAC3C,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,mBAAmB,CAAC;QAC3C,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,wBAAwB,CAAC;QAChD,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,0BAA0B,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QACrF,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QACxD,YAAY,EAAE,SAAS,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB;QAC3E,QAAQ,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,4BAA4B,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QAC3F,QAAQ,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,+BAA+B,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QAC9F,gBAAgB,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,uBAAuB,CAAC,IAAI,KAAK,CAAC;KACzE,CAAC;AACJ,CAAC"}

package/dist/deploy.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Deploying an app is two halves that must agree:
+ *
+ *   1. A signed specification message, handed to one FluxOS node and gossiped
+ *      to the network. The node answers with a 64-character hash and keeps the
+ *      message in a temporary store for one hour.
+ *   2. An on-chain payment to the network deployment address carrying that
+ *      hash in an OP_RETURN. When nodes index the transaction they pair it with
+ *      the stored message, check the amount, and publish the app globally.
+ *
+ * If the payment never lands the message just expires and nothing is spent.
+ * The amount paid is the Flux Cloud USD quote converted to FLUX. Consensus
+ * would accept far less, but that minimum is checked here only as a guard:
+ * underpaying it burns the FLUX with no refund, since the message is dropped
+ * silently and the same hash cannot be paid twice.
+ */
+import type { Config } from './config.js';
+import { Explorer } from './chain.js';
+import { FluxClient } from './fluxapi.js';
+import { type Identity } from './keys.js';
+import { type DeploymentInformation, type Quote } from './pricing.js';
+import { type AppComponent, type AppSpec, type PublishedAppSpec, type SpecInput } from './spec.js';
+export interface Wallet {
+    owner: Identity;
+    payer: Identity;
+}
+export declare function walletFromConfig(config: Config): Wallet;
+export declare function api(config: Config): FluxClient;
+export declare function explorer(config: Config): Explorer;
+export declare function publishedSpec(client: FluxClient, name: string): Promise<PublishedAppSpec | null>;
+export interface Location {
+    ip: string;
+    name: string;
+    broadcastedAt?: string;
+    expireAt?: string;
+    hash?: string;
+    runningSince?: string;
+    osUptime?: number;
+    staticIp?: boolean;
+}
+export declare function appLocations(client: FluxClient, name: string): Promise<Location[]>;
+/**
+ * Pick a node that can take the registration: enough peers, ArcaneOS when
+ * the spec is enterprise, and honouring a pinned FLUX_NODE_URL.
+ */
+export declare function selectNode(config: Config, { arcane, log }?: {
+    arcane?: boolean;
+    log?: (m: string) => void;
+}): Promise<FluxClient>;
+export interface EnterpriseInput {
+    compose: AppComponent[];
+    contacts: string[];
+}
+export interface Plan {
+    action: 'register' | 'update';
+    spec: AppSpec;
+    /** The node's own formatting of the spec: this is what gets signed. */
+    formatted: AppSpec;
+    previous: PublishedAppSpec | null;
+    quote: Quote;
+    consensusMinimumFlux: number;
+    deployment: DeploymentInformation;
+    height: number;
+    payer: string;
+    balanceFlux: number;
+    requiredFlux: number;
+    funded: boolean;
+    warnings: string[];
+    node: FluxClient;
+}
+/**
+ * Everything needed to decide whether a deployment can proceed, without
+ * signing, spending or broadcasting anything.
+ */
+export declare function plan(config: Config, input: SpecInput & {
+    name: string;
+}, options?: {
+    enterprise?: EnterpriseInput | undefined;
+    log?: (m: string) => void;
+}): Promise<Plan>;
+export interface DeployResult {
+    action: 'register' | 'update';
+    name: string;
+    messageHash: string;
+    messageExpiresAt: string;
+    txid: string;
+    paidFlux: number;
+    paidUsd: number;
+    feeFlux: number;
+    deploymentAddress: string;
+}
+/** Sign, broadcast the message, then pay for it. Spends FLUX. */
+export declare function execute(config: Config, prepared: Plan, log?: (m: string) => void): Promise<DeployResult>;
+export interface WaitResult {
+    accepted: PublishedAppSpec | null;
+    paymentConfirmations: number;
+    instances: Location[];
+    wantedInstances: number;
+    done: boolean;
+    timedOut: boolean;
+}
+/**
+ * Poll until the message is accepted and instances run, within `timeoutMs`.
+ * Returns partial progress on timeout so a caller can simply call again.
+ */
+export declare function waitForApp(config: Config, name: string, options?: {
+    txid?: string | undefined;
+    previousHash?: string | undefined;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<WaitResult>;