1. Introduction

This guide is intended for smart‑contract developers, backend engineers, DevOps, security reviewers and external contributors who want to build, integrate or extend the YieldGuard on‑chain treasury‑bill aggregator. It complements the YieldGuard Architecture & White‑paper (v0.1).

1.1 Scope & Audience

Who should read – core protocol engineers, integrators, auditors.
What is covered – repository layout, local setup, contracts, off‑chain services, AI agents, deployment, observability, security, contribution.

2. Repository Overview

yieldguard/
├── contracts/
│   ├── AggregatorVault.sol
│   ├── StrategyRouter.sol
│   ├── Guard.sol
│   └── KycPass.sol
├── test/
├── scripts/
├── crons/
│   └── rebalance/
├── services/
│   ├── oracle‑watcher/
│   └── agents/
├── infra/
│   ├── terraform/
│   └── github‑workflows/
├── docs/
└── frontend/

3. Prerequisites

Rust ≥1.78 (cargo)
Node.js v20 + pnpm
Python 3.12 + Poetry
Foundry forge ≥0.2.1
Docker Desktop ≥4.30
AWS CLI v2
Arbitrum Goerli wallet funded with ETH + USDC.e

3.1 Installing Toolchain

curl -L https://foundry.paradigm.xyz | bash && foundryup
rustup target add x86_64-unknown-linux-musl

4. Smart-contract Development

4.1 Architecture Recap

AggregatorVault – ERC‑4626 receipt token yTBill; collects 30 bp streaming fee and 5 bp exit fee; upgradeable via TransparentUpgradeableProxy with 48 h timelock.
StrategyRouter – immutable logic selecting best tokenised T‑bill wrapper; issuer cap 60 %.
Guard – monitors oracles, pauses deposits.
KYC_PASS – soulbound NFT gating deposits.
Gas snapshot: deposit() 42 391 gas; withdraw() 37 555 gas; rebalance() ≤ 230 k gas.

4.2 Local Workflow

1. Clone & bootstrap

git clone git@github.com:yield‑guard/yieldguard.git
cd yieldguard
make bootstrap

2. Start Anvil fork

make anvil ARBI_RPC=$ALCHEMY_ARBI_GOERLI

3. Tests & fuzzing

forge test -vv
forge test --match-contract RebalanceInvariant

4. Deploy to fork

forge script scripts/Deploy.s.sol --fork-url http://127.0.0.1:8545 --broadcast

4.3 Coding Standards

Solidity 0.8.x with --via-ir --optimize --optimizer-runs 21000.
No inline assembly outside OZ libs.
NatSpec for public/external funcs.
Checks–Effects–Interactions order.

4.4 Security Checks

Check	Tool
Static analysis	Slither
Invariants	Forge‑std
Differential fuzz	Echidna

4.5 Upgrade Process

Implement new logic in contracts/vX/.
Run tests.
Generate diff forge inspect → audits/upgrade-report.
Propose Safe TX.
48 h timelock.
Execute with ≥3/5 signatures.

5. Off-chain Services

5.1 Rebalance Cron (Rust)

Path crons/rebalance/.
Config via AWS SSM.
Local: cargo run -- --network arbitrum-goerli --dry-run.

5.2 Oracle Watcher (Node.js)

Path services/oracle-watcher/.
Streams Chainlink aggregator events.
Auto‑pauses via Safe TX.

5.3 AI Agent Orchestrator (Python)

Poetry‑managed project in services/agents/.
Agents extend BaseAgent.
To add an agent:

class MyNewAgent(BaseAgent):
    name = 'LpForecaster'
    schema = MySchema

6. Data & Indexing

TheGraph subgraph at subgraph.yaml.
Local: graph dev --network arbitrum-goerli.

7. Frontend dApp

Next.js 14 + wagmi v2.
Env vars: NEXT_PUBLIC_VAULT_ADDRESS, NEXT_PUBLIC_GRAPH_URL.
Start: pnpm dev.

8. CI/CD

GitHub Actions in .github/workflows/.
On tag release vX.Y.Z builds docker images and contracts artifacts.

9. Infrastructure

YieldGuard runs exclusively on Amazon Web Services (AWS) across three isolated accounts—production, staging, and security‑ops—governed by AWS Organizations and Service Control Policies (SCPs).

9.1 Reference Architecture

Layer	AWS Services	Notes
Networking	VPC (3 AZs), Public + Private Subnets, AWS Transit Gateway	VPC Flow Logs shipped to S3; IPv6 dual‑stack on the 2025 roadmap.
Containers	Amazon EKS (Kubernetes 1.30), AWS Fargate	Control plane isolated in private subnets; Karpenter for cost‑efficient autoscaling.
Data	Amazon RDS PostgreSQL 15 (subgraph indexer), Amazon S3 (logs & artifacts)	RDS Multi‑AZ, encrypted with customer‑managed KMS keys.
Serverless	AWS Lambda (rebalance cron), Amazon EventBridge Scheduler	Lambdas written in Rust (via `lambda_http` crate).
Messaging	Amazon SQS (agent orchestration), Amazon SNS (alert fan‑out)	FIFO queues guarantee ordered oracle events.
Secrets & Config	AWS Secrets Manager, AWS SSM Parameter Store	Automated rotation every 30 days using Lambda + KMS.
Edge	Amazon Route 53, AWS CloudFront, S3 (static dApp hosting)	CloudFront Functions for lightweight auth header injection.
Monitoring	Amazon CloudWatch, AWS X‑Ray	Logs and metrics forwarded to Grafana Cloud via Grafana Agent sidecars.
Security	IAM Roles & Policies, AWS KMS, AWS Shield Advanced	Access managed by IAM Identity Center (SAML SSO); Shield Advanced enabled on CloudFront distro.

9.2 Deployment Flow

GitHub Action builds & pushes Docker images to ECR on every SemVer tag.
Argo CD (deployed in the staging account) tracks the helm/ directory and syncs manifests to EKS clusters.
Terraform Cloud applies infrastructure changes after manual approval in the security‑ops account.
GitHub runners assume a cross‑account OIDC role (arn:aws:iam:::role/GithubDeploy) with least‑privilege permissions.

9.3 Disaster-Recovery & Backups

RDS automated backups kept for 30 days; snapshots replicated nightly to eu‑west‑2.
S3 buckets are versioned with replication to secondary region; Lifecycle rules transition to Glacier after 90 days.
Infrastructure‑as‑Code (Terraform) and Helm files stored in Git; cold redeploy time < 60 minutes.

10. Observability & Incident Response

Prometheus metrics, Grafana dashboards, PagerDuty hooks.
War‑room runbook: triage 15 min, public update 30 min, mitigation 2 h.

11. Contribution Guidelines

Fork → feature branch → PR to develop.
PR template requires tests + gas diff.

12. Glossary

Term	Definition
NAV (Net Asset Value)	Real‑time value of all vault assets minus liabilities, denominated in USDC.e.
TVL (Total Value Locked)	Aggregate dollar value of assets deposited in YieldGuard contracts.
PoR (Proof of Reserve)	Cryptographic and accounting process confirming off‑chain T‑Bill tokens backing on‑chain tokens.
RAIF (Restricted Alternative Investment Fund)	Luxembourg‑domiciled fund structure that legally holds the underlying Treasury Bills.
APR / APY	Annual Percentage Rate / Yield – standardised return metrics; APY includes compounding.
Basis Points (bp)	One‑hundredth of a percent (0.01 %). Fees expressed as bp, e.g., 30 bp = 0.30 %.
ERC‑4626	Ethereum tokenised vault standard defining deposit/withdraw interfaces and share accounting.
T‑Bill	U.S. Treasury Bills – short‑term government debt maturing < 1 year.
Safe (Gnosis Safe)	Multisig smart‑contract wallet controlling upgrades, pausing and treasury movements.
Upgradable Proxy	Pattern splitting storage proxy from logic contract, enabling post‑deployment upgrades.
Timelock	Delay contract enforcing a waiting period (48 h) before queued admin actions execute.
Oracle	Data feed (Chainlink) delivering off‑chain market prices and T‑Bill yields on‑chain.
L2 / Rollup	Layer‑2 scaling network (e.g., Arbitrum) bundling transactions and posting proofs to Ethereum.
Anvil	Foundry local EVM node; supports forking mainnet and deterministic testing.
Fuzzing	Property‑based testing generating random inputs to find failing invariants or reverts.
Invariant Testing	Verification style ensuring certain conditions (e.g., vault shares ≥ assets) always hold.
Subgraph	TheGraph indexer providing GraphQL API for querying on‑chain events and states.
Soulbound NFT	Non‑transferable NFT (KYC_PASS) proving whitelisted investor status.
Rebalance	Moving assets between T‑Bill wrappers to optimise yield or manage issuer caps.
Liquidity	Capacity to deposit/withdraw without significant slippage or delay.

14. Key Contract Interfaces

See .env.example in repo.

14.1 AggregatorVault.sol (ERC-4626)

Function	Selector	Visibility	Description
`deposit(uint256 assets, address receiver)`	`0xb6b55f25`	external	Mints shares for receiver by transferring assets (USDC.e) from `msg.sender`. Emits Deposit.
`mint(uint256 shares, address receiver)`	`0xea12d0c7`	external	Variant that targets share amount instead of asset amount.
`withdraw(uint256 assets, address receiver, address owner)`	`0x2e1a7d4d`	external	Burns shares from owner and transfers assets to receiver.
`redeem(uint256 shares, address receiver, address owner)`	`0xdb006a75`	external	Burns shares and returns proportional assets to receiver.
`rebalance()`	`0xe0c4399a`	external (EOA/cron only)	Moves idle USDC.e into StrategyRouter‑selected wrapper.

14.2 StrategyRouter.sol

Function	Description
`selectBestWrapper()`	Returns address of wrapper with highest after‑fee yield and available capacity.
`capForIssuer(address issuer)`	View limiting exposure per issuing SPV.

Full NatSpec‑generated HTML is available under /docs/natspec/ after make docs.

15. Running a Full Local Stack

A reproducible dev stack is provided under docker-compose.yml.

docker compose -f infra/docker-compose.dev.yaml up

Container	Port	Purpose
`anvil`	8545	Local forked EVM
`subgraph`	8000	GraphQL API + playground
`grafana`	3000	Dashboards (`admin/admin`)
`prometheus`	9090	Metrics

> Tip: Preload USDC.e into dev accounts with scripts/fund-dev.ts.

16. Example GraphQL Queries

Latest TVL

{
  vault(id: "0x...") {
    tvl
    apr
    totalUsers
  }
}

Deposits by user

{
  deposits(first: 10, where:{user:"0xYourAddress"}) {
    amount
    txHash
    blockTime
  }
}

17. CI/CD Pipeline Example

.github/workflows/ci.yml

name: Contracts CI
on:
  pull_request:
    paths:
      - 'contracts/**'
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: foundry-rs/setup@v1
      - run: forge test -vv
  slither:
    runs-on: ubuntu-latest
    container: crytic/slither:0.10.0
    steps:
      - uses: actions/checkout@v4
      - run: slither .

18. Complete Env Vars Reference

Var	Default	Description
`ARBI_RPC`	–	Arbitrum Goerli RPC endpoint.
`PRIVATE_KEY`	–	Deployer key for forge scripts.
`SUBGRAPH_DB_USER`	`graph`	Postgres username for TheGraph indexer.
`SUBGRAPH_DB_PASS`	`graph`	Postgres password.
`PROM_ALERT_WEBHOOK`	–	PagerDuty webhook for critical alerts.
`NEXT_PUBLIC_VAULT_ADDRESS`	–	Deployed AggregatorVault address injected into dApp.
`NEXT_PUBLIC_GRAPH_URL`	`http://localhost:8000/subgraphs/name/yieldguard`	Subgraph URL for local dev.

> Note: Each service has an .env.example with additional variables.