Table of Contents

Token Definition

A Token Definition is a concept in Nexus that allows you to group multiple blockchain-specific token implementations under a single unified token identity. This enables a single token to exist across multiple blockchains while maintaining a consistent identity, properties, and business logic.

Overview

Token Definitions solve a fundamental challenge in multi-blockchain token management: how to represent the same token across different blockchain networks while maintaining consistency and enabling cross-chain operations. With Token Definitions, you can create a token once and deploy it across Algorand, Stellar, Ethereum, the Internal Network, and other supported blockchains.

Key Characteristics

  • Single Identity: One token code representing the same token across multiple blockchains
  • Consistent Properties: Shared name, code, type, rate, and pegging information
  • Flexible Deployment: Deploy on any combination of supported blockchains
  • Cross-Chain Operations: Enable token movements between different blockchains via Internal Network
  • Centralized Management: Update shared properties once, reflected across all variants

Why Use Token Definitions?

Problem: Multi-Blockchain Fragmentation

Without Token Definitions, each blockchain requires a separate, independent token:

  • CUSD on Algorand (separate issuer address)
  • CUSD on Stellar (different issuer address)
  • CUSD on Internal Network (virtual representation)

This creates fragmentation:

  • No relationship between the tokens
  • Separate management for each variant
  • Difficult cross-chain reconciliation
  • Complex liquidity management

Solution: Unified Token Definition

With Token Definitions, you create one CUSD definition that links all implementations:

Token Definition: CUSD
-> CUSD on ALGO (Issuer: ALGO123...)
-> CUSD on XLM (Issuer: STELLAR456...)
-> CUSD on ETH (Contract: 0x789...)
-> CUSD on INTERNAL (Virtual)

Token Definition Properties

A Token Definition contains the following core properties that are shared across all token variants:

Required Properties

Property Type Description
Code string (max 12) Unique identifier for the token (e.g., CUSD, CEUR)
Name string (max 100) Human-readable name (e.g., "Quantoz USD")
TokenType enum Type of token: PeggedByCurrency or PeggedByAsset
LabelPartner reference The organization that owns this token definition
CreatedBy string (max 256) User or system that created the definition

Optional Properties

Property Type Description
Rate decimal Exchange rate (required for PeggedByCurrency tokens)
PeggedByCurrency reference Currency for currency-pegged tokens
BackgroundColor string Hex color code for UI representation
NOTE

Each Token Definition receives a unique identifier that persists across all variants. This ID is used to link individual token implementations to their definition.

Token Variants

Each blockchain implementation of a token definition is called a Token Variant. Token variants inherit the core properties from the definition but have blockchain-specific attributes:

Variant-Specific Properties

Property Description
IssuerAddress Blockchain-specific issuer/contract address
BlockchainId Unique identifier on the blockchain (e.g., asset ID, contract address)
Decimals Blockchain-specific decimal precision
Status Variant-specific status (Draft, Active, Disabled)
Authorization Flags Blockchain-specific authorization settings

Example: Multi-Chain Token

A token definition for CUSD (Quantoz USD) can have variants across multiple blockchains:

Token Definition:

  • Code: CUSD
  • Name: Quantoz USD
  • Type: PeggedByCurrency
  • Rate: 1.0
  • Pegged Currency: USD

Variant 1: Algorand

  • Code: CUSD
  • Blockchain: ALGO
  • Issuer: ALGO_ISSUER_ADDRESS
  • Blockchain ID: 12345678 (Algorand asset ID)
  • Decimals: 6

Variant 2: Internal Network

  • Code: CUSD
  • Blockchain: INTERNAL
  • Issuer: INTERNAL_ISSUER (logical address)
  • Decimals: 6

Creating Token Definitions

Step 1: Create the Definition

Create a token definition through the Nexus Portal. This establishes the core properties that will be shared across all blockchain variants.

Navigate to: Token Management -> Token Definitions -> Create New

Required Information:

  • Token code (unique identifier)
  • Token name (display name)
  • Token type (PeggedByCurrency or PeggedByAsset)
  • Rate (for currency-pegged tokens)
  • Pegged currency (for currency-pegged tokens)

Step 2: Create Token Variants

After creating the definition, create token variants on each desired blockchain through the Portal or Token API:

Navigate to: Settings -> Definitions -> [Select Definition] -> Create Token

For Algorand Variant:

  • Select the token definition to link to
  • Define Algorand-specific settings (decimals, authorization flags)
  • Set overall limit and account limits

For Internal Network Variant:

  • Select the same token definition
  • Internal tokens can be activated immediately
  • No blockchain-specific issuer needed

Step 3: Assign Existing Tokens

You can also assign existing tokens to a definition after creation through the Portal. This is useful for migrating existing tokens into a multi-blockchain structure.

Navigate to: Settings -> Definitions -> [Select Definition] -> Assign Tokens

Token Definition Validation

When assigning a token to a definition, Nexus validates compatibility:

Type Matching

The token's type must match the definition's type:

Valid Assignment:

  • Definition Type: PeggedByCurrency
  • Token Type: PeggedByCurrency

Invalid Assignment:

  • Definition Type: PeggedByCurrency
  • Token Type: PeggedByAsset
  • Result: Assignment rejected

Currency Matching

For PeggedByCurrency tokens, the pegged currency must match:

Valid Assignment:

  • Definition Currency: USD
  • Token Currency: USD

Invalid Assignment:

  • Definition Currency: USD
  • Token Currency: EUR
  • Result: Assignment rejected

Rate Matching

The token rate must match the definition rate:

Valid Assignment:

  • Definition Rate: 1.0
  • Token Rate: 1.0

Invalid Assignment:

  • Definition Rate: 1.0
  • Token Rate: 0.5
  • Result: Assignment rejected

Cross-Chain Operations

Token Definitions enable cross-chain operations through the Nexus APIs and Portal:

Query Tokens by Definition

The Portal and API allow you to view all variants of a token across different blockchains. This provides a complete view of where a token is deployed and the status of each variant.

View in Portal: Settings -> Definitions -> [Select Definition] -> View Variants

Returned Information:

  • Token code and name
  • Blockchain code
  • Issuer address
  • Status (Draft, Active, Disabled)
  • Blockchain-specific ID
  • Decimals

Cross-Chain Payments

When a token has multiple variants, you can transfer tokens between blockchains using the Internal Network as an intermediary:

IMPORTANT

Direct transfers between different blockchains (e.g., Algorand to Stellar) are not supported. All cross-chain transfers must use the Internal Network as an intermediary. The process requires two separate payment operations.

See the Internal Network documentation for more details on setting up virtual accounts and performing cross-chain transfers.

Limitations

Definition Constraints

  • Immutable Type: Once created, a definition's TokenType cannot be changed
  • Currency Lock: For PeggedByCurrency tokens, the pegged currency cannot be changed after creation
  • Code Uniqueness: Token definition codes must be unique within your organization

Variant Constraints

  • Blockchain Limits: Each blockchain has its own limits on code length, name length, and decimals
  • One Variant Per Blockchain: A definition can only have one active variant per blockchain
  • Compatibility Validation: All variants must match the definition's type, currency, and rate

Cross-Chain Operations

  • No Direct Transfers: Cross-chain transfers cannot go directly between blockchains; Internal Network intermediary required
  • Two-Step Process: Each cross-chain transfer requires two separate payment operations
  • Virtual Account Required: Must have a virtual account on Internal Network to facilitate transfers
  • Blockchain-Specific Rules: Some operations may behave differently on different blockchains
  • Network Fees: Each blockchain variant incurs its own network fees for on-chain operations