11.5. Rewards and Tokens

This tutorial covers the dAIEDGE Middleware DLT token economy, including token balance management, earning rewards, and the rewards system.

Overview

The token system enables:

Platform currency for marketplace transactions
Reward mechanisms for contributions
Incentivizing hardware providers
Automated reward distribution
Manual reward grants

Prerequisites

Completed Authentication, Wallet Management, and Identity Management tutorials
Active session and wallet
Understanding of Role Management
Admin roles required for token management and rewards (see below)

Required Roles

Token Management Roles

The token system uses a hierarchical role structure:

Role	Purpose	Can Be Granted By
`TOKEN_ADMIN_ROLE`	Update token metadata, pause/unpause token transfers	ADMIN_ROLE
`TOKEN_MINTER_ROLE`	Mint new tokens, create token supply	TOKEN_ADMIN_ROLE
`TOKEN_USER_ROLE`	Burn owned tokens, reduce token supply	ADMIN_ROLE

Rewards Management Roles

The rewards system has three distinct roles:

Role	Purpose	Can Be Granted By
`REWARD_ADMIN_ROLE`	Set/remove reward rules, grant manual rewards, pause/unpause system	ADMIN_ROLE
`REWARD_DISTRIBUTOR_ROLE`	Distribute on-chain action rewards automatically	REWARD_ADMIN_ROLE
`ORACLE_ROLE`	Distribute off-chain action rewards, report external events	REWARD_ADMIN_ROLE

Authorization

For token minting (Step 2):

Your identity must have TOKEN_MINTER_ROLE (granted by TOKEN_ADMIN_ROLE holder)

For reward rules (Step 4):

Your identity must have REWARD_ADMIN_ROLE (granted by ADMIN_ROLE)

For manual rewards (Step 5):

Your identity must have REWARD_ADMIN_ROLE (granted by ADMIN_ROLE)

For on-chain rewards (Step 6):

Your identity must have REWARD_DISTRIBUTOR_ROLE (granted by REWARD_ADMIN_ROLE holder)

For off-chain rewards:

Your identity must have ORACLE_ROLE (granted by REWARD_ADMIN_ROLE holder)

See the Role Management tutorial to understand role hierarchies.

Step 1: Check Token Balance

View the token balance for an identity.

Endpoint

GET /api/v1/tokens/balance?did={did}

Request

curl -X GET "https://middleware-daiedge.bisite.usal.es/api/v1/tokens/balance?did=did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"

async with daiedge_middleware_client.ApiClient() as api_client:
    tokens_api = daiedge_middleware_client.TokensApi(api_client)
    # NOTE: The API returns a plain integer, not a JSON object.
    balance = await tokens_api.tokens_balance_get(
        did="did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
    )
    print(f"Balance: {balance}")

Response (200 OK)

Returns the token balance as a number (integer).

Error Responses

Code	Error	Cause
400	`INVALID_DID`	Identity format invalid
500	`TRANSACTION_ERROR`	Blockchain query failed

Step 2: Mint Tokens (Admin Only)

Create new tokens and assign to an identity.

Endpoint

POST /api/v1/tokens/mint

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/tokens/mint \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "000013d7a9f4c6b8e3a1d5f2",
    "password": "AdminPass123!",
    "did": "did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
    "amount": "10000"
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    tokens_api = daiedge_middleware_client.TokensApi(api_client)
    # NOTE: 'did' is the minter AND recipient — must have TOKEN_MINTER_ROLE.
    # NOTE: 'amount' must be passed as a string.
    await tokens_api.tokens_mint_post(
        daiedge_middleware_client.MintTokensBody(
            wallet_id="000013d7a9f4c6b8e3a1d5f2",
            password="AdminPass123!",
            did="did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
            amount="10000",
        )
    )
    print("Tokens minted")

Request Body

Field	Type	Required	Description
`walletId`	string	Yes	Admin wallet ID
`password`	string	Yes	Wallet password
`did`	string	Yes	Minter DID — must have `TOKEN_MINTER_ROLE`, also receives the tokens
`amount`	string	Yes	Number of tokens to mint (passed as string)

Response (200 OK)

{}

Authorization

Only identities with TOKEN_MINTER_ROLE can mint tokens. This role is granted by TOKEN_ADMIN_ROLE holders.

Error Responses

Code	Error	Cause
404	`WALLET_NOT_FOUND`	Wallet doesn’t exist
400	`WRONG_PASSWORD`	Wallet password incorrect
400	`INVALID_DID`	Identity format invalid
400	`INVALID_AMOUNT`	Amount negative
403	`TOKEN_MINTER_ROLE_REQUIRED`	DID lacks `TOKEN_MINTER_ROLE`
403	`INVALID_WALLET`	Wallet doesn’t belong to you
500	`TRANSACTION_ERROR`	Blockchain transaction failed (check you have `TOKEN_MINTER_ROLE`)

Step 3: View Reward History

Check reward history for an identity.

Endpoint

GET /api/v1/rewards?page={page}&did={did}

Request

curl -X GET "https://middleware-daiedge.bisite.usal.es/api/v1/rewards?page=1&did=did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"

async with daiedge_middleware_client.ApiClient() as api_client:
    rewards_api = daiedge_middleware_client.RewardManagerApi(api_client)
    history = await rewards_api.rewards_get(
        did="did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
        page=1,
    )
    print(f"total: {history.total}")
    for item in history.history:
        print(f"  [{item.id}] action={item.action} amount={item.amount} type={item.reward_type}")

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1)
`did`	string	Yes	Identity address

Response (200 OK)

{
  "history": [
    {
      "id": "000014e8b6a5d9c7f2e4a1b3",
      "identity": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "action": "HARDWARE_REGISTRATION",
      "rewardType": "on-chain",
      "amount": 500,
      "created": 1697000000000
    },
    {
      "id": "000015f9c7b6a8d5e3f2a4c1",
      "identity": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "action": "BENCHMARK_EXECUTION",
      "rewardType": "manual",
      "amount": 1000,
      "created": 1697100000000
    }
  ],
  "page": 1,
  "totalPages": 3,
  "total": 65
}

Response Fields

Field	Description
`id`	Reward record ID
`identity`	Recipient identity
`action`	Action that triggered reward
`rewardType`	Reward type: `on-chain`, `off-chain`, or `manual`
`amount`	Token amount awarded
`created`	Timestamp

Step 4: Set Reward Rule (Admin Only)

Define automatic rewards for specific actions.

Endpoint

POST /api/v1/rewards/set-reward-rule

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/rewards/set-reward-rule \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "000016a8d7c5f9b3e6a2d4f1",
    "password": "AdminPass123!",
    "userDID": "did:ethr:development:0x6A9c2E5d8F1b4A7c9D2e5F8a1C4d7E9b2A5c8D1f",
    "action": "HARDWARE_REGISTRATION",
    "rewardAmount": 500
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    rewards_api = daiedge_middleware_client.RewardManagerApi(api_client)
    await rewards_api.rewards_set_reward_rule_post(
        daiedge_middleware_client.SetRewardRuleBody(
            wallet_id="000016a8d7c5f9b3e6a2d4f1",
            password="AdminPass123!",
            user_did="did:ethr:development:0x6A9c2E5d8F1b4A7c9D2e5F8a1C4d7E9b2A5c8D1f",
            action="HARDWARE_REGISTRATION",
            reward_amount=500,
        )
    )
    print("Reward rule set")

Request Body

Field	Type	Required	Description
`walletId`	string	Yes	Admin wallet ID
`password`	string	Yes	Wallet password
`userDID`	string	Yes	Admin identity DID (format: `did:ethr:{network}:0x...`)
`action`	string	Yes	Action identifier (max 255 chars)
`rewardAmount`	number	Yes	Token reward (non-negative integer)

Common Actions

HARDWARE_REGISTRATION - Registering hardware
BENCHMARK_EXECUTION - Executing benchmarks
DATASET_REGISTRATION - Registering datasets
AI_MODEL_REGISTRATION - Registering AI models
MARKETPLACE_SALE - Selling resources

Response (200 OK)

{}

Authorization

Only identities with REWARD_ADMIN_ROLE can set reward rules.

Error Responses

Code	Error	Cause
404	`WALLET_NOT_FOUND`	Wallet doesn’t exist
400	`WRONG_PASSWORD`	Wallet password incorrect
400	`INVALID_USER_DID`	User DID format invalid
400	`INVALID_ACTION`	Action empty or > 255 chars
400	`INVALID_REWARD_AMOUNT`	Reward amount negative
403	`INVALID_WALLET`	Wallet doesn’t belong to you
500	`TRANSACTION_ERROR`	Blockchain transaction failed (check you have `REWARD_ADMIN_ROLE`)

Step 5: Manual Reward

Grant tokens to an identity for contributions.

Endpoint

POST /api/v1/rewards/reward-manual

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/rewards/reward-manual \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "000017b9e8d6a4f7c5b3e2a1",
    "password": "AdminPass123!",
    "userDID": "did:ethr:development:0x7B8d1F4c9E2a5D7b9F2c4E8a1D5f7C9e2B4a7D1f",
    "did": "did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
    "rewardAmount": 1000
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    rewards_api = daiedge_middleware_client.RewardManagerApi(api_client)
    await rewards_api.rewards_reward_manual_post(
        daiedge_middleware_client.RewardManualBody(
            wallet_id="000017b9e8d6a4f7c5b3e2a1",
            password="AdminPass123!",
            user_did="did:ethr:development:0x7B8d1F4c9E2a5D7b9F2c4E8a1D5f7C9e2B4a7D1f",
            did="did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
            reward_amount=1000,
        )
    )
    print("Manual reward granted")

Request Body

Field	Type	Required	Description
`walletId`	string	Yes	Admin wallet ID
`password`	string	Yes	Wallet password
`userDID`	string	Yes	Admin identity DID (format: `did:ethr:{network}:0x...`)
`did`	string	Yes	Recipient identity DID (format: `did:ethr:{network}:0x...`)
`rewardAmount`	number	Yes	Token amount (non-negative integer)

Response (200 OK)

{}

Authorization

Only identities with REWARD_ADMIN_ROLE can grant manual rewards.

Error Responses

Code	Error	Cause
404	`WALLET_NOT_FOUND`	Wallet doesn’t exist
400	`WRONG_PASSWORD`	Wallet password incorrect
400	`INVALID_USER_DID`	User DID format invalid
400	`INVALID_DID`	Recipient identity format invalid
400	`INVALID_REWARD_AMOUNT`	Reward amount negative
403	`INVALID_WALLET`	Wallet doesn’t belong to you
500	`TRANSACTION_ERROR`	Blockchain transaction failed (check you have `REWARD_ADMIN_ROLE`)

Use Cases

Exceptional contributions
Bug bounties
Community initiatives
Special promotions
Compensation

Step 6: On-Chain Reward

Trigger automatic reward based on predefined rules.

Endpoint

POST /api/v1/rewards/reward-on-chain

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/rewards/reward-on-chain \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "000018c8a9f7d5e3b6a4c2f1",
    "password": "AdminPass123!",
    "userDID": "did:ethr:development:0x8C2e4A6d9F1b5C7e9A2d4F8b1C5e7A9c2D4f8B1e",
    "did": "did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
    "action": "HARDWARE_REGISTRATION"
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    rewards_api = daiedge_middleware_client.RewardManagerApi(api_client)
    await rewards_api.rewards_reward_on_chain_post(
        daiedge_middleware_client.RewardOnChainBody(
            wallet_id="000018c8a9f7d5e3b6a4c2f1",
            password="AdminPass123!",
            user_did="did:ethr:development:0x8C2e4A6d9F1b5C7e9A2d4F8b1C5e7A9c2D4f8B1e",
            did="did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
            action="HARDWARE_REGISTRATION",
        )
    )
    print("On-chain reward distributed")

Request Body

Field	Type	Required	Description
`walletId`	string	Yes	Admin wallet ID
`password`	string	Yes	Wallet password
`userDID`	string	Yes	Admin identity DID (format: `did:ethr:{network}:0x...`)
`did`	string	Yes	Recipient identity DID (format: `did:ethr:{network}:0x...`)
`action`	string	Yes	Action that triggered reward

Response (200 OK)

{}

Note: The reward amount is determined by the reward rule set for this action.

Authorization

Only identities with REWARD_DISTRIBUTOR_ROLE can distribute on-chain rewards.

Error Responses

Code	Error	Cause
404	`WALLET_NOT_FOUND`	Wallet doesn’t exist
400	`WRONG_PASSWORD`	Wallet password incorrect
400	`INVALID_USER_DID`	User DID format invalid
400	`INVALID_DID`	Recipient identity format invalid
400	`INVALID_ACTION`	Action empty or not found in reward rules
403	`INVALID_WALLET`	Wallet doesn’t belong to you
500	`TRANSACTION_ERROR`	Blockchain transaction failed (check you have `REWARD_DISTRIBUTOR_ROLE`)

Complete Token Lifecycle

1. Token Minting (Admin)
   → Initial distribution to users

2. Earning Tokens
   → Register resources → Automatic rewards
   → Execute benchmarks → Automatic rewards
   → Manual grants → Admin discretion

3. Using Tokens
   → Purchase resources on marketplace
   → Pay for benchmarking services
   → Access premium features

4. Token Transfer
   → Marketplace transactions
   → Ownership transfers
   → Automated by smart contracts

11.5. Rewards and Tokens

Overview

Prerequisites

Required Roles

Token Management Roles

Rewards Management Roles

Authorization

Step 1: Check Token Balance

Endpoint

Request

Response (200 OK)

Error Responses

Step 2: Mint Tokens (Admin Only)

Endpoint

Request

Request Body

Response (200 OK)

Authorization

Error Responses

Step 3: View Reward History

Endpoint

Request

Query Parameters

Response (200 OK)

Response Fields

Step 4: Set Reward Rule (Admin Only)

Endpoint

Request

Request Body

Common Actions

Response (200 OK)

Authorization

Error Responses

Step 5: Manual Reward

Endpoint

Request

Request Body

Response (200 OK)

Authorization

Error Responses

Use Cases

Step 6: On-Chain Reward

Endpoint

Request

Request Body

Response (200 OK)

Authorization

Error Responses

Complete Token Lifecycle

Related Topics