> For the complete documentation index, see [llms.txt](https://docs.nfh.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nfh.global/build/onboarding/file-based.md).

# File-based onboarding

Publish DeDi files on your own domain — publishing your index file and registry is your onboarding, for NFOs and NPs alike.

On this path you publish records directly on a domain under your own control, in conformance with the [DeDi protocol specification](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol).

Any file-based publisher — NFO or NP — must publish at least two files:

| File                                                                                                                                                                               | Location                                                                                                                                                                                                          | Purpose                                                    | Schema                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [DeDi index file](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/docs/publishing-dedi-files.md#6-the-manifest--well-knowndediindexjson) | `https://<your-domain>/.well-known/dedi.index.json`                                                                                                                                                               | Lists your signing keys and the registry files you publish | [dedi-manifest.schema.json](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/schemas/dedi-manifest.schema.json)                                                                                                                                                                                                                                                                                                                                                |
| [Registry file(s)](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/docs/publishing-dedi-files.md#5-the-dedi-file)                        | URL declared in the index file ([hosting conventions](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/docs/publishing-dedi-files.md#52-layout-and-hosting-conventions)) | The registry records themselves, signed by you             | [dedi-file.schema.json](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/schemas/dedi-file.schema.json); records follow [beckn\_subscriber\_reference.json](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/schemas/beckn_subscriber_reference.json) (NFO) or [beckn\_subscriber.json](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/schemas/beckn_subscriber.json) (NP) |

Both files are signed with your key — see [Signing your files](#signing-your-files) below.

## How a file-based network comes together

Publishing your DeDi index file and registry **is** your onboarding — for NFOs and NPs alike. The sequence below shows an NFO onboarding its network together with its NPs.

**Step 1 — NFO expresses intent to join the NFH fabric.** The NFO enters its domain on the [NFH fabric onboarding portal](https://fabric.nfh.global/#onboarding).

**Step 2 — NFO publishes its index and participant registry.** The NFO publishes its DeDi index file at `nfo.com/.well-known/dedi.index.json`, and creates its reference registry of network participants — suggested name `nfoname_networkname_env_ref_registry` — at `nfo.com/dedi/nfoname_networkname_env_ref_registry.json`. The registry must use the [Beckn Subscriber Reference schema](https://raw.githubusercontent.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/refs/heads/main/schemas/beckn_subscriber_reference.json).

**Step 3 — NP publishes its records.** The NP publishes its DeDi index file at `np.com/.well-known/dedi.index.json`, and creates its network key registry at `np.com/dedi/nfoname_networkname_env_registry.json` (e.g. `nfo-x_mobility_prod_registry.json`), using the [Beckn Subscriber schema](https://raw.githubusercontent.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/refs/heads/main/schemas/beckn_subscriber.json). It then shares its registry URL with the NFO.

**Step 4 — NFO updates its records.** The NFO adds the new NP's details to its registry of NPs, re-signs, and republishes.

In Steps 2–4, every file is signed before it is published — see [Signing your files](#signing-your-files).

```mermaid
sequenceDiagram
    participant NFO as NFO (nfo.com)
    participant P as NFH fabric onboarding portal
    participant NP as NP (np.com)

    NFO->>P: 1. Express intent — enter domain
    NFO->>NFO: 2. Publish /.well-known/dedi.index.json<br/>+ nfoname_networkname_env_ref_registry.json
    NP->>NP: 3. Publish /.well-known/dedi.index.json<br/>+ nfoname_networkname_env_registry.json
    NP-->>NFO: 3. Share URL of registry (or dedi.global lookup URL)
    NFO->>NFO: 4. Add NP record to reference registry,<br/>re-sign and republish
```

## If you are an NFO

* **Onboarding your network**: do Steps 1 and 2 — express intent on the onboarding portal, then publish your index file and reference registry. See the NFO's index file and reference registry laid out in full in the [worked example](/build/onboarding/worked-example.md#dedi-index-file-of-the-nfo).
* **Adding an NP to your network**: do Step 4 each time an NP joins — add a record with the NP's `subscriber_id` and registry URL (in either [URL form](#registry-url-forms)) to your reference registry, then re-sign and republish the registry file. If your index file carries a [digest](#adding-a-digest-optional) for that registry, also update the digest, then re-sign and republish the index file.

## If you are an NP

Your onboarding is Step 3 — publishing your DeDi index file at `np.com/.well-known/dedi.index.json` and your network key registry at `np.com/dedi/nfoname_networkname_env_registry.json`, using the Beckn Subscriber schema. See NP1's index file and registry laid out in full in the [worked example](/build/onboarding/worked-example.md#dedi-index-file-of-np1).

Each record in your registry describes one of your subscriber endpoints:

| Field                 | What to fill                                                      | Example                             |
| --------------------- | ----------------------------------------------------------------- | ----------------------------------- |
| Subscriber ID         | Your unique identifier, typically your domain                     | np.com                              |
| Subscriber URL        | Your ONIX receiver endpoint                                       | `https://np.com/beckn/bap/receiver` |
| Type                  | Your role on the network                                          | consumer node or provider node      |
| Domain                | Deprecated field; can be ignored                                  | \*                                  |
| Signing Public Key    | Your Ed25519 public key, Base64-encoded, without header or footer | eyAeqGFtAuks...                     |
| Encryption Public Key | Optional encryption public key                                    | lCI84I0Q0U0w\...                    |
| Countries             | Countries where you operate                                       | \["IND"]                            |

If you operate in multiple roles, publish a separate record for each role.

{% hint style="warning" %}
Your Subscriber ID must be your domain itself, or a subdomain of it — e.g. a domain of `example.com` may use subscriber IDs `example.com` or `bap.example.com`, but not `something.com`.
{% endhint %}

**Generating the signing keypair for ONIX**: you can use [this utility script](https://github.com/beckn/beckn-onix/blob/main/install/generate-ed25519-keys.go) provided in ONIX, or any other tool, as long as it produces an Ed25519 key pair with the private key as the raw 32-byte seed and the public key as the raw 32-byte public key, both Base64-encoded (standard RFC 4648, with padding).

Sign your registry file with the key declared in your DeDi index file, then publish both.

* **Joining under an NFO**: share your registry URL with the NFO, which adds your record to its reference registry (Step 4).
* **Not tied to any NFO yet**: enter your domain on the NFH fabric onboarding portal yourself, then publish. You are then on the NFH fabric standalone, and NFOs can add you to their networks later.

## Signing your files

[dedi-cli](https://github.com/nfh-trust-labs/dedi-cli) generates your signing key, signs your index and registry files, and checks the signatures locally, as the [DeDi protocol](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/docs/publishing-dedi-files.md) requires. Install it with Go:

```bash
go install github.com/nfh-trust-labs/dedi-cli/cmd/dedi-cli@latest
```

Or download a pre-built binary for Linux, macOS or Windows from the [Releases page](https://github.com/nfh-trust-labs/dedi-cli/releases).

**1. Generate a signing key** (once):

```bash
dedi-cli keygen --kid key-1 --out key.json
```

`key.json` holds your private key. Keep it secret, never commit it, and back it up — you need it every time you re-sign.

**This is not your ONIX key.** You work with two different signing keys:

| Key                   | What it signs                                   | Where its public key goes                    |
| --------------------- | ----------------------------------------------- | -------------------------------------------- |
| ONIX signing key      | Beckn messages, live during transactions        | `signing_public_key` in your registry record |
| DeDi file-signing key | Your index and registry files, when you publish | `keys` in your index file                    |

{% hint style="info" %}
We recommend a separate key for each. You *can* reuse one keypair for both (re-encoded for each place), but keeping them apart is safer: the ONIX key lives on a running server, while the DeDi key can stay offline. And if the ONIX key leaks or you rotate it, your index file isn't affected.
{% endhint %}

**2. Sign each file.** Fill in every field of the index or registry file except the signing key and `proof`, then:

```bash
dedi-cli sign --key key.json --in unsigned/nfo-x_mobility_prod_ref_registry.json --out signed/nfo-x_mobility_prod_ref_registry.json
```

`sign` detects whether the input is an index file or a registry file, adds your public key if it is missing, and writes the `proof`. Before signing, it also catches mistakes that would otherwise fail silently later:

* records whose `details` don't match the registry's schema;
* for Beckn Subscriber registries, a `subscriber_id` that is not your domain or a subdomain of it — DeDi never picks up such a record;
* a `next_update` that is already in the past.

If you're using a [digest](#adding-a-digest-optional), sign the registry file first, then add its digest to the index file, then sign the index file.

**3. Check the signature** before you publish:

```bash
dedi-cli verify --in signed/nfo-x_mobility_prod_ref_registry.json
```

This only checks the signature itself, not domain binding or freshness. dedi-cli doesn't publish: upload the signed files to your domain yourself, exactly as `sign` wrote them.

## Adding a digest (optional)

Each registry entry in your index file's `files` can carry a `digest` — a hash of the registry file's current content. The [DeDi specification](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/docs/publishing-dedi-files.md#63-digests) makes it optional, but it helps crawlers: a crawler compares the digest in your index file with the one it saw last time. If it hasn't changed, the crawler skips re-fetching the registry. If it has changed, the crawler fetches the new version. Without a digest, crawlers have to fetch the registry file itself to find out whether it changed.

The digest is the SHA-256 hash of the exact bytes of the signed registry file you publish, written as `sha-256:` followed by the lowercase hex hash:

{% tabs %}
{% tab title="macOS" %}

```bash
echo "sha-256:$(shasum -a 256 signed/nfo-x_mobility_prod_ref_registry.json | cut -d ' ' -f 1)"
```

{% endtab %}

{% tab title="Linux" %}

```bash
echo "sha-256:$(sha256sum signed/nfo-x_mobility_prod_ref_registry.json | cut -d ' ' -f 1)"
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
"sha-256:" + (Get-FileHash signed\nfo-x_mobility_prod_ref_registry.json -Algorithm SHA256).Hash.ToLower()
```

{% endtab %}
{% endtabs %}

Put the result in that registry's `files[].digest` in your index file, then sign the index file. Keep these rules in mind:

* **Hash the signed file.** Compute the digest after signing the registry, and publish that file unchanged — reformatting or re-saving it changes the bytes and breaks the digest.
* **Update it on every change.** Each time you re-sign a registry, recompute its digest, update the index file and re-sign it too. A stale digest makes verifiers reject the registry until the index file catches up.
* **Or keep it in a separate digests file.** To avoid re-signing your index file on every registry change, you can put digests in a signed digests file linked from the index file's `digests` URL instead — see [§6.3 of the specification](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol/blob/main/docs/publishing-dedi-files.md#63-digests).

## Reuse of an existing dedi.global presence

Where an NP already maintains a presence on dedi.global, that existing record may be used for onboarding, without requiring the NP to publish files independently. In this case, the lookup URL from dedi.global can be used in the NFO's registry, for example:

```
https://api.dedi.global/dedi/lookup/np2.com/nfo-x_mobility_prod_registry
```

## Registry URL forms

An NP's registry URL can be in one of two forms, depending on the path the NP uses:

| NP path    | URL form                                               | Example                                                                   |
| ---------- | ------------------------------------------------------ | ------------------------------------------------------------------------- |
| Hosted     | `api.dedi.global/dedi/lookup/<domain>/<registry-name>` | `https://api.dedi.global/dedi/lookup/np.com/nfo-x_mobility_prod_registry` |
| File-based | `<domain>/dedi/<registry-name>`                        | `https://np.com/dedi/nfo-x_mobility_prod_registry`                        |

See all of these files fully written out in the [worked example](/build/onboarding/worked-example.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nfh.global/build/onboarding/file-based.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.