Node Lifecycle

The state machine for a Rails Yield node — every state, the action that advances it, and how to query progress via the API.

A Rails Yield node moves through a deterministic sequence of states from creation to active yield generation. Knowing the state machine is essential for any integration that watches a node, drives onboarding, or handles deactivation.

State diagram

State reference

State	What it means	How to advance
`CREATED`	A node row exists. For Fully Managed setups, infrastructure provisioning is queued.	Automatic. For Third Party Hosted, call `node.connect` with LND or Litd credentials.
`WAITING_FOR_CREDENTIALS`	The node is reachable but Rails has not yet stored the macaroons it needs to operate.	Automatic for Fully Managed. For Third Party Hosted, complete the `node.connect` mutation.
`WAITING_FOR_DEPOSIT`	Credentials are stored. The node is ready to receive on-chain Bitcoin.	Send Bitcoin to the node's on-chain address. The state advances once a deposit confirms.
`WAITING_FOR_ACTIVATION`	Funds have arrived. Automation is paused pending subscription setup.	Call `node.activate`. For LP nodes you may be redirected to Stripe.
`ACTIVE`	The node is automated. Channels open, liquidity is deployed, and routing/leasing yield begins accruing.	This is the steady-state. Use Monitor to track earnings.
`DELETION_INITIATED`	A deactivation is in progress. Channels are closing and funds are being moved on-chain.	Wait for closures to settle. Track ETA via the `funds_available_at` field.
`DELETED`	All channels are closed and funds are released. The node is read-only history.	Terminal state.

WAITING_FOR_INIT is reserved in the enum but is no longer emitted by current versions of the API. You can treat it as equivalent to CREATED if you encounter it.

Querying state

Every node-level query returns a state field. Poll node.deployed_node for a single node, or node.deployed_nodes for the full list.

query NodeState($nodeId: String!) {
  node {
    id
    deployed_node(node_id: $nodeId) {
      id
      state
      type
      node_type
      pubkey
      created_at
      deactivation_initiated
      deleted_at
    }
  }
}

curl -X POST https://rails.amboss.tech/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AMBOSS_DASHBOARD_TOKEN" \
  -d '{
    "query": "query($nodeId: String!) { node { deployed_node(node_id: $nodeId) { id state type pubkey } } }",
    "variables": { "nodeId": "<NODE_ID>" }
  }'

import { request } from "graphql-request";

const query = `
  query($nodeId: String!) {
    node {
      deployed_node(node_id: $nodeId) {
        id state type pubkey
      }
    }
  }`;

const data = await request({
  url: "https://rails.amboss.tech/graphql",
  document: query,
  variables: { nodeId: process.env.NODE_ID },
  requestHeaders: {
    authorization: `Bearer ${process.env.AMBOSS_DASHBOARD_TOKEN}`,
  },
});

Polling guidance

State transitions are driven by background work (provisioning, on-chain confirmations, Stripe webhooks). For onboarding flows poll the node every 10-15 seconds. Once a node reaches ACTIVE, switch to event-driven monitoring of balances and earnings rather than polling state.

Common reasons for getting stuck

Stuck at WAITING_FOR_CREDENTIALS (Third Party Hosted) - the macaroon submitted via node.connect is missing required permissions. See Permissions.
Stuck at WAITING_FOR_DEPOSIT - the deposit has been sent but is still pending on-chain confirmation. Check on a block explorer; the node confirms after one block.
Stuck at WAITING_FOR_ACTIVATION - the activation flow was opened but the Stripe subscription was not completed. Re-call node.activate to receive a fresh external URL.
ACTIVE but no earnings - channels have not finished opening, or the node has not yet been selected as a routing partner. Initial yield typically appears within the first 24-48 hours after activation.