Deposit & Transfer dfTokens

⏱️ 7 min read

📖 What You'll Learn

In this tutorial you'll build a TypeScript script that:

• Deposits assets into a DeFindex vault and receives dfTokens in return

• Transfers those dfTokens to another Stellar wallet

By the end, you'll have a working script that automates this entire flow — useful for vault managers who want to run raffles, airdrops, or distribute incentives to their users.

💡 Why Would I Want to Transfer dfTokens?

When you deposit into a DeFindex vault, the vault mints dfTokens — tokens that represent your proportional share of the vault's assets. These tokens:

• Increase in value as the vault earns yield

• Can be redeemed later for the underlying assets + profits

• Are transferable, just like any other Stellar token

This means a vault manager can deposit funds, receive dfTokens, and then distribute them to other wallets. The recipients now hold vault shares without needing to deposit themselves. Some practical use cases:

Use Case	Description
🎁 Raffles & Giveaways	Deposit and distribute dfTokens as prizes
🏆 User Incentives	Reward active users with yield-bearing tokens
💼 Team Distribution	Split vault ownership across team members
🔄 OTC Transfers	Move vault positions between wallets

🎯 Prerequisites

Before starting, make sure you have:

• Node.js (v18+) and a package manager (npm, yarn, or similar)

• A Stellar wallet with enough balance for the deposit + transaction fees

• A DeFindex API key (register at api.defindex.io or contact us on Discord)

• Basic knowledge of TypeScript and the Stellar network

🧠 Key Concepts

Before diving into code, let's understand the two core operations we'll perform.

Deposit → Mint dfTokens

When you call deposit on a DeFindex vault, the contract:

1. Transfers your assets (e.g., XLM) from your wallet into the vault

2. Calculates how many shares you should receive, proportional to your contribution

3. Mints dfTokens to your wallet representing those shares

4. Optionally invests the deposited funds into the vault's strategies

The vault contract's deposit function signature looks like this:

fn deposit(
    e: Env,
    amounts_desired: Vec<i128>,
    amounts_min: Vec<i128>,
    from: Address,
    invest: bool,
) -> Result<(Vec<i128>, i128, Option<Vec<Option<AssetInvestmentAllocation>>>), ContractError>

It returns a tuple with: the actual deposited amounts, the number of dfTokens minted, and the investment allocations.

Transfer dfTokens

Here's something important: the vault contract itself is the dfToken contract. The vault implements the standard Stellar token interface, which means you can call transfer directly on the vault contract to move dfTokens between wallets:

fn transfer(e: Env, from: Address, to: Address, amount: i128)

No separate token contract needed — just call transfer on the vault address with the sender, receiver, and amount.

🏗️ Step-by-Step Implementation

Step 1: Project Setup

Create a new project and install the required dependencies:

mkdir defindex-deposit-transfer
cd defindex-deposit-transfer
npm init -y
npm install @defindex/sdk @stellar/stellar-sdk
npm install -D typescript tsx @types/node dotenv

Add a run script to your package.json:

{
  "scripts": {
    "start": "tsx src/index.ts"
  }
}

Create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

Create a .env file with your configuration:

DEFINDEX_API_KEY=sk_your_api_key_here
STELLAR_SECRET_KEY=S_your_wallet_secret_key
RECEIVER_ADDRESS=G_receiver_wallet_public_key
SOROBAN_RPC=your testnet soroban rpc url (e.g., https://soroban-testnet.stellar.org)

⚠️ Never commit your .env file to version control. Add it to your .gitignore.

Note: This tutorial uses testnet for learning purposes. For production, change SOROBAN_RPC to a mainnet endpoint (e.g., https://soroban-rpc.mainnet.stellar.gateway.fm) and update the network references in the code to Networks.PUBLIC / SupportedNetworks.MAINNET.

Step 2: Load Configuration

Create src/index.ts and start by importing dependencies and loading environment variables:

import { DefindexSDK, SupportedNetworks } from '@defindex/sdk';
import {
  rpc,
  Keypair,
  Networks,
  TransactionBuilder,
  Transaction,
  Contract,
  Address,
  BASE_FEE,
  xdr,
  scValToNative,
  nativeToScVal,
} from '@stellar/stellar-sdk';
import { config } from 'dotenv';

config();

Define your constants. You'll need to update VAULT_ADDRESS to match the vault you want to deposit into:

// ─── Constants ───────────────────────────────────────────────
const VAULT_ADDRESS = 'YOUR_VAULT_ADDRESS_HERE'; // ← Replace with your vault
const DECIMALS = 7;
const DEPOSIT_AMOUNT = 10; // Human-readable amount
const DEPOSIT_AMOUNT_RAW = BigInt(Math.round(DEPOSIT_AMOUNT * 10 ** DECIMALS));

About decimals: Stellar uses 7 decimal places for most assets. So 10 XLM = 100,000,000 stroops (base units). Always convert to raw amounts before calling contract functions. We use BigInt(Math.round(...)) to avoid floating-point precision issues with non-integer amounts like 0.5.

Now load and validate the environment variables:

// ─── Environment ─────────────────────────────────────────────
interface EnvConfig {
  apiKey: string;
  secretKey: string;
  receiverAddress: string;
  sorobanRpc: string;
}

function loadEnv(): EnvConfig {
  const apiKey = process.env.DEFINDEX_API_KEY;
  const secretKey = process.env.STELLAR_SECRET_KEY;
  const receiverAddress = process.env.RECEIVER_ADDRESS;
  const sorobanRpc = process.env.SOROBAN_RPC;

  const missing: string[] = [];
  if (!apiKey) missing.push('DEFINDEX_API_KEY');
  if (!secretKey) missing.push('STELLAR_SECRET_KEY');
  if (!receiverAddress) missing.push('RECEIVER_ADDRESS');
  if (!sorobanRpc) missing.push('SOROBAN_RPC');

  if (missing.length > 0) {
    console.error(`Missing environment variables: ${missing.join(', ')}`);
    process.exit(1);
  }

  return {
    apiKey: apiKey!,
    secretKey: secretKey!,
    receiverAddress: receiverAddress!,
    sorobanRpc: sorobanRpc!,
  };
}

Step 3: Transaction Helper

Both deposit and transfer need to submit a transaction and wait for on-chain confirmation. Let's create a reusable helper:

// ─── Transaction Helpers ─────────────────────────────────────
interface TxResult {
  txHash: string;
  returnValue?: xdr.ScVal;
}

const MAX_POLLS = 30; // 30 polls × 2s = 60s max wait

async function sendAndConfirm(
  rpcServer: rpc.Server,
  transaction: Transaction
): Promise<TxResult> {
  const response = await rpcServer.sendTransaction(transaction);

  if (response.status !== 'PENDING') {
    const errorXdr = response.errorResult?.toXDR('base64');
    if (errorXdr) {
      const errorName = xdr.TransactionResult.fromXDR(errorXdr, 'base64')
        .result()
        .switch().name;
      throw new Error(`Transaction rejected: ${errorName}`);
    }
    throw new Error(`Transaction rejected with status: ${response.status}`);
  }

  const txHash = response.hash;
  console.log(`  Submitted: ${txHash}`);
  console.log('  Waiting for confirmation...');

  // Poll until confirmed, failed, or timeout
  for (let i = 0; i < MAX_POLLS; i++) {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    const txResponse = await rpcServer.getTransaction(txHash);

    if (txResponse.status === 'SUCCESS') {
      const successResponse =
        txResponse as rpc.Api.GetSuccessfulTransactionResponse;
      return { txHash, returnValue: successResponse.returnValue };
    }

    if (txResponse.status === 'FAILED') {
      throw new Error(`Transaction failed on-chain: ${txHash}`);
    }
  }

  throw new Error(
    `Transaction not confirmed after ${MAX_POLLS * 2}s: ${txHash}`
  );
}

🔍 What this function does:

1. Submits the signed transaction to the Soroban RPC

2. Validates the transaction was accepted (status PENDING)

3. Polls every 2 seconds (up to 60s) until the transaction is confirmed or fails

4. Returns the transaction hash and the on-chain return value

Step 4: The Deposit Function 💰

This function uses the DeFindex SDK to build a deposit transaction, signs it locally, and submits it. The key part is extracting the minted dfTokens from the return value:

// ─── Deposit ─────────────────────────────────────────────────
async function deposit(
  sdk: DefindexSDK,
  rpcServer: rpc.Server,
  keypair: Keypair
): Promise<{ txHash: string; dfTokensMinted: bigint }> {
  const caller = keypair.publicKey();

  console.log('  Building deposit via SDK...');
  const depositResponse = await sdk.depositToVault(
    VAULT_ADDRESS,
    { amounts: [DEPOSIT_AMOUNT_RAW], caller, invest: true },
    SupportedNetworks.TESTNET
  );

  console.log('  Signing...');
  const tx = TransactionBuilder.fromXDR(
    depositResponse.xdr,
    Networks.TESTNET
  ) as Transaction;
  tx.sign(keypair);

  console.log('  Sending deposit...');
  const { txHash, returnValue } = await sendAndConfirm(rpcServer, tx);

  if (!returnValue) {
    throw new Error('Deposit transaction returned no value');
  }

  // The deposit function returns a tuple:
  //   Index 0: Vec<i128> → actual amounts deposited
  //   Index 1: i128      → dfTokens minted  ← this is what we need
  //   Index 2: Option     → investment allocations
  const nativeResult = scValToNative(returnValue);

  if (!Array.isArray(nativeResult) || nativeResult[1] == null) {
    throw new Error('Unexpected deposit return shape');
  }

  const dfTokensMinted = BigInt(nativeResult[1] as string | number | bigint);

  return { txHash, dfTokensMinted };
}

🔍 What this function does:

1. Builds an unsigned deposit transaction using the DeFindex SDK (depositToVault)

2. Signs the transaction with your keypair

3. Submits it to the network and waits for confirmation

4. Parses the return value to extract how many dfTokens were minted

Why invest: true? When set to true, the vault automatically allocates your deposited funds into its yield-generating strategies. Set to false if you want the funds to remain idle in the vault.

Tip: You can also pass slippageBps in the deposit params (e.g., slippageBps: 100 for 1% tolerance) to control slippage during deposit.

Note: The number of dfTokens minted is not 1:1 with the deposited amount. dfTokens represent your proportional share of the vault — their quantity depends on the vault's current share price, which changes as the vault earns yield.

Step 5: The Transfer Function 🔄

Now the interesting part — transferring dfTokens to another wallet. Since the vault contract implements the token interface, we call transfer directly on the vault contract address:

// ─── Transfer dfTokens ──────────────────────────────────────
async function transferDfTokens(
  rpcServer: rpc.Server,
  keypair: Keypair,
  toAddress: string,
  amount: bigint
): Promise<string> {
  const from = keypair.publicKey();
  const contract = new Contract(VAULT_ADDRESS);

  // Build the transfer operation on the vault contract
  const operation = contract.call(
    'transfer',
    new Address(from).toScVal(),
    new Address(toAddress).toScVal(),
    nativeToScVal(amount, { type: 'i128' })
  );

  // Create the transaction
  const account = await rpcServer.getAccount(from);
  const tx = new TransactionBuilder(account, {
    fee: BASE_FEE,
    networkPassphrase: Networks.TESTNET,
  })
    .addOperation(operation)
    .setTimeout(30)
    .build();

  // Simulate to estimate resources
  console.log('  Simulating transfer...');
  const simulation = await rpcServer.simulateTransaction(tx);

  if (rpc.Api.isSimulationError(simulation)) {
    throw new Error(`Transfer simulation failed: ${simulation.error}`);
  }

  // Assemble with simulation results, sign, and send
  const preparedTx = rpc.assembleTransaction(tx, simulation).build();
  preparedTx.sign(keypair);

  console.log('  Sending transfer...');
  const { txHash } = await sendAndConfirm(rpcServer, preparedTx);

  return txHash;
}

🔍 What this function does:

1. Creates a Contract instance pointing to the vault address

2. Builds a transfer(from, to, amount) call — this is the standard Soroban token transfer

3. Simulates the transaction to estimate the required resources (CPU, memory, ledger I/O)

4. Assembles the final transaction with the simulation results

5. Signs and submits it to the network

Why simulate first? Soroban smart contract calls require accurate resource estimation. The simulation step calculates CPU instructions, memory bytes, and ledger operations needed, so the transaction has the right resource limits to succeed on-chain.

About fees: BASE_FEE is the minimum fee (100 stroops). On a congested network, transactions with the minimum fee may be dropped. For production, consider using a higher fee (e.g., String(100 * 10)) or implementing a fee-bumping strategy.

Step 6: Put It All Together 🚀

Finally, wire everything up in a main function:

// ─── Main ────────────────────────────────────────────────────
async function main(): Promise<void> {
  const { apiKey, secretKey, receiverAddress, sorobanRpc } = loadEnv();

  const keypair = Keypair.fromSecret(secretKey);
  const walletA = keypair.publicKey();
  const walletB = receiverAddress;
  const rpcServer = new rpc.Server(sorobanRpc);
  const sdk = new DefindexSDK({ apiKey });

  console.log('='.repeat(60));
  console.log('DeFindex: Deposit & Transfer dfTokens');
  console.log('='.repeat(60));
  console.log(`  Wallet A (depositor): ${walletA}`);
  console.log(`  Wallet B (receiver):  ${walletB}`);
  console.log(`  Vault:                ${VAULT_ADDRESS}`);
  console.log(`  Deposit:              ${DEPOSIT_AMOUNT} XLM`);
  console.log('='.repeat(60));
  console.log('');

  // Step 1: Deposit into vault → receive dfTokens
  console.log('[Step 1] Depositing into vault...');
  const { txHash: depositTxHash, dfTokensMinted } = await deposit(
    sdk,
    rpcServer,
    keypair
  );
  console.log(`  ✅ Deposit confirmed: ${depositTxHash}`);
  console.log(`  dfTokens minted: ${dfTokensMinted}`);
  console.log('');

  // Step 2: Transfer dfTokens to Wallet B
  console.log(`[Step 2] Transferring ${dfTokensMinted} dfTokens to Wallet B...`);
  const transferTxHash = await transferDfTokens(
    rpcServer,
    keypair,
    walletB,
    dfTokensMinted
  );
  console.log(`  ✅ Transfer confirmed: ${transferTxHash}`);
  console.log('');

  // Summary
  console.log('='.repeat(60));
  console.log('DONE');
  console.log('='.repeat(60));
  console.log(`  Deposited:      ${DEPOSIT_AMOUNT} XLM`);
  console.log(`  dfTokens:       ${dfTokensMinted}`);
  console.log(`  Transferred to: ${walletB}`);
  console.log(`  Deposit TX:     ${depositTxHash}`);
  console.log(`  Transfer TX:    ${transferTxHash}`);
  console.log('='.repeat(60));
}

main().catch((error: unknown) => {
  console.error('Fatal error:', error);
  process.exit(1);
});

Run It

npm start

You should see output similar to:

============================================================
DeFindex: Deposit & Transfer dfTokens
============================================================
  Wallet A (depositor): GABC...
  Wallet B (receiver):  GXYZ...
  Vault:                CVAULT...
  Deposit:              10 XLM
============================================================

[Step 1] Depositing into vault...
  Building deposit via SDK...
  Signing...
  Sending deposit...
  Submitted: abc123...
  Waiting for confirmation...
  ✅ Deposit confirmed: abc123...
  dfTokens minted: 19850000

[Step 2] Transferring 19850000 dfTokens to Wallet B...
  Simulating transfer...
  Sending transfer...
  Submitted: def456...
  ✅ Transfer confirmed: def456...

============================================================
DONE
============================================================

🚨 Troubleshooting

Problem	Solution
Missing environment variables	Check that your .env file has all four variables filled in
Transaction rejected	Verify Wallet A has enough asset balance and XLM for fees
Transfer simulation failed	Confirm the vault address is correct and Wallet A holds dfTokens
Deposit returned no value	May be a network issue — check your Soroban RPC endpoint
Transaction failed on-chain	Check the transaction on Stellar Expert for details
Transaction not confirmed after 60s	The RPC node may have dropped the tx — check your Soroban RPC endpoint or retry with a higher fee

🎓 Next Steps

• Withdraw — Redeem dfTokens back for the underlying assets: Withdraw Guide

• Check Balances — Query dfToken holdings: Get Balance

• Monitor APY — Track vault performance: Get APY

• Explore the SDK — More features available in the TypeScript SDK

---

🤖 Build It with AI

Want to build this script quickly? Copy the prompt below and paste it into a new Claude Code session. It contains all the technical details needed to generate the complete implementation:

Build a TypeScript script that deposits assets into a DeFindex vault and transfers the minted
dfTokens to another wallet on the Stellar testnet.

## Technical Context

- DeFindex vaults are Soroban smart contracts on Stellar that accept asset deposits and mint
  dfTokens (vault share tokens) in return
- The vault contract itself implements the Soroban token interface, so dfTokens can be
  transferred by calling `transfer` directly on the vault contract address
- The deposit function returns a tuple where index [1] is the number of dfTokens minted (i128)

## Required Dependencies

```bash
npm install @defindex/sdk @stellar/stellar-sdk
npm install -D typescript tsx @types/node dotenv
```

Use your preferred package manager (`npm`, `yarn`, etc.). Install the latest versions.

## Environment Variables (.env)

```
DEFINDEX_API_KEY=     # DeFindex API key (sk_...)
STELLAR_SECRET_KEY=   # Wallet A secret key (depositor/signer)
RECEIVER_ADDRESS=     # Wallet B public key (receives dfTokens)
SOROBAN_RPC=your testnet soroban rpc url
```

## Implementation Requirements

Create `src/index.ts` with the following structure:

### 1. Constants
- `VAULT_ADDRESS`: The target vault contract address (user must configure)
- `DECIMALS = 7` (Stellar standard)
- `DEPOSIT_AMOUNT`: Human-readable amount, converted to raw (amount * 10^7)

### 2. `loadEnv()` function
- Load and validate all four environment variables
- Exit with error if any are missing
- Return typed config object

### 3. `sendAndConfirm(rpcServer, transaction)` helper
- Send transaction to Soroban RPC via `rpcServer.sendTransaction()`
- Check status is 'PENDING', otherwise parse error from `response.errorResult`
- Poll `rpcServer.getTransaction(hash)` every 2 seconds until SUCCESS or FAILED (max 30 polls / 60s timeout)
- On SUCCESS, return `{ txHash, returnValue }` from `GetSuccessfulTransactionResponse`

### 4. `deposit(sdk, rpcServer, keypair)` function
- Use `sdk.depositToVault(VAULT_ADDRESS, { amounts: [RAW_AMOUNT], caller, invest: true },
  SupportedNetworks.TESTNET)` to build unsigned XDR
- Parse XDR with `TransactionBuilder.fromXDR(xdr, Networks.TESTNET)`
- Sign with keypair, send via `sendAndConfirm()`
- Parse return value: `StellarSdk.scValToNative(returnValue)` returns an array,
  index [1] is dfTokens minted as bigint
- Return `{ txHash, dfTokensMinted }`

### 5. `transferDfTokens(rpcServer, keypair, toAddress, amount)` function
- Create `new Contract(VAULT_ADDRESS)` instance
- Build operation: `contract.call('transfer', Address(from).toScVal(),
  Address(to).toScVal(), nativeToScVal(amount, { type: 'i128' }))`
- Get account via `rpcServer.getAccount(from)`
- Build transaction with `TransactionBuilder`, fee `BASE_FEE`,
  network `Networks.TESTNET`, timeout 30s
- Simulate with `rpcServer.simulateTransaction(tx)`, check for errors
  with `rpc.Api.isSimulationError()`
- Assemble with `rpc.assembleTransaction(tx, simulation).build()`
- Sign and send via `sendAndConfirm()`

### 6. `main()` function
- Load env, create Keypair, rpc.Server, and DefindexSDK instances
- Step 1: Call deposit, log the deposit tx hash and dfTokens minted
- Step 2: Call transferDfTokens with the minted amount, log the transfer tx hash
- Print summary with all transaction details

## Run Script
Add `"start": "tsx src/index.ts"` to package.json scripts.

## Important Notes
- Use `Networks.TESTNET` and `SupportedNetworks.TESTNET` for testnet
- For production, switch to `Networks.PUBLIC` / `SupportedNetworks.MAINNET`
  and a mainnet RPC endpoint
- All amounts use 7 decimals (stroops)
- The vault contract address is used both for deposit (via SDK) and for the
  transfer call (as a Contract instance)
- Handle errors with try/catch — re-throw or call `process.exit(1)` on fatal errors
- Validate the deposit return shape before accessing positional indices