# Dynamic Vault listing (database-based metadata) · Chromia Docs (concept)

> Flexible approach to list your dapp on the Chromia Vault using database-stored metadata. Perfect for production dapps or when you need frequent content updates.

Source: https://docs.chromia.com/build/deployment/vault-listing/dynamic-vault-listing/

# Dynamic Vault listing (database-based metadata)

On this page

* [Prerequisites](#prerequisites)
* [Implementation](#implementation)
* [Configuration](#configuration)
* [1. Include the module in your main Rell file](#1-include-the-module-in-your-main-rell-file)
* [2. Update your chromia.yml file](#2-update-your-chromiayml-file)
* [Deployment](#deployment)
* [Verify the data](#verify-the-data)
* [Automatic listing](#automatic-listing)
* [Making changes](#making-changes)
* [Admin key management](#admin-key-management)
* [Optional: Storing media content on chain](#optional-storing-media-content-on-chain)

Flexible approach to list your dapp on the Chromia Vault using database-stored metadata. Perfect for production dapps or
when you need frequent content updates.

## Prerequisites

* A deployed dapp on Chromia (Mainnet or Testnet)
* Media files for your dapp (icons, screenshots, etc.)
* Admin key pair for managing operations

## Implementation

Create a new module for Vault listing functionality. Copy this complete implementation into your
`dynamic_vault_listing.rell` file:

Important customization

You only need to change "My dapp name" to your actual dapp's name in this code. All other parts can remain as shown.

./dynamic\_vault\_listing.rellRell

```
module;

struct module_args {
    admin_pubkey: byte_array;
    dapp_name: text;
}

function require_admin_signer() =
require(op_context.is_signer(chain_context.args.admin_pubkey), "The operation requires admin signer");

enum dapp_content_type {
    landscape,
    portrait,
    promotional,
    video,
    icon
}

entity dapp {
    key name;
    mutable description: text = "";
    mutable launch_url: text = "";
    mutable genre: text = "";
}

entity dapp_media {
    key dapp, name;
    mutable url: text = "";
    type: dapp_content_type;
}

entity blockchain {
    key dapp, brid: byte_array;
    index brid;
    index mutable name: text;
    mutable role: text;
}

operation create_or_update_dapp(description: text, launch_url: text, genre: text) {
    require_admin_signer();
    functions.create_or_update_dapp(chain_context.args.dapp_name, description, launch_url, genre);
}

operation create_or_update_blockchain(brid: byte_array, chain_name: text, role: text) {
    require_admin_signer();
    val dapp = get_dapp_by_name(chain_context.args.dapp_name);
    functions.create_or_update_blockchain(dapp, brid, chain_name, role);
}

operation create_or_update_dapp_media(name, url: text, type: dapp_content_type) {
    require_admin_signer();
    functions.create_or_update_dapp_media(chain_context.args.dapp_name, name, url, type);
}

query find_dapp_details(dapp_rowid: rowid, requested_content_types: list<dapp_content_type>? = null){
    val dapp = get_dapp_by_name(chain_context.args.dapp_name);
    return map_dapp_details(dapp, requested_content_types);
}

namespace functions {
    function create_or_update_blockchain(dapp, brid: byte_array, name: text, role: text) {
        val blockchain = blockchain @? { brid };
        if (empty(blockchain)) {
            create blockchain ( dapp, brid, name, role );
        } else {
            update blockchain ( name, role );
        }
    }

    function create_or_update_dapp(name, description: text, launch_url: text, genre: text) {
        val dapp = dapp @? { name };
        if (empty(dapp)) {
            create dapp ( name, description, launch_url, genre );
        } else {
            update dapp ( description, launch_url, genre );
        }
    }

    function create_or_update_dapp_media(dapp_name: text, name, url: text, type: dapp_content_type) {
        val dapp = dapp @? { dapp_name == .name };
        require(not empty(dapp), "dapp not found");
        val media = dapp_media @? { dapp!!, name };
        if (empty(media)) {
            create dapp_media ( dapp, name, url, type );
        } else {
            update media ( url );
        }
    }
}

function get_dapp_by_name(name) = dapp @ { name };

function map_dapp_details(dapp, requested_content_types: list<dapp_content_type>? = null) {
    val blockchains = find_and_map_dapp_blockchains(dapp);
    val dapp_media = if (not empty(requested_content_types)) find_and_map_dapp_media(
        dapp,
        requested_content_types
    ) else null;

    return (
        rowid = dapp.rowid,
        name = dapp.name,
        description = dapp.description,
        launch_url = dapp.launch_url,
        genre = dapp.genre,
        chain_list = blockchains,
        content = dapp_media
    ).to_gtv_pretty();
}

function find_and_map_dapp_blockchains(dapp) =
    blockchain @* { dapp } (
    @omit @sort .rowid,
    name = .name,
    brid = .brid,
    role = .role
);

function find_and_map_dapp_media(dapp, requested_content_types: list<dapp_content_type>) =
    dapp_media @* {
    dapp,
    .type in requested_content_types
} (
    @omit @sort .rowid,
    name = .name,
    url = .url,
    type = .type
);
```

## Configuration

### 1. Include the module in your main Rell file

Add the following line to your main Rell file (e.g., `main.rell`) to import the vault listing module:

Rell

```
import dynamic_vault_listing;
```

### 2. Update your `chromia.yml` file

Update your `chromia.yml` file to include the Vault listing module with admin authentication:

./chromia.ymlYAML

```
blockchains:
  <blockchain_name>:
    module: main
    moduleArgs:
      dynamic_vault_listing:
        admin_pubkey: x"<public_key>" # Your admin public key
        dapp_name: <blockchain_name>
```

## Deployment

**1. Update your dapp with Vault module**

After adding the code, deploy your changes to either Testnet or Mainnet:

Terminal

```
chr deployment update --network <deployment_name> --blockchain <blockchain_name>
```

**2. Create dapp metadata**

Terminal

```
chr tx --network <deployment_name> --blockchain <blockchain_name> create_or_update_dapp "Your dapp description" "https://your-dapp-url.com" "Your genre"
```

Expected output:

Plain text

```
transaction with rid A9B05BCC105E69AD627984463BF0B6A9496CF3D9AFD721683B21DC1C91382BCB was posted and confirmed
```

**3. Create blockchain data**

Terminal

```
chr tx --network <deployment_name> --blockchain <blockchain_name> create_or_update_blockchain 'x"D2...3B2"' <blockchain_name> "Role description"
```

Expected output:

Plain text

```
transaction with rid A9B05BCC105E69AD627984463BF0B6A9496CF3D9AFD721683B21DC1C91382BCB was posted and confirmed
```

**4. Create media data (use a link to Filehub or external image service)**

Terminal

```
chr tx --network <deployment_name> --blockchain <blockchain_name> create_or_update_dapp_media "icon" "https://pbs.twimg.com/profile_images/1928427668728598528/xbFphaFl_400x400.jpg" 4
```

Expected output:

Plain text

```
transaction with rid A9B05BCC105E69AD627984463BF0B6A9496CF3D9AFD721683B21DC1C91382BCB was posted and confirmed
```

Enum values

The media type parameter uses the enum index: `landscape=0`, `portrait=1`, `promotional=2`, `video=3`, `icon=4`.

### Verify the data

Terminal

```
# Basic verification (no media content)
chr query --network <deployment_name> --blockchain <blockchain_name> --output-format json find_dapp_details dapp_rowid=0 'requested_content_types=[]'
```

Terminal

```
# Get all media content
chr query --network <deployment_name> --blockchain <blockchain_name> --output-format json find_dapp_details dapp_rowid=0 'requested_content_types=["landscape", "portrait", "promotional", "video", "icon"]'
```

## Automatic listing

Once you implement the query and functions, your dapp will be automatically listed in the Chromia Vault based on the
information it provides.

## Making changes

To update your dapp's metadata, call the appropriate operations:

* **Update description/URL/genre**: Use `create_or_update_dapp`
* **Update blockchain info**: Use `create_or_update_blockchain`
* **Add/update media**: Use `create_or_update_dapp_media`

No redeployment is required - changes are immediate!

## Admin key management

Keep your admin key secure and accessible for making updates. The admin key is specified in your `chromia.yml` file and
is required for all metadata operations.

## Optional: Storing media content on chain

If you want to store your media files on-chain for enhanced decentralization, you can use [Filehub](https://docs.chromia.com/ecosystem/filehub/overview/),
Chromia's decentralized storage platform.

Filehub benefits

Consider using [Filehub](https://docs.chromia.com/ecosystem/filehub/overview/) for decentralized media storage. Fixed cost of $0.10 per MB for perpetual
storage with free access for everyone. Requires CHR tokens on the Economy Chain (minimum 1 CHR deposit).

Recommended image sizes:

* Horizontal image preview - 180px x 100px (recommended x3 - 540px x 300px)
* Vertical image preview - 180px x 240px (recommended x3 - 540px x 720px)
* Big image - 510px x 286px (recommended x3 - 1530px x 858px)
* Pagination image - 86px x 48px (recommended x3 - 258px x 144px)

[View this page on docs.chromia.com](https://docs.chromia.com/build/deployment/vault-listing/dynamic-vault-listing/)Content mirrored from the live docs
