# Rell best practices · Chromia Docs (concept)

> This topic shares real examples and best practices for building Rell dapps on Chromia, using actual implementations from the FT4 library.

Source: https://docs.chromia.com/rell/rell-best-practices/

# Rell best practices

On this page

* [Entity modeling best practices](#entity-modeling-best-practices)
* [Composite keys for uniqueness](#composite-keys-for-uniqueness)
* [Strategic indexing](#strategic-indexing)
* [FT4 account integration patterns](#ft4-account-integration-patterns)
* [Account registration strategy](#account-registration-strategy)
* [Query patterns](#query-patterns)
* [Queries with pagination](#queries-with-pagination)
* [Testing patterns](#testing-patterns)
* [Testing error cases](#testing-error-cases)
* [Security patterns](#security-patterns)
* [Input validation](#input-validation)
* [Error handling](#error-handling)
* [Performance optimization patterns](#performance-optimization-patterns)
* [Efficient data structures](#efficient-data-structures)
* [Batch operations for efficiency](#batch-operations-for-efficiency)
* [Code formatting best practices](#code-formatting-best-practices)
* [Consistent spacing and indentation](#consistent-spacing-and-indentation)
* [Function parameter formatting](#function-parameter-formatting)
* [Query formatting consistency](#query-formatting-consistency)
* [Utility functions and helper patterns](#utility-functions-and-helper-patterns)
* [Rate limiting for spam prevention](#rate-limiting-for-spam-prevention)
* [Security best practices](#security-best-practices)
* [Input validation patterns](#input-validation-patterns)
* [Documentation for dapp context](#documentation-for-dapp-context)

This topic shares real examples and best practices for building Rell dapps on Chromia, using actual implementations from
the FT4 library.

## Entity modeling best practices

### Composite keys for uniqueness

Use composite keys to ensure uniqueness within specific contexts, which is crucial for distributed state integrity:

Rell

```
// FT4 balance entity demonstrates proper composite key usage
entity balance {
  key accounts.account, asset; // Composite key ensures one balance per account+asset
  mutable amount: big_integer;
}
```

### Strategic indexing

Index fields used in cross-entity queries and `@*` operations, but avoid over-indexing as it impacts write performance:

Rell

```
// FT4 account entity with strategic indexing
entity account {
  key id: byte_array;
  index type: text; // For querying accounts by type
}
```

## FT4 account integration patterns

### Account registration strategy

Use account registration strategies for your dapp
[documentation](https://docs.chromia.com/build/ft4/account-management/overview/#registration-strategies),
[cookbook](https://docs.chromia.com/build/cookbook/overview/), [course](https://chromia.com/learn/monetize-dapp/introduction/)

## Query patterns

### Queries with pagination

FT4 demonstrates proper query patterns with pagination: [documentation](https://docs.chromia.com/build/ft4/pagination/),
[example](https://gitlab.com/chromaway/ft4-lib/-/blob/v1.1.0/rell/src/lib/build/ft4/core/assets/history.rell?ref_type=tags#L129)

## Testing patterns

### Testing error cases

Rell

```
function test_transfer_validation_must_fail() {
    val sender = rell.test.keypairs.alice;

    // Test invalid amount
    val failure = rell.test.tx()
        .op(transfer(
            rell.test.keypairs.bob.pub,
            get_test_asset_id(),
            -1
        ))
        .sign(sender)
        .run_must_fail("Amount must be positive");

    assert_true(failure.message.contains("Amount must be positive"));

    // Test insufficient balance
    val failure2 = rell.test.tx()
        .op(transfer(
            rell.test.keypairs.bob.pub,
            get_test_asset_id(),
            1000000
        ))
        .sign(sender)
        .run_must_fail("Insufficient balance");

    assert_true(failure2.message.contains("Insufficient balance"));
}
```

## Security patterns

### Input validation

FT4 demonstrates thorough input validation:

Rell

```
function validate_asset_registration(
    name: text,
    symbol: text,
    decimals: integer
): boolean {
    // Validate name
    require(name.size() >= 1, "Name cannot be empty");
    require(name.size() <= 1024, "Name too long");

    // Validate symbol
    require(symbol.matches("^[A-Z0-9_]+$"),
        "Symbol must contain only uppercase letters, numbers, and underscores");
    require(symbol.size() <= 10, "Symbol too long");

    // Validate decimals
    require(decimals >= 0, "Decimals cannot be negative");
    require(decimals <= 18, "Too many decimal places");

    return true;
}
```

### Error handling

FT4's approach to error handling:

Rell

```
function safe_get_balance(
    account_id: byte_array,
    asset_id: byte_array
): big_integer {
    // Handle non-existent balance
    val balance_record = balance @? {
        .account.id == account_id,
        .asset.id == asset_id
    };

    return if (balance_record != null) balance_record.amount else 0;
}
```

## Performance optimization patterns

### Efficient data structures

Use appropriate data structures for your use case:

Rell

```
// For frequent lookups - use indexed fields
entity user_session {
    key session_id: text;
    index account_id: byte_array; // Fast lookup by account
    index expires_at: timestamp; // Fast cleanup of expired sessions
    created_at: timestamp;
}

// For hierarchical data - use composite keys
entity post_comment {
    key post_id: integer, comment_id: integer;
    index author_account: byte_array;
    parent_comment_id: integer?;
    content: text;
    created_at: timestamp;
}
```

### Batch operations for efficiency

Process multiple items in single operations:

Rell

```
operation batch_transfer(
    transfers: list<(
        recipient: byte_array,
        asset_id: byte_array,
        amount: big_integer
    )>
) {
    val account = auth.authenticate();

    // Validate all transfers first
    for (transfer in transfers) {
        require(transfer.amount > 0, "All amounts must be positive");
        require(
            transfer.recipient.size() == 32,
            "Invalid recipient account ID"
        );
    }

    // Group transfers by asset for efficient balance checking
    val transfers_by_asset = map<byte_array, list<(recipient: byte_array, amount: big_integer)>>();

    for (transfer in transfers) {
        if (transfers_by_asset[transfer.asset_id] == null) {
            transfers_by_asset[transfer.asset_id] = list<(recipient: byte_array, amount: big_integer)>();
        }
        transfers_by_asset[transfer.asset_id].add((
            recipient = transfer.recipient,
            amount = transfer.amount
        ));
    }

    for ((asset_id, asset_transfers) in transfers_by_asset) {
        val total_amount = asset_transfers @ { } ( @sum .amount );
        val asset = asset @ { .id == asset_id };
        val sender_balance = balance @ {
            .account.id == account.id,
            .asset.id == asset_id
        };
        require(
            sender_balance.amount >= total_amount,
            "Insufficient balance for asset"
        );

        // Process all transfers for this asset
        for (transfer in asset_transfers) {
            transfer_internal(account.id, transfer.recipient, asset_id, transfer.amount);
        }
    }
}
```

## Code formatting best practices

### Consistent spacing and indentation

Follow consistent spacing patterns for better readability:

Rell

```
// ✅ Good formatting
entity user {
    key account_id: byte_array;
    index display_name: text;
    created_at: timestamp;
}

operation create_user(account_id: byte_array, display_name: text) {
    val existing_user = user @? { .account_id == account_id };
    require(existing_user == null, "User already exists");

    create user (
        account_id = account_id,
        display_name = display_name,
        created_at = op_context.last_block_time
    );
}

// ❌ Poor formatting
entity user{
key account_id:byte_array;
index display_name:text;
created_at:timestamp;
}

operation create_user(account_id:byte_array,display_name:text){
val existing_user=user@?{.account_id==account_id};
require(existing_user==null,"User already exists");
create user(account_id=account_id,display_name=display_name,created_at=op_context.last_block_time);
}
```

### Function parameter formatting

Use consistent parameter formatting for better readability:

Rell

```
// ✅ Good - parameters on separate lines for complex functions
operation transfer_with_validation(
    from_account: byte_array,
    to_account: byte_array,
    asset_id: byte_array,
    amount: big_integer,
    memo: text?
) {
    // ... implementation
}

// ✅ Good - simple functions can be on one line
operation simple_update(account_id: byte_array, status: text) {
    // ... implementation
}
```

### Query formatting consistency

Structure queries for optimal readability:

Rell

```
// ✅ Good - clear query structure
query get_user_transactions(
    account_id: byte_array,
    limit: integer = 10
) = transfer_log @* {
    .from_account == account_id or .to_account == account_id
} (
    .tx_id,
    .amount,
    .created_at
) limit limit;

// ✅ Good - complex queries with proper line breaks
query get_user_activity_summary(
    account_id: byte_array,
    days: integer = 30
) {
    val cutoff_time = op_context.last_block_time - days * 24 * 60 * 60 * 1000;

    return (
        sent_count = transfer_log @* {
            .from_account == account_id,
            .created_at >= cutoff_time
        }.size(),
        received_count = transfer_log @* {
            .to_account == account_id,
            .created_at >= cutoff_time
        }.size()
    );
}
```

### Utility functions and helper patterns

Create reusable utility functions for common operations:

Rell

```
function validate_transfer_amount(
    from_balance: big_integer,
    transfer_amount: big_integer
): boolean {
    require(from_balance >= 0, "Balance cannot be negative");
    require(transfer_amount > 0, "Transfer amount must be positive");

    return from_balance >= transfer_amount;
}

function require_account_exists(account_id: byte_array): account =
    account @ { .id == account_id };

function get_account_balance(
    account_id: byte_array,
    asset_id: byte_array
): big_integer {
    val balance_record = balance @? {
        .account.id == account_id,
        .asset.id == asset_id
    };
    return if (balance_record != null) balance_record.amount else 0;
}

function format_currency(amount: big_integer, decimals: integer = 2): text {
    val divisor = 10 ** decimals;
    val whole_part = amount / divisor;
    val decimal_part = amount % divisor;
    return "%d.%0*d".format(whole_part, decimals, decimal_part);
}

// Helper function for admin verification
function is_admin(account_id: byte_array): boolean {
    // This should be implemented based on your specific admin system
    // Example implementation:
    val admin_account = account_metadata @? {
        .account_id == account_id,
        .display_name == "admin"
    };
    return admin_account != null;
}
```

## Rate limiting for spam prevention

Use [rate limiting](https://docs.chromia.com/ecosystem/providers/nodes/economy-chain-config/#ft4-configuration).

## Security best practices

### Input validation patterns

Always validate inputs thoroughly:

Rell

```
function validate_account_id(account_id: byte_array): boolean {
    require(account_id.size() == 32, "Account ID must be 32 bytes");
    require(
        account_id != x"0000000000000000000000000000000000000000000000000000000000000000",
        "Account ID cannot be zero"
    );
    return true;
}

function validate_asset_id(asset_id: byte_array): boolean {
    require(asset_id.size() == 32, "Asset ID must be 32 bytes");
    require(
        asset_id != x"0000000000000000000000000000000000000000000000000000000000000000",
        "Asset ID cannot be zero"
    );
    return true;
}

function validate_amount_precision(
    amount: big_integer,
    decimals: integer
): boolean {
    require(amount >= 0, "Amount cannot be negative");
    require(decimals >= 0, "Decimals cannot be negative");
    require(decimals <= 18, "Too many decimal places");
    return true;
}
```

## Documentation for dapp context

Document dapp-specific behaviors that aren't obvious from the code:

Rell

```
/**
 * Creates account metadata for a user account
 * IMPORTANT CONSIDERATIONS:
 * - Creates immutable on-chain record
 * - Gas costs scale with display name length due to indexing
 * - Consider data size impact on network state
 */
operation create_account_metadata(
    account_id: byte_array,
    display_name: text
): text {
    // Authentication should be handled through auth.authenticate() with proper auth handlers
    val account = auth.authenticate();

    // Verify the authenticated account matches the target account_id
    require(account.id == account_id, "Can only create metadata for own account");

    val existing_metadata = account_metadata @? { .account_id == account_id };
    require(existing_metadata == null, "Account metadata already exists");

    create account_metadata (
        account_id = account_id,
        display_name = display_name,
        created_at = op_context.last_block_time,
        last_active = op_context.last_block_time
    );

    return "Account metadata created successfully";
}
```

[View this page on docs.chromia.com](https://docs.chromia.com/rell/rell-best-practices/)Content mirrored from the live docs
