> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/ecosystem/nodes/rust/quick-start",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Rust node quick start

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

Deploy a TON Rust node using the Helm chart.

For chart-specific values, configuration examples, and operator documentation such as networking, Vault, and monitoring, refer to the [chart README](https://github.com/RSquad/ton-rust-node/tree/master/helm/ton-rust-node).

## Image configuration

The Helm chart defines the container image through Helm values:

* `image.repository`
* `image.tag`

Avoid relying on a hard-coded tag in the documentation, because default values can change between chart releases.

To see the current defaults, refer to:

* [Chart values](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/values.yaml)
* [Chart `appVersion`](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/Chart.yaml)

## Node roles

The chart deploys the same TON Rust node binary in two operational roles: validator and full node.

| Role      | Purpose                                                          | Ports to expose                                                                                                      |
| --------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Validator | Participates in consensus and validator elections.               | Keep `liteserver` and `jsonRpc` disabled; expose only required node and ops ports (`adnl`, and `control` if needed). |
| Full node | Syncs chain and serves external clients (APIs, explorers, bots). | Enable `liteserver`, `jsonRpc`, or both when external access is required.                                            |

* Run validators and full nodes as separate Helm releases so resources, security policy, and lifecycle stay isolated.
* If full chain history is needed, enable archival mode as described in [Archival node settings](/ecosystem/nodes/rust/node-config#archival-node).

## Quick start

### Prerequisites

* Kubernetes cluster access configured for `helm`.
* [Helm 3 installed](https://helm.sh/docs/intro/install/).
* Access to the chart at `./helm/ton-rust-node` by cloning the [`ton-rust-node` repository](https://github.com/RSquad/ton-rust-node/tree/master/helm/ton-rust-node).
* A values file for the release, for example `values.yaml`.

Install and deploy TON Rust node with [Helm](https://helm.sh) using a minimal configuration, then optionally enable liteserver and JSON Remote Procedure Call (JSON-RPC) ports.

To deploy a validator, use this page for base deployment and keep the liteserver and JSON-RPC ports disabled. For validator election and operations workflow, use the validator guide [(`nodectl`)](https://github.com/RSquad/ton-rust-node/tree/master/helm/nodectl).

### 1. Prepare a values file

Not runnable

```yaml title="values.yaml" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}

replicas: 2

services:
  adnl:
    perReplica:
      - annotations:
          metallb.universe.tf/loadBalancerIPs: "1.2.3.4"
      - annotations:
          metallb.universe.tf/loadBalancerIPs: "5.6.7.8"

nodeConfigs:
  node-0.json: |
    { "log_config_name": "/main/logs.config.yml", ... }
  node-1.json: |
    { "log_config_name": "/main/logs.config.yml", ... }
```

The chart includes a mainnet [`globalConfig`](/ecosystem/nodes/rust/global-config) and a default [`logsConfig`](/ecosystem/nodes/rust/logs-config). This minimal setup requires only [`nodeConfigs`](/ecosystem/nodes/rust/node-config).

Other networking modes are described in the [Networking section](/ecosystem/nodes/rust/node-config#networking), including `NodePort`, `hostPort`, `hostNetwork`, and ingress controllers such as `ingress-nginx`.

### 2. Install the release

All `helm` commands below require [Helm to be installed](https://helm.sh/docs/intro/install/) and available in `PATH`.

Use the local chart from [`ton-rust-node/helm/ton-rust-node`](https://github.com/RSquad/ton-rust-node/tree/e8bd0451b326099146a90a913beedaebd952fa56/helm/ton-rust-node):

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
helm install <RELEASE_NAME> ./helm/ton-rust-node -f <VALUES_FILE>
```

Or install from an Open Container Initiative registry:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
helm install <RELEASE_NAME> oci://ghcr.io/rsquad/ton-rust-node/helm/node -f <VALUES_FILE>
```

## Verify deployment

Check pod status for the release:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
kubectl get pods -l app.kubernetes.io/name=node,app.kubernetes.io/instance=<RELEASE_NAME>
```

Check service status for the release:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
kubectl get svc -l app.kubernetes.io/name=node,app.kubernetes.io/instance=<RELEASE_NAME>
```

## Enable liteserver and JSON-RPC ports

Use this only for full node deployments. Do not expose these ports on validators.

Not runnable

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
replicas: 2

ports:
  liteserver: 40000
  jsonRpc: 8081

services:
  adnl:
    perReplica:
      - annotations:
          metallb.universe.tf/loadBalancerIPs: "10.0.0.1"
      - annotations:
          metallb.universe.tf/loadBalancerIPs: "10.0.0.2"

nodeConfigs:
  node-0.json: |
    { "log_config_name": "/main/logs.config.yml", ... }
  node-1.json: |
    { "log_config_name": "/main/logs.config.yml", ... }
```

## Run multiple releases in the same namespace

Use different release names:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
helm install validator ./helm/ton-rust-node -f validator-values.yaml
helm install fullnode ./helm/ton-rust-node -f fullnode-values.yaml
```

This creates separate StatefulSets (`validator`, `fullnode`), services (`validator-0`, `fullnode-0`), and configs.

## Operational notes

### Helm hooks

This chart does not rely on [Helm hooks](https://helm.sh/docs/topics/charts_hooks/) for bootstrap. Instead, an init container seeds `/main` from ConfigMaps and Secrets before the main container starts.

If pre- or post-deployment actions are required, such as backups before upgrades or data integrity checks, implement them outside the chart. This can be done in a CI/CD pipeline, dedicated Jobs, or Helm hooks in a wrapper chart.

Chart implementation references:

* [Init bootstrap script](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/files/init-script.sh)
* [StatefulSet init container](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/templates/statefulset.yaml)

### Ingress and TLS

* The chart does not create Kubernetes `Ingress` resources.

  For UDP and TCP stream ports, including ADNL UDP, liteserver TCP, control TCP, a standard HTTP Ingress is not sufficient.

  If `ingress-nginx` is already used, [TCP and UDP ports can be exposed](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/) through its `tcp-services` and `udp-services` ConfigMaps, which enable stream proxying.

* TLS termination depends on the protocol used by the exposed port.

  * For HTTP-based ports such as some JSON-RPC setups, terminate TLS at an L7 proxy or an Ingress controller that supports HTTP routing.
  * For pure TCP stream proxying, terminate TLS at an external load balancer or TCP proxy, or use a TCP proxy that supports TLS passthrough or termination.
  * ADNL uses UDP and is typically exposed directly through `LoadBalancer`, `hostPort`, or `hostNetwork`. TLS termination does not apply to it in the same way as for HTTP.

* [Chart networking reference](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/docs/networking.md)

### PVC resizing and retention

The chart defines `volumeClaimTemplates` in the StatefulSet for `main`, `db`, `keys`, and optionally `logs`.

PVC resizing (expansion) depends on the StorageClass configuration. If the StorageClass is `allowVolumeExpansion: true`, the PVC size can be increased by editing the PVC. Shrinking PVCs is not supported.

Related Kubernetes documentation:

* [PVC expansion overview](https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/)
* If data must be preserved, consider using the PersistentVolume [reclaim policy](https://kubernetes.io/docs/tasks/administer-cluster/change-pv-reclaim-policy/) `Retain` instead of the default `Delete` for dynamically provisioned volumes.

Chart retention configuration:

* The chart supports `helm.sh/resource-policy: keep` for selected PVCs through `storage.<vol>.resourcePolicy`; defaults keep for `main` and `keys`.
* [Values chart](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/values.yaml)

### Safe upgrades, backups, and rolling restarts

1. Use `helm upgrade` with an explicit image tag bump.
2. Treat the `db` and `keys` PVCs as critical state. Plan backups according to the storage backend.
3. Configuration changes:
   * Inline configuration changes trigger pod restarts through a checksum annotation.
   * External `existing*` ConfigMaps and Secrets are managed outside the chart. Changing them does not trigger an automatic rollout. Restart the pods or upgrade the release explicitly.

### Exposure mode examples

* Use one [exposure mode](/ecosystem/nodes/rust/node-config#exposure-modes) per deployment. Combining modes is possible but uncommon.
* [Chart implementation reference for per-port Services](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/templates/services.yaml)

### Vault integration using VAULT\_URL

The chart supports an operator workflow where private keys are stored in an encrypted vault file, and the vault URL is passed through the `VAULT_URL` environment variable.

Recommended configuration (Secret-based):

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
vault:
  secretName: ton-node-vault
  secretKey: VAULT_URL
```

The Secret should contain `VAULT_URL`. Example format: `file:///keys/vault.json&master_key=<64-hex-chars>`.

<Aside type="caution">
  In the RSquad chart workflow, Vault is configured through `VAULT_URL`. Do not rely on `secrets_vault_config` in `config.json` when using this approach.

  Keep the vault master key secure: it decrypts the vault file.
</Aside>

* [Chart Vault reference](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/docs/vault.md)
* Chart implementation references:
  * [`VAULT_URL` injection helper](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/templates/_helpers.tpl)
  * [Container env wiring](https://raw.githubusercontent.com/RSquad/ton-rust-node/master/helm/ton-rust-node/templates/statefulset.yaml)

## Useful commands

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
# Check pod status (replace "my-node" with the release name)
kubectl get pods -l app.kubernetes.io/name=node,app.kubernetes.io/instance=my-node

# Get external service IPs
kubectl get svc -l app.kubernetes.io/name=node,app.kubernetes.io/instance=my-node

# View logs
kubectl logs my-node-0 -c ton-node

# Exec into pod
kubectl exec -it my-node-0 -c ton-node -- /bin/sh
```