Staking (RUJI, bRUNE, TCY)

Technical documentation for wallets, portfolio apps, staking dashboards, and user-facing apps integrating staking markets powered by the Rujira staking contract.

This guide is scoped to user-owned staking positions. It does not cover protocol/operator revenue setup, revenue converter administration, or contract sudo messages.

Overview

The Rujira staking contract is generic. A deployed staking market can be configured for RUJI, bRUNE, TCY, or another supported bond token. Each market has its own contract address and config.

A staking market supports two user paths:

Path	User sends	User receives	Reward behavior
Account staking	The market's bond_denom	Account staking position (non-transferable)	Rewards accrue as revenue_denom and are claimed manually.
Liquid staking	The market's bond_denom	Liquid staking receipt tokens (transferable)	Rewards are converted into more bond_denom, increasing the value of each receipt token.

Always query the staking contract config before building transactions. The contract tells you which token to stake through bond_denom and which reward token account stakers can claim through revenue_denom.

Existing Staking Markets

Use this table as an integration hint, not as the source of truth. The live contract config should still be queried before every staking flow.

Market	Bond denom	Typical display	Liquid receipt denom	Receipt display
RUJI staking	x/ruji	RUJI	x/staking-x/ruji	sRUJI
bRUNE staking	x/brune	bRUNE	x/staking-x/brune	ybRUNE
TCY staking	tcy	TCY	x/staking-tcy	sTCY

The bank metadata for x/ruji, x/brune, and the liquid receipt denoms uses 8 display decimals. The tcy supply exists on chain, but the bank metadata endpoint may not return a base metadata object for tcy; clients should use the chain/app asset registry or a maintained token list as a display fallback.

Who This Guide Is For

Integrator	Typical integration
Wallets	Show RUJI balance, account stake, pending revenue, liquid receipt balance, and sign bond/claim/withdraw/unbond transactions.
Portfolio apps	Display account positions, pending rewards, liquid share positions, and pool status.
Staking UIs	Provide standard staking and auto-compounding staking flows.
Card or repayment apps	Let users claim staking revenue and then use the claimed funds in the app's own repayment flow.

Prerequisites

• The user needs a THOR/Rujira app-layer address.

• The user needs the staking bond_denom; for RUJI staking this is x/ruji.

• Account staking rewards are paid in revenue_denom, which should be read from contract config.

• Liquid staking receipt token denom is derived from the bond denom: x/staking-<bond_denom>.

• All Uint128 amounts are strings in JSON.

Useful references:

• RUJI token FAQ

• Rujira secured assets

• RUJI bank metadata

• Deployment list

Architecture

Wallet / staking UI / portfolio app
        |
        | CosmWasm query / execute
        v
Rujira staking contract
        |
        +-- Account staking
        |       +-- bond bond_denom
        |       +-- claim revenue_denom
        |       +-- withdraw bond_denom + claimed rewards
        |
        +-- Liquid staking
                +-- bond bond_denom
                +-- mint x/staking-<bond_denom>
                +-- convert revenue into more bond_denom
                +-- unbond receipt token for proportional bond_denom

Do not call settle directly. It is an internal self-call used by the staking contract after revenue conversion.

Contract Address and Config

The current staking contract addresses should be read from official deployment data. If static addresses are needed in a downstream guide, verify them first against the Rujira deployment page and look for the relevant rujira-staking instances.

Model staking markets by contract address:

type StakingMarket = {
  label: string;
  contract: string;
  expectedBondDenom?: string;
};

const markets: StakingMarket[] = [
  {
    label: "RUJI",
    contract: "thor1...", // Verify from deployment data.
    expectedBondDenom: "x/ruji",
  },
  {
    label: "bRUNE",
    contract: "thor1...", // Verify from deployment data.
    expectedBondDenom: "x/brune",
  },
  {
    label: "TCY",
    contract: "thor1...", // Verify from deployment data.
    expectedBondDenom: "tcy",
  },
];

Query config before rendering the staking UI:

{ "config": {} }

Example response shape:

{
  "bond_denom": "x/ruji",
  "revenue_denom": "rune",
  "revenue_converter": [
    "thor1converter...",
    "base64_encoded_execute_msg",
    "1000000"
  ],
  "fee": ["0.05", "thor1fees..."]
}

Field	Meaning for user integrations
bond_denom	Token users bond into this staking market. Examples: x/ruji, x/brune, tcy.
revenue_denom	Token account stakers claim as rewards.
revenue_converter	Converter used internally to compound liquid staking rewards. Wallet UIs should display or ignore this, not execute it.
fee	Optional protocol fee on distributable revenue, shaped as [percentage, recipient].

Do not hardcode the reward token from product copy. Different staking markets can pay different revenue_denom assets, and the live config is the source of truth for transaction builders.

Staking Concepts

Account Staking vs. Liquid Staking

Account staking and liquid staking use the same bond token, but they behave differently.

Concept	Account staking	Liquid staking
Execute namespace	account	liquid
User sends	bond_denom	bond_denom
User receives	Stored account position	Receipt token balance
Rewards	Claimed manually as revenue_denom	Converted into more bond_denom in the pool
Exit	account.withdraw	liquid.unbond with receipt token funds

Liquid Receipt Denom

The liquid receipt denom is:

x/staking-<bond_denom>

Examples:

Bond denom	Receipt denom
x/ruji	x/staking-x/ruji
x/brune	x/staking-x/brune
tcy	x/staking-tcy

Derive this from config in code:

function receiptDenom(bondDenom: string): string {
  return `x/staking-${bondDenom}`;
}

Do not assume the receipt denom from the display symbol. Use the bank denom.

Revenue Distribution Timing

Revenue distribution is lazy. Sending revenue_denom to the staking contract does not immediately update every account. The contract distributes pending revenue at the start of the next account or liquid staking execute.

For UI, this means:

• status shows the current stored state plus raw undistributed revenue.

• account.pending_revenue can change after any staking action triggers distribution.

• Re-query status, account, and bank balances after every staking transaction.

Query Integration

Query Status

{ "status": {} }

Response shape:

{
  "account_bond": "100000000",
  "assigned_revenue": "5000000",
  "liquid_bond_shares": "75000000",
  "liquid_bond_size": "78000000",
  "undistributed_revenue": "1000000"
}

Field	Meaning
account_bond	Total bond_denom bonded in account staking.
assigned_revenue	Total revenue_denom already assigned to account stakers but not yet claimed.
liquid_bond_shares	Total liquid receipt shares issued.
liquid_bond_size	Total bond_denom backing the liquid staking pool.
undistributed_revenue	revenue_denom currently in the contract but not yet distributed.

For liquid staking display, the simple pool ratio is:

bond_per_share = liquid_bond_size / liquid_bond_shares

If liquid_bond_shares is zero, show the ratio as zero or unavailable.

Query Account

{
  "account": {
    "addr": "thor1user..."
  }
}

Response shape:

{
  "addr": "thor1user...",
  "bonded": "100000000",
  "pending_revenue": "2500000"
}

account only works for addresses that have an account staking record. If the query returns not found, show a zero account position:

{
  "addr": "thor1user...",
  "bonded": "0",
  "pending_revenue": "0"
}

There is no account-list query and no pagination in the staking contract.

Account Staking Integration

Account staking is the standard staking path where the user bonds the market token and manually claims rewards.

Bond

{
  "account": {
    "bond": {}
  }
}

Funds:

[
  { "denom": "<config.bond_denom>", "amount": "100000000" }
]

Use config.bond_denom for the funds denom. Send only the bond denom.

If the account already has pending rewards, bond claims those rewards first and sends them to the user before increasing the bonded amount.

Claim

{
  "account": {
    "claim": {}
  }
}

Claim is nonpayable. Send no funds.

If there are claimable rewards, the contract sends revenue_denom to the user. If the user already has an account staking record and rewards are zero, the transaction can still complete and emit a zero-amount claim event. If the user has never bonded, do not offer claim; there is no account record yet.

Withdraw

Partial withdraw:

{
  "account": {
    "withdraw": {
      "amount": "50000000"
    }
  }
}

Full withdraw:

{
  "account": {
    "withdraw": {
      "amount": null
    }
  }
}

Withdraw is nonpayable. Send no funds.

Withdraw requires an existing account staking record. It always claims pending rewards first. The payout can include both bond_denom and revenue_denom.

TypeScript Example: Account Bond

import { CosmWasmClient, SigningCosmWasmClient } from "@cosmjs/cosmwasm-stargate";

const rpc = "See Developer Endpoints";
const sender = "thor1...";
const amount = "100000000"; // Base units for the selected bond denom.

const market = {
  label: "bRUNE",
  contract: "thor1...", // Verify from deployment data.
  expectedBondDenom: "x/brune",
};

const stakingContract = market.contract;

const queryClient = await CosmWasmClient.connect(rpc);

const config = await queryClient.queryContractSmart(stakingContract, {
  config: {},
});

if (market.expectedBondDenom && config.bond_denom !== market.expectedBondDenom) {
  throw new Error(`Unexpected bond denom: ${config.bond_denom}`);
}

const signingClient = await SigningCosmWasmClient.connectWithSigner(rpc, signer);

const tx = await signingClient.execute(
  sender,
  stakingContract,
  {
    account: {
      bond: {},
    },
  },
  "auto",
  "",
  [{ denom: config.bond_denom, amount }],
);

TypeScript Example: Claim and Use Rewards

This is the wallet/user flow a card or repayment app should use. The staking contract claims rewards to the user first; the app then uses the user's resulting revenue_denom balance in its own repayment flow.

async function queryAccountOrZero(addr: string) {
  try {
    return await queryClient.queryContractSmart(stakingContract, {
      account: {
        addr,
      },
    });
  } catch (error) {
    if (String(error).toLowerCase().includes("not found")) {
      return {
        addr,
        bonded: "0",
        pending_revenue: "0",
      };
    }

    throw error;
  }
}

const before = await queryAccountOrZero(sender);

if (BigInt(before.pending_revenue) > 0n) {
  await signingClient.execute(
    sender,
    stakingContract,
    {
      account: {
        claim: {},
      },
    },
    "auto",
    "",
    [],
  );
}

// After the claim is indexed, query the user's revenue_denom bank balance
// and use that balance in the app's own repayment transaction.

Liquid Staking Integration

Liquid staking is the auto-compounding path. The user bonds the market token and receives receipt tokens. As revenue is converted into more bond_denom, the pool size grows and each receipt token represents more underlying bond token.

Bond

{
  "liquid": {
    "bond": {}
  }
}

Funds:

[
  { "denom": "<config.bond_denom>", "amount": "100000000" }
]

The contract mints receipt tokens to the user. Derive the receipt denom from config:

receipt_denom = x/staking-<config.bond_denom>

Unbond

{
  "liquid": {
    "unbond": {}
  }
}

Funds:

[
  { "denom": "<receipt_denom>", "amount": "100000000" }
]

Liquid unbond burns receipt tokens and returns the user's proportional bond_denom. The returned amount depends on the current pool ratio and is floor-rounded by share-pool math.

TypeScript Example: Liquid Bond and Unbond

function liquidReceiptDenom(bondDenom: string): string {
  return `x/staking-${bondDenom}`;
}

const config = await queryClient.queryContractSmart(stakingContract, {
  config: {},
});

const receipt = liquidReceiptDenom(config.bond_denom);

await signingClient.execute(
  sender,
  stakingContract,
  {
    liquid: {
      bond: {},
    },
  },
  "auto",
  "",
  [{ denom: config.bond_denom, amount: "100000000" }],
);

await signingClient.execute(
  sender,
  stakingContract,
  {
    liquid: {
      unbond: {},
    },
  },
  "auto",
  "",
  [{ denom: receipt, amount: "50000000" }],
);

Events

CosmWasm event types usually appear in indexed transaction logs with a wasm- prefix.

Account staking events:

wasm-rujira-staking/account.bond
wasm-rujira-staking/account.claim
wasm-rujira-staking/account.withdraw

Event	Attributes
account.bond	owner, amount
account.claim	owner, amount
account.withdraw	owner, amount, rewards

Liquid staking events:

wasm-rujira-staking/liquid.bond
wasm-rujira-staking/liquid.unbond

Event	Attributes
liquid.bond	owner, amount, shares
liquid.unbond	owner, shares, returned

Internal settlement event:

wasm-rujira-staking/settle

settle has a returned attribute and is emitted by the contract's internal revenue-conversion flow. User interfaces can index it, but users should not build or sign settle messages.

Use events for fast UI updates, but re-query contract state and bank balances after the transaction is indexed.

UI and UX Checklist

• Show account staking and liquid staking as separate modes.

• Query config first and use its bond_denom and revenue_denom.

• Display the bond token from bank metadata or a maintained token registry. Do not hardcode a single staking denom.

• For TCY, handle metadata fallback because tcy may not return a base bank metadata object even though the denom exists on chain.

• For account staking, show bonded and pending_revenue.

• For account staking, explain that rewards are claimable manually in revenue_denom.

• For liquid staking, show receipt token balance and estimated underlying bond_denom.

• For liquid staking, explain that rewards compound by increasing pool value, not by sending revenue directly to the user.

• For card or repayment apps, claim rewards first, then use the user's claimed balance in the app repayment flow.

• Prevent users from attaching funds to claim or withdraw.

• Prevent users from sending config.bond_denom to liquid.unbond; it requires the receipt token.

• Refresh status, account, and bank balances after every transaction.

Common Errors and Gotchas

Issue	Why it happens	Integrator fix
Wrong funds denom on bond	Account and liquid bond require bond_denom.	Query config and send only config.bond_denom.
Claim sent with funds	account.claim is nonpayable.	Send no funds.
Withdraw sent with funds	account.withdraw is nonpayable.	Send no funds.
Liquid unbond sends the bond token	liquid.unbond burns receipt tokens, not bond tokens.	Send x/staking-<bond_denom> funds.
Account query fails for a new user	The account record does not exist until the user bonds.	Treat not found as zero bonded and zero pending revenue.
Claim or withdraw fails for a new user	There is no account staking record yet.	Disable claim and withdraw until the user has an account position.
Pending rewards look stale	Distribution runs lazily during staking executes.	Re-query after transactions and explain update timing.
User expects liquid rewards as the account reward token	Liquid rewards are converted into more bond token value.	Show pool ratio and receipt-token underlying value.
Tiny liquid bond mints zero shares	Share math floors issuance.	Block very small deposits or explain the failure.
Unbond amount exceeds receipt balance	Share pool rejects over-unbonding.	Check the user's receipt token balance before signing.

Message Reference

Queries

{ "config": {} }

{ "status": {} }

{ "account": { "addr": "thor1user..." } }

Executes

{ "account": { "bond": {} } }

{ "account": { "claim": {} } }

{ "account": { "withdraw": { "amount": "1000000" } } }

{ "account": { "withdraw": { "amount": null } } }

{ "liquid": { "bond": {} } }

{ "liquid": { "unbond": {} } }

Do not use this internal message in wallet or user integrations:

{ "settle": { "balance": "0" } }