> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Shield

> Zero-trust transaction validation for Yield.xyz integrations

## Overview

When interacting with on-chain yield protocols through the Yield API, transaction integrity is critical. Even a small modification can redirect funds or trigger unintended contract calls.

**Shield** is a lightweight validation library that lets you verify unsigned transactions from the Yield API before presenting them for signing. It's designed to be embedded directly into your integration — giving you full control over when and how validation occurs.

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/yieldxyz/shield">
    View source code
  </Card>

  <Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@yieldxyz/shield">
    Install via npm
  </Card>
</CardGroup>

***

## Key Features

<CardGroup cols={2}>
  <Card title="Zero-trust verification" icon="shield-check">
    Every transaction must match a pre-audited pattern
  </Card>

  <Card title="Multi-chain support" icon="link">
    Works across EVM, Solana, and Tron (Cosmos and other L2s coming soon)
  </Card>

  <Card title="Easy to integrate" icon="plug">
    Add one validation call before your signing logic — no extra middleware required
  </Card>

  <Card title="Clear error reporting" icon="triangle-exclamation">
    Immediate feedback on invalid or ambiguous transactions
  </Card>
</CardGroup>

***

## Installation

```bash theme={null}
npm install @yieldxyz/shield
```

***

## Usage Example

```typescript theme={null}
import { Shield } from '@yieldxyz/shield';
const shield = new Shield();

// 1. 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,
  },
  body: JSON.stringify({
    yieldId: 'ethereum-eth-lido-staking',
    address: userWalletAddress,
    arguments: { amount: '0.01' },
  }),
});

const action = await response.json();

// 2. Validate each transaction before signing
for (const tx of action.transactions) {
  const result = shield.validate({
    unsignedTransaction: tx.unsignedTransaction,
    yieldId: action.yieldId,
    userAddress: userWalletAddress,
  });

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

// 3. Proceed with signing
```

***

## How It Works

Shield uses **pattern matching** to analyze each transaction's structure, function calls, and parameters, validating them against a verified template for the specified yield integration.

If the transaction doesn't match the safe pattern — for example, if an attacker modified a withdrawal address — Shield immediately flags it:

```
Invalid transaction: Withdrawal owner does not match user address
```

You can decide how to handle the result: block the signing flow, display a warning, or log it for review.

***

## Supported Yield Integrations

| Chain    | Yield ID                                   | Description        |
| -------- | ------------------------------------------ | ------------------ |
| Ethereum | `ethereum-eth-lido-staking`                | Lido ETH staking   |
| Solana   | `solana-sol-native-multivalidator-staking` | Native SOL staking |
| Tron     | `tron-trx-native-staking`                  | TRX native staking |

<Info>
  More integrations (Cosmos, Polkadot, Bittensor, additional EVM yields) are being continuously added.
</Info>

Check programmatically:

```typescript theme={null}
shield.getSupportedYieldIds();
```

***

## API Reference

### shield.validate(request)

Validates a transaction by auto-detecting its type.

**Parameters:**

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

**Returns:**

```typescript theme={null}
{
  isValid: boolean;
  reason?: string;         // Why validation failed
  details?: any;           // Additional error info
  detectedType?: string;   // Auto-detected transaction type (for debugging)
}
```

### shield.isSupported(yieldId: string): boolean

Checks whether a given yield integration is supported.

### shield.getSupportedYieldIds(): string\[]

Returns a list of all supported Yield IDs.

***

## Common Validation Errors

| Context           | Error Message                                         | Meaning                                                                              |
| ----------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Solana            | `Transfer recipient does not match new stake account` | Your SOL is being sent to a different wallet instead of the intended stake account   |
| Solana            | `Delegate authority is not user address`              | Someone else would gain control over your staked SOL                                 |
| EVM / Ethereum    | `Transaction not to Lido stETH contract`              | The transaction targets a fake contract attempting to steal your ETH                 |
| Pattern Detection | `No matching operation pattern found`                 | The transaction type doesn't match any valid pattern — likely malicious or corrupted |

***

## Decoding & Visualization

Shield allows clients to locally decode and visualize unsigned transactions before signing or broadcasting them.

This feature enhances transparency and compliance by letting integrators inspect every on-chain instruction — including target addresses, function calls, and parameter values — directly on their own systems.

### How It Works

<Steps>
  <Step title="Retrieve transaction">
    Get an unsigned transaction from the Yield API (e.g., `/v1/actions/enter` or `/v1/actions/exit`)
  </Step>

  <Step title="Decode locally">
    Pass the transaction into Shield's `decode()` method
  </Step>

  <Step title="Inspect results">
    Shield returns a structured, human-readable view including target contract, function/method, parameters, token amounts, and associated accounts
  </Step>
</Steps>

### Why It Matters

* **Transparency**: Visually confirm every on-chain call before user signing
* **Security**: Reduces man-in-the-middle or tampering attacks by verifying locally
* **Compliance**: Log decoded transactions for audit trails or regulator review
* **Zero Trust**: Decoding occurs entirely client-side — no external API calls needed

***

## Shield — Go Package

For institutional and high-security deployments, Shield is also available as a **Go package** designed for hardware-secure, compiled environments (e.g., secure enclaves, HSMs, air-gapped systems) where TypeScript cannot be executed.

Shield Go provides the same validation and decoding functionality as the TypeScript package.

### Capability Comparison

| Capability                                 | Shield TypeScript | Shield Go |
| ------------------------------------------ | ----------------- | --------- |
| Transaction validation                     | ✅                 | ✅         |
| Local transaction decoding                 | ✅                 | ✅         |
| Multi-chain support (EVM, Solana, Tron)    | ✅                 | ✅         |
| Secure enclave compatibility               | ⚠️ Limited        | ✅ Full    |
| Embeddable in hardware / compiled binaries | ❌                 | ✅         |
| CLI / SDK usage                            | ✅                 | ✅         |

***

## Why Shield Matters

Each API layer in a DeFi integration increases potential attack surfaces. Shield enforces a **zero-trust model**, guaranteeing that the transaction users sign is exactly the one intended by Yield.xyz.

By validating before signing, you:

* **Prevent tampering** and phishing attempts
* **Maintain user trust** through transparency
* **Add structural security** without sacrificing UX

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Security Overview" icon="shield" href="/documentation/shield-security/security-overview">
    Full security architecture
  </Card>

  <Card title="HyperNative" icon="bolt" href="/documentation/shield-security/hypernative">
    Pre-transaction simulation
  </Card>

  <Card title="Security Tiers" icon="layer-group" href="/documentation/shield-security/security-tiers">
    Deployment models
  </Card>

  <Card title="Quickstart" icon="rocket" href="/documentation/quickstart">
    Integrate Shield into your app
  </Card>
</CardGroup>