usdd-just-protocol

USDD / JUST Protocol

Interact with USDD, TRON's over-collateralized stablecoin, via the JUST Protocol. Swap USDT for USDD at 1:1 through the Peg Stability Module (PSM), query vault (CDP) positions and protocol parameters, and check token balances.

Quick Start

cd usdd-skill && npm install
export TRON_PRIVATE_KEY="<your-private-key>"
export TRON_NETWORK="mainnet"

[!CAUTION] Never display or log the private key.

Available Scripts

1. psm-swap.js — Buy/Sell USDT via PSM (1:1, Zero Fee)

node scripts/psm-swap.js sell 1000 --dry-run    # Preview: 1000 USDT -> 1000 USDD
node scripts/psm-swap.js sell 500                # Execute: sell 500 USDT for USDD
node scripts/psm-swap.js buy 1000 --dry-run      # Preview: spend USDD -> 1000 USDT
node scripts/psm-swap.js buy 250                 # Execute: buy 250 USDT with USDD

• sell <amount>: Sell USDT to PSM, receive USDD 1:1
• buy <amount>: Buy USDT from PSM, spend USDD 1:1
• Amount is always in USDT terms
• Auto-handles TRC20 approval
• Uses the direct buyGem/sellGem PSM interface (not the router)

[!NOTE] PSM fees (tin/tout) are currently 0%. Use psm-info.js to verify current fees.

Output: action, direction, amount_usdt, status, tx_id, needs_approval

2. psm-info.js — PSM State (Read-Only)

node scripts/psm-info.js

No private key required. Shows PSM fees (tin/tout), USDT reserves held by the GemJoin, and USDD total supply.

Output: fees (tin, tout, percentages), reserves (usdt_available), usdd (total_supply)

3. balance.js — Check Token Balances

node scripts/balance.js
node scripts/balance.js --address TXYzL2gqz5AB4dbGeiX9h8unkKHxuWwb

Queries balances for USDD, USDT, USDC, TRX, and JST. Uses --address for read-only lookups (no private key needed).

Output: wallet, balances[] (symbol, balance, address)

4. vault-info.js — Vault Positions & Parameters (Read-Only)

node scripts/vault-info.js                      # All vault types
node scripts/vault-info.js --vault TRX-A        # Specific vault type
node scripts/vault-info.js --cdp 42             # Specific CDP position

No private key required. Queries the Vat and DssCdpManager for vault parameters and individual CDP positions.

Without --cdp: shows global parameters per vault type (total debt, rate, spot price, debt ceiling, dust).

With --cdp <id>: shows a specific CDP's collateral locked, debt, and collateralization ratio.

Output (global): vaults[] (name, total_debt_usdd, rate, spot, debt_ceiling_usdd)

Output (CDP): cdp_id, owner, collateral_locked, actual_debt_usdd, collateralization_ratio

Usage Patterns

Get USDD via PSM (Simplest)

node scripts/psm-info.js                         # Check PSM reserves and fees
node scripts/psm-swap.js sell 1000 --dry-run      # Preview swap
node scripts/psm-swap.js sell 1000                # Execute: 1000 USDT -> 1000 USDD

Redeem USDD for USDT

node scripts/balance.js                           # Check USDD balance
node scripts/psm-swap.js buy 500 --dry-run        # Preview redemption
node scripts/psm-swap.js buy 500                  # Execute: spend USDD -> 500 USDT

Inspect Vault Health

node scripts/vault-info.js                        # View all vault type parameters
node scripts/vault-info.js --cdp 42               # Check specific CDP position

Supported Vaults

| Name | Collateral | GemJoin Address | Stability Fee | |---|---|---|---| | TRX-A | TRX | TJ1VWPvFVq7sVsN7J7dWJVZz4SLT14qRUr | 5% | | TRX-B | TRX | TGQKnHDQNyc3QeHJ7YxH8wggdg89UVXyvX | 5% | | TRX-C | TRX | TPUPPLTYLdbW4jxwD5g2T7ystxsR9HL2mt | 5% | | sTRX-A | sTRX | TKha7zcAXZMaaWzoVmUHtvVFqr9GeiChgJ | 1% | | USDT-A | USDT | TDUkQbjrXs6xUbxGCLknWwJHxVTdysXBhy | 0% |

Key Contracts

| Contract | Address | Description | |---|---|---| | USDD Token (v2) | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | USDD TRC20 (18 decimals) | | UsddPsm | TBXW4hS5KYjjbJXDpnrPf4zhkLwrpUjbyz | PSM — buyGem/sellGem for 1:1 swaps | | PSM GemJoin | TSUYvQ5tdd3DijCD1uGunGLpftHuSZ12sQ | PSM USDT collateral adapter (sellGem: approve USDT here) | | UsddJoin | TUajR7CbXU6hX8n3XtNkitFAD25JvP99K6 | USDD join adapter (buyGem: approve USDD here) | | DssCdpManager | TDDWjmQaquEtUn1Pa8wCd8dfWFPdQLGPYL | CDP management (open, frob, flux) | | Vat | TH5dhX7o39afSbfDT2e3c9k4itWjNKD4D9 | Core accounting engine | | USDT Token | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | USDT TRC20 (6 decimals) | | JST Token | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | JUST governance token (18 decimals) |

Security Rules

1. Never display private keys.
2. Always dry-run before PSM swaps. Verify amounts and token directions.
3. Check PSM reserves before swapping. If USDT reserves are low, buyGem may fail.
4. Decimal mismatch awareness. USDD is 18 decimals, USDT/USDC are 6. Scripts handle normalization automatically.
5. Vault positions are read-only. This skill queries but does not modify vault positions (no deposit/draw/repay/withdraw).
6. Verify CDP IDs. Always confirm the CDP ID and owner before acting on position data.

Common Issues

| Problem | Solution | |---|---| | Unknown token | Use USDD, USDT, USDC, TRX, or JST | | Insufficient balance | Check wallet balance with balance.js before swapping | | PSM swap fails | PSM may be depleted — check reserves with psm-info.js | | Unknown vault | Use TRX-A, TRX-B, TRX-C, sTRX-A, or USDT-A | | Unknown network | Set TRON_NETWORK to mainnet, nile, or shasta | | Vault shows all zeros | The ilk may not be active on this network, or the CDP ID does not exist |

Version 1.0.0 — Created by M2M Agent Registry for Bank of AI