Skip to content
BranchesTags

Repository files navigation

🛡️ @yieldxyz/shield

CI npm version License: MIT

Zero-trust transaction validation for Yield.xyz integrations. Shield ensures every transaction is structurally correct and untampered before signing.

Installation

For TypeScript/JavaScript Projects

npm install @yieldxyz/shield

For Other Languages (Standalone Binary)

Download the pre-built binary for your platform from GitHub Releases:

Platform Download
Linux (x64) shield-linux-x64
macOS (Apple Silicon) shield-darwin-arm64
macOS (Intel) shield-darwin-x64
Windows shield-windows-x64.exe 
# Example: Download for macOS Apple Silicon
curl -L https://github.com/stakekit/shield/releases/latest/download/shield-darwin-arm64 -o shield
chmod +x shield

# Verify integrity (recommended)
curl -LO https://github.com/stakekit/shield/releases/latest/download/shield-darwin-arm64.sha256
shasum -a 256 -c shield-darwin-arm64.sha256
# Expected output: shield-darwin-arm64: OK

See the examples/ directory for complete integration examples in Python, Go, and Rust.

Usage

import { Shield } from '@yieldxyz/shield';

const shield = new Shield();

// Parameters controlled by the caller. Keeping them in variables lets us
// use the same values for the request and, later, for validation.
const yieldId = 'ethereum-eth-lido-staking';
const userWalletAddress = '0x742d35cc6634c0532925a3b844bc9e7595f0beb8';
const args = { amount: '0.01' };

// Get transaction from Yield API
const response = await fetch('https://api.yield.xyz/v1/actions/enter', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.YIELD_API_KEY, // Your API key
  },
  body: JSON.stringify({
    yieldId,
    address: userWalletAddress,
    arguments: args,
  }),
});

const action = await response.json();

// Validate before signing.
//
// Note: only `transaction.unsignedTransaction` should come from the API
// response. The other fields — yieldId, userAddress, args — should be the
// values you sent in the request, since the goal is to check the API's
// transaction against what you actually asked for.
for (const transaction of action.transactions) {
  const result = shield.validate({
    unsignedTransaction: transaction.unsignedTransaction,
    yieldId,
    userAddress: userWalletAddress,
    args, // Optional
  });

  if (!result.isValid) {
    throw new Error(`Invalid transaction: ${result.reason}`);
  }
}

How It Works

Shield automatically detects and validates transaction types through pattern matching. Each transaction must match exactly one known pattern to be considered valid.

Using Shield from Other Languages

Shield is written in TypeScript, but can be used from any programming language via its CLI (Command Line Interface).

Why Two Approaches?

Your Language How to Use Shield
TypeScript/JavaScript Import the library directly (see Usage)
Python, Go, Ruby, Rust, Java, etc. Use the CLI via subprocess

The CLI approach means you get the exact same validation logic without rewriting Shield in your language.

The JSON Protocol

The CLI reads JSON from stdin and writes JSON to stdout:

Input:

{
  "apiVersion": "1.0",
  "operation": "validate",
  "yieldId": "ethereum-eth-lido-staking",
  "unsignedTransaction": "{\"to\":\"0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84\",...}",
  "userAddress": "0x742d35cc6634c0532925a3b844bc9e7595f0beb8"
}

Output:

{
  "ok": true,
  "apiVersion": "1.0",
  "result": {
    "isValid": true,
    "detectedType": "STAKE"
  },
  "meta": {
    "requestHash": "a1b2c3..."
  }
}

Operations

Operation Required Fields Description
validate yieldId, unsignedTransaction, userAddress Validate a transaction
isSupported yieldId Check if a yield is supported
getSupportedYieldIds (none) List all supported yields

CLI Examples (Bash)

# Check if a yield is supported
echo '{"apiVersion":"1.0","operation":"isSupported","yieldId":"ethereum-eth-lido-staking"}' | npx @yieldxyz/shield

# Validate a transaction
echo '{"apiVersion":"1.0","operation":"validate","yieldId":"ethereum-eth-lido-staking","unsignedTransaction":"{...}","userAddress":"0x..."}' | npx @yieldxyz/shield


# List supported yields
echo '{"apiVersion":"1.0","operation":"getSupportedYieldIds"}' | npx @yieldxyz/shield

Supported Yield IDs

  • ethereum-eth-lido-staking
  • solana-sol-native-multivalidator-staking
  • tron-trx-native-staking
  • All generic ERC4626 vault yields from: Angle, Curve, Euler, Fluid, Gearbox, Idle Finance, Lista, Morpho, Sky, SummerFi, Venus Flux, Yearn, Yo Protocol

To see the full list:

echo '{"apiVersion":"1.0","operation":"getSupportedYieldIds"}' | npx @yieldxyz/shield

Note: Aave, Maple, Spark use non-standard transaction flows and are not yet supported. Protocol-specific validators for these will be added in a future release.

ERC4626 Vault Operations

Shield validates the following operations for all supported ERC4626 vaults:

Operation Transaction Type Description
Approve APPROVAL ERC20 token approval for vault deposit
Deposit SUPPLY Deposit assets into vault
Mint SUPPLY Mint vault shares
Withdraw WITHDRAW Withdraw assets from vault
Redeem WITHDRAW Redeem vault shares
WETH Wrap WRAP Convert native ETH to WETH (WETH vaults only)
WETH Unwrap UNWRAP Convert WETH to native ETH (WETH vaults only)

Amount intent (args) — ERC-4626 enter & exit

Amount checks are opt-in. If you omit args.amount / args.shareAmount, Shield runs only structural checks (vault whitelist, owner/receiver, method, non-zero).

Units: pass base-unit integer strings (wei) only — the same scale as calldata. Human values like "0.01" are rejected.

Calldata Pass to Shield Match rule
deposit / approve / WRAP args.amount (asset wei) Exact
withdraw(assets, …) args.amount (asset wei) Within 10 wei (monorepo near-max snap)
redeem(shares, …) args.shareAmount (share wei) Within margin (see below)

Do not declare both amount and shareAmount. Do not pass asset amount on a redeem, or shareAmount on a withdraw (fail-closed).

Match the built tx, not only what you sent the Yield API:

Yield API exit Typical calldata Shield args
amount with withdraw-on-amount (team flag off) withdraw(assets) amount = asset wei
shareAmount / shareAmountRaw redeem(shares) shareAmount = share wei
useMaxAmount: true redeem(maxRedeem) shareAmount from balances shareAmountRaw, or omit intent 
// Partial exit — withdraw(assets)
shield.validate({
  unsignedTransaction,
  yieldId,
  userAddress,
  args: { amount: '1000000' }, // 1 USDC @ 6 decimals, wei
});

// Share exit — redeem(shares)
shield.validate({
  unsignedTransaction,
  yieldId,
  userAddress,
  args: { shareAmount: '1000000000000000000' }, // 1 share @ 18 decimals
});

// Full exit (useMaxAmount) — redeem; declare the share balance, not an asset amount
shield.validate({
  unsignedTransaction,
  yieldId,
  userAddress,
  args: { shareAmount: balance.shareAmountRaw },
});

Redeem margin

  • Default / underlying vault: "10" share wei.
  • Allocator / OAV target (tx.to in the registry's allocatorVaults): decimal-gap margin 10^(abs(inputDecimals − vaultDecimals) + 1) — e.g. USDC 6 vs shares 18 → 10^13 — except a small hardcoded set of OAVs that stay at "10" for parity with the Yield API exit path.

API Reference

shield.validate(request)

Validates a transaction by auto-detecting its type.

Parameters:

{
  unsignedTransaction: string;  // Transaction from Yield API
  yieldId: string;              // Yield integration ID
  userAddress: string;          // User's wallet address
  args?: ActionArguments;       // Optional arguments
  context?: ValidationContext;  // Optional context
}

Returns:

{
  isValid: boolean;
  reason?: string;         // Why validation failed
  details?: any;          // Additional error details
  detectedType?: string;  // Auto-detected type (for debugging)
}

shield.isSupported(yieldId)

Check if a yield is supported.

shield.getSupportedYieldIds()

Get all supported yield IDs.

Error Messages

Common validation failures:

  • "Invalid referral address" - Wrong referral in transaction
  • "Withdrawal owner does not match user address" - Ownership mismatch
  • "Transaction validation failed: No matching operation pattern found" - Transaction doesn't match any supported pattern
  • "Transaction validation failed: Ambiguous transaction pattern detected" - Transaction matches multiple patterns

Security

Shield is designed with security as a top priority:

  • Input Validation: All inputs are validated against strict JSON schemas with size limits (100KB max)
  • Pattern Matching: Transactions must match exactly one known pattern to be valid
  • No Network Access: The CLI binary has no network capabilities - it only reads stdin and writes stdout
  • Checksum Verification: All release binaries include SHA256 checksums for integrity verification

Embedded Vault Registry

ERC-4626 vault data is embedded at build time from vault-registry.json (addresses, token decimals, and allocatorVaults). Transactions to known allocator vaults use the same ERC-4626 checks. Newly deployed OAVs are only recognized after a registry re-export and package publish.

Verifying Binary Integrity

Always verify downloaded binaries:

# Download binary and checksum
curl -LO https://github.com/stakekit/shield/releases/latest/download/shield-darwin-arm64
curl -LO https://github.com/stakekit/shield/releases/latest/download/shield-darwin-arm64.sha256

# Verify
shasum -a 256 -c shield-darwin-arm64.sha256
# Expected: shield-darwin-arm64: OK

License

MIT

About

Shield is a zero trust transaction validation library built for Yield.xyz integrations. It ensures that every transaction generated by the Yield API is structurally correct, safe, and untampered before being signed or broadcast, protecting users, partners, and SDKs from invalid or malicious transaction data.

yield.xyz/

Resources

Readme
MIT license
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Used by

Contributors

Languages