{"id":43931745,"url":"https://github.com/stakekit/shield","last_synced_at":"2026-04-02T20:53:05.697Z","repository":{"id":318714924,"uuid":"1072946862","full_name":"stakekit/shield","owner":"stakekit","description":"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.","archived":false,"fork":false,"pushed_at":"2026-04-01T02:24:44.000Z","size":428,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T04:56:36.366Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://yield.xyz/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stakekit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-09T12:31:15.000Z","updated_at":"2026-04-01T02:23:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"5fcd011d-3c17-4ba2-a5b4-c92047dd6253","html_url":"https://github.com/stakekit/shield","commit_stats":null,"previous_names":["stakekit/shield"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/stakekit/shield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakekit%2Fshield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakekit%2Fshield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakekit%2Fshield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakekit%2Fshield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stakekit","download_url":"https://codeload.github.com/stakekit/shield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stakekit%2Fshield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31316008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-07T00:12:08.625Z","updated_at":"2026-04-02T20:53:05.691Z","avatar_url":"https://github.com/stakekit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ @yieldxyz/shield\n\n\u003cdiv align=\"center\"\u003e\n\n[![CI](https://github.com/stakekit/shield/actions/workflows/ci.yml/badge.svg)](https://github.com/stakekit/shield/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@yieldxyz/shield.svg)](https://www.npmjs.com/package/@yieldxyz/shield)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003c/div\u003e\n\n\u003e Zero-trust transaction validation for Yield.xyz integrations. Shield ensures every transaction is structurally correct and untampered before signing.\n\n## Installation\n\n### For TypeScript/JavaScript Projects\n\n```bash\nnpm install @yieldxyz/shield\n```\n\n### For Other Languages (Standalone Binary)\n\nDownload the pre-built binary for your platform from [GitHub Releases](https://github.com/stakekit/shield/releases):\n\n| Platform              | Download                 |\n| --------------------- | ------------------------ |\n| Linux (x64)           | `shield-linux-x64`       |\n| macOS (Apple Silicon) | `shield-darwin-arm64`    |\n| macOS (Intel)         | `shield-darwin-x64`      |\n| Windows               | `shield-windows-x64.exe` |\n\n```bash\n# Example: Download for macOS Apple Silicon\ncurl -L https://github.com/stakekit/shield/releases/latest/download/shield-darwin-arm64 -o shield\nchmod +x shield\n\n# Verify integrity (recommended)\ncurl -LO https://github.com/stakekit/shield/releases/latest/download/shield-darwin-arm64.sha256\nshasum -a 256 -c shield-darwin-arm64.sha256\n# Expected output: shield-darwin-arm64: OK\n```\n\nSee the [examples/](./examples/) directory for complete integration examples in Python, Go, and Rust.\n\n## Usage\n\n```typescript\nimport { Shield } from '@yieldxyz/shield';\n\nconst shield = new Shield();\n\n// Get transaction from Yield API\nconst response = await fetch('https://api.yield.xyz/v1/actions/enter', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'X-API-Key': process.env.YIELD_API_KEY, // Your API key\n  },\n  body: JSON.stringify({\n    yieldId: 'ethereum-eth-lido-staking',\n    address: userWalletAddress,\n    arguments: { amount: '0.01' },\n  }),\n});\n\nconst action = await response.json();\n\n// Validate before signing\nfor (const transaction of action.transactions) {\n  const result = shield.validate({\n    unsignedTransaction: transaction.unsignedTransaction,\n    yieldId: action.yieldId,\n    userAddress: userWalletAddress,\n    args: action.arguments, // Optional\n  });\n\n  if (!result.isValid) {\n    throw new Error(`Invalid transaction: ${result.reason}`);\n  }\n}\n```\n\n## How It Works\n\nShield automatically detects and validates transaction types through pattern matching. Each transaction must match exactly one known pattern to be considered valid.\n\n## Using Shield from Other Languages\n\nShield is written in TypeScript, but can be used from **any programming language** via its CLI (Command Line Interface).\n\n### Why Two Approaches?\n\n| Your Language                      | How to Use Shield                                 |\n| ---------------------------------- | ------------------------------------------------- |\n| TypeScript/JavaScript              | Import the library directly (see [Usage](#usage)) |\n| Python, Go, Ruby, Rust, Java, etc. | Use the CLI via subprocess                        |\n\nThe CLI approach means you get the **exact same validation logic** without rewriting Shield in your language.\n\n### The JSON Protocol\n\nThe CLI reads JSON from stdin and writes JSON to stdout:\n\n**Input:**\n\n```json\n{\n  \"apiVersion\": \"1.0\",\n  \"operation\": \"validate\",\n  \"yieldId\": \"ethereum-eth-lido-staking\",\n  \"unsignedTransaction\": \"{\\\"to\\\":\\\"0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84\\\",...}\",\n  \"userAddress\": \"0x742d35cc6634c0532925a3b844bc9e7595f0beb8\"\n}\n```\n\n**Output:**\n\n```json\n{\n  \"ok\": true,\n  \"apiVersion\": \"1.0\",\n  \"result\": {\n    \"isValid\": true,\n    \"detectedType\": \"STAKE\"\n  },\n  \"meta\": {\n    \"requestHash\": \"a1b2c3...\"\n  }\n}\n```\n\n### Operations\n\n| Operation              | Required Fields                                 | Description                   |\n| ---------------------- | ----------------------------------------------- | ----------------------------- |\n| `validate`             | `yieldId`, `unsignedTransaction`, `userAddress` | Validate a transaction        |\n| `isSupported`          | `yieldId`                                       | Check if a yield is supported |\n| `getSupportedYieldIds` | (none)                                          | List all supported yields     |\n\n### CLI Examples (Bash)\n\n```bash\n# Check if a yield is supported\necho '{\"apiVersion\":\"1.0\",\"operation\":\"isSupported\",\"yieldId\":\"ethereum-eth-lido-staking\"}' | npx @yieldxyz/shield\n\n# Validate a transaction\necho '{\"apiVersion\":\"1.0\",\"operation\":\"validate\",\"yieldId\":\"ethereum-eth-lido-staking\",\"unsignedTransaction\":\"{...}\",\"userAddress\":\"0x...\"}' | npx @yieldxyz/shield\n\n\n# List supported yields\necho '{\"apiVersion\":\"1.0\",\"operation\":\"getSupportedYieldIds\"}' | npx @yieldxyz/shield\n```\n\n## Supported Yield IDs\n\n- `ethereum-eth-lido-staking`\n- `solana-sol-native-multivalidator-staking`\n- `tron-trx-native-staking`\n- All generic ERC4626 vault yields from: Angle, Curve, Euler, Fluid, Gearbox, Idle Finance, Lista, Morpho, Sky, SummerFi, Venus Flux, Yearn, Yo Protocol\n\nTo see the full list:\n\n```bash\necho '{\"apiVersion\":\"1.0\",\"operation\":\"getSupportedYieldIds\"}' | npx @yieldxyz/shield\n```\n\n\u003e **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.\n\n### ERC4626 Vault Operations\n\nShield validates the following operations for all supported ERC4626 vaults:\n\n| Operation   | Transaction Type | Description                                   |\n| ----------- | ---------------- | --------------------------------------------- |\n| Approve     | APPROVAL         | ERC20 token approval for vault deposit        |\n| Deposit     | SUPPLY           | Deposit assets into vault                     |\n| Mint        | SUPPLY           | Mint vault shares                             |\n| Withdraw    | WITHDRAW         | Withdraw assets from vault                    |\n| Redeem      | WITHDRAW         | Redeem vault shares                           |\n| WETH Wrap   | WRAP             | Convert native ETH to WETH (WETH vaults only) |\n| WETH Unwrap | UNWRAP           | Convert WETH to native ETH (WETH vaults only) |\n\n## API Reference\n\n### `shield.validate(request)`\n\nValidates a transaction by auto-detecting its type.\n\n**Parameters:**\n\n```typescript\n{\n  unsignedTransaction: string;  // Transaction from Yield API\n  yieldId: string;              // Yield integration ID\n  userAddress: string;          // User's wallet address\n  args?: ActionArguments;       // Optional arguments\n  context?: ValidationContext;  // Optional context\n}\n```\n\n**Returns:**\n\n```typescript\n{\n  isValid: boolean;\n  reason?: string;         // Why validation failed\n  details?: any;          // Additional error details\n  detectedType?: string;  // Auto-detected type (for debugging)\n}\n```\n\n### `shield.isSupported(yieldId)`\n\nCheck if a yield is supported.\n\n### `shield.getSupportedYieldIds()`\n\nGet all supported yield IDs.\n\n## Error Messages\n\nCommon validation failures:\n\n- `\"Invalid referral address\"` - Wrong referral in transaction\n- `\"Withdrawal owner does not match user address\"` - Ownership mismatch\n- `\"Transaction validation failed: No matching operation pattern found\"` - Transaction doesn't match any supported pattern\n- `\"Transaction validation failed: Ambiguous transaction pattern detected\"` - Transaction matches multiple patterns\n\n## Security\n\nShield is designed with security as a top priority:\n\n- **Input Validation**: All inputs are validated against strict JSON schemas with size limits (100KB max)\n- **Pattern Matching**: Transactions must match exactly one known pattern to be valid\n- **No Network Access**: The CLI binary has no network capabilities - it only reads stdin and writes stdout\n- **Checksum Verification**: All release binaries include SHA256 checksums for integrity verification\n\n### Embedded Vault Registry\n\nERC4626 vault data is embedded in the package at build time from `vault-registry.json`. The registry includes allocator vault (OAV) addresses for yields with fee configurations. Transactions targeting allocator vaults are validated using the same ERC4626 standard.\n\n### Verifying Binary Integrity\n\nAlways verify downloaded binaries:\n\n```bash\n# Download binary and checksum\ncurl -LO https://github.com/stakekit/shield/releases/latest/download/shield-darwin-arm64\ncurl -LO https://github.com/stakekit/shield/releases/latest/download/shield-darwin-arm64.sha256\n\n# Verify\nshasum -a 256 -c shield-darwin-arm64.sha256\n# Expected: shield-darwin-arm64: OK\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstakekit%2Fshield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstakekit%2Fshield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstakekit%2Fshield/lists"}