|
| 1 | +--- |
| 2 | +title: "Blockchain Wallet Setup" |
| 3 | +description: "Set up an Ethereum wallet and fund it with testnet ETH for dstack deployment" |
| 4 | +section: "Prerequisites" |
| 5 | +stepNumber: 5 |
| 6 | +totalSteps: 7 |
| 7 | +lastUpdated: 2026-01-09 |
| 8 | +prerequisites: [] |
| 9 | +tags: |
| 10 | + - blockchain |
| 11 | + - ethereum |
| 12 | + - wallet |
| 13 | + - testnet |
| 14 | + - sepolia |
| 15 | +difficulty: intermediate |
| 16 | +estimatedTime: 15-20 minutes |
| 17 | +--- |
| 18 | + |
| 19 | +# Blockchain Wallet Setup |
| 20 | + |
| 21 | +dstack's Key Management Service (KMS) is deployed as a smart contract on the Ethereum blockchain. For tutorial purposes, we'll use the **Sepolia testnet**, which allows you to deploy and test without spending real ETH. |
| 22 | + |
| 23 | +## What You'll Need |
| 24 | + |
| 25 | +- **Ethereum wallet** with a private key |
| 26 | +- **Testnet ETH** (~0.1 ETH minimum for deployment) |
| 27 | + |
| 28 | +## Why Sepolia? |
| 29 | + |
| 30 | +Sepolia is one of Ethereum's official testnets: |
| 31 | + |
| 32 | +- Free testnet ETH from faucets |
| 33 | +- Similar to mainnet but without real value |
| 34 | +- Perfect for development and testing |
| 35 | +- Widely supported by tools and services |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +## Option 1: Command-Line Wallet (Recommended) |
| 40 | + |
| 41 | +If you have [Foundry](https://book.getfoundry.sh/getting-started/installation) installed, you can create a wallet using the `cast` command. |
| 42 | + |
| 43 | +### Step 1.1: Check if Foundry is Installed |
| 44 | + |
| 45 | +```bash |
| 46 | +cast --version |
| 47 | +``` |
| 48 | + |
| 49 | +If not installed, see: https://book.getfoundry.sh/getting-started/installation |
| 50 | + |
| 51 | +### Step 1.2: Generate New Wallet |
| 52 | + |
| 53 | +```bash |
| 54 | +cast wallet new |
| 55 | +``` |
| 56 | + |
| 57 | +**Example output:** |
| 58 | + |
| 59 | +``` |
| 60 | +Successfully created new keypair. |
| 61 | +Address: 0x91Ba69FCD13D2876FD06907a2880BDBC93C336aF |
| 62 | +Private key: 0xd76e8d3059484d5d9167c4e10cfeea2a4efa655875112e693e18fb4ab890b98a |
| 63 | +``` |
| 64 | + |
| 65 | +⚠️ **Save these immediately:** |
| 66 | + |
| 67 | +- **Address:** Your public wallet address (safe to share) |
| 68 | +- **Private Key:** SECRET - never share or commit to git |
| 69 | + |
| 70 | +### Step 1.3: Store Wallet Credentials Securely |
| 71 | + |
| 72 | +Create secure files to store your wallet address and private key: |
| 73 | + |
| 74 | +```bash |
| 75 | +# Create secure directory |
| 76 | +mkdir -p ~/.dstack/secrets |
| 77 | +chmod 700 ~/.dstack/secrets |
| 78 | + |
| 79 | +# Store wallet address (replace with your address) |
| 80 | +echo "0xYOUR_ADDRESS_HERE" > ~/.dstack/secrets/sepolia-address |
| 81 | +chmod 600 ~/.dstack/secrets/sepolia-address |
| 82 | + |
| 83 | +# Store private key (replace with your key) |
| 84 | +echo "0xYOUR_PRIVATE_KEY_HERE" > ~/.dstack/secrets/sepolia-private-key |
| 85 | +chmod 600 ~/.dstack/secrets/sepolia-private-key |
| 86 | +``` |
| 87 | + |
| 88 | +⚠️ **IMPORTANT:** Add to `.gitignore` if working in a git repository: |
| 89 | + |
| 90 | +```bash |
| 91 | +echo "~/.dstack/secrets/" >> ~/.gitignore |
| 92 | +``` |
| 93 | + |
| 94 | +### Step 1.4: Check Wallet Balance |
| 95 | + |
| 96 | +```bash |
| 97 | +# Quick check using public Sepolia RPC |
| 98 | +cast balance "$(cat ~/.dstack/secrets/sepolia-address)" --rpc-url https://ethereum-sepolia-rpc.publicnode.com |
| 99 | +``` |
| 100 | + |
| 101 | +Expected output for new wallet: `0` (zero) |
| 102 | + |
| 103 | +--- |
| 104 | + |
| 105 | +## Option 2: MetaMask Wallet |
| 106 | + |
| 107 | +If you prefer a browser-based wallet, MetaMask is the most popular choice. |
| 108 | + |
| 109 | +### Step 2.1: Install MetaMask |
| 110 | + |
| 111 | +1. Visit: https://metamask.io/ |
| 112 | +2. Install browser extension (Chrome, Firefox, Brave, Edge) |
| 113 | +3. Create new wallet or import existing one |
| 114 | +4. **Save your seed phrase securely** (12 or 24 words) |
| 115 | + |
| 116 | +### Step 2.2: Add Sepolia Network |
| 117 | + |
| 118 | +1. Open MetaMask |
| 119 | +2. Click network dropdown (top center) |
| 120 | +3. Click "Add Network" or "Add a network manually" |
| 121 | +4. Enter Sepolia network details: |
| 122 | + |
| 123 | +``` |
| 124 | +Network Name: Sepolia |
| 125 | +RPC URL: https://ethereum-sepolia-rpc.publicnode.com |
| 126 | +Chain ID: 11155111 |
| 127 | +Currency Symbol: ETH |
| 128 | +Block Explorer: https://sepolia.etherscan.io |
| 129 | +``` |
| 130 | + |
| 131 | +5. Click "Save" |
| 132 | + |
| 133 | +### Step 2.3: Get Your Wallet Address |
| 134 | + |
| 135 | +1. Open MetaMask |
| 136 | +2. Click on account name (top center) |
| 137 | +3. Address shown below name (starts with `0x...`) |
| 138 | +4. Click to copy |
| 139 | + |
| 140 | +### Step 2.4: Export Private Key (for dstack CLI) |
| 141 | + |
| 142 | +⚠️ **Only do this if you need the private key for programmatic access** |
| 143 | + |
| 144 | +1. Open MetaMask |
| 145 | +2. Click three dots (top right) → Account Details |
| 146 | +3. Click "Export Private Key" |
| 147 | +4. Enter MetaMask password |
| 148 | +5. Click to reveal and copy private key |
| 149 | +6. Store securely as shown in Step 1.3 |
| 150 | + |
| 151 | +--- |
| 152 | + |
| 153 | +## Step 2: Get Testnet ETH |
| 154 | + |
| 155 | +You need testnet ETH to deploy the KMS smart contract. |
| 156 | + |
| 157 | +### PoW Faucet (Recommended) |
| 158 | + |
| 159 | +**Best option for new wallets** - no requirements: |
| 160 | + |
| 161 | +1. Visit: https://sepolia-faucet.pk910.de/ |
| 162 | +2. Enter your wallet address |
| 163 | +3. Click "Start Mining" |
| 164 | +4. Wait 10-30 minutes while mining runs in your browser |
| 165 | +5. Claim your testnet ETH (typically 0.05-0.1 ETH per session) |
| 166 | + |
| 167 | +✅ **Why this faucet?** |
| 168 | + |
| 169 | +- No mainnet ETH balance required |
| 170 | +- No account signup needed |
| 171 | +- No MetaMask required |
| 172 | +- Works for brand new wallets |
| 173 | +- Just needs patience for mining |
| 174 | + |
| 175 | +### MetaMask Faucet |
| 176 | + |
| 177 | +If you're using MetaMask: |
| 178 | + |
| 179 | +- URL: https://docs.metamask.io/developer-tools/faucet |
| 180 | +- ❌ **Requires:** MetaMask extension installed |
| 181 | + |
| 182 | +### More Faucet Options |
| 183 | + |
| 184 | +For a comprehensive list of Sepolia faucets with their specific requirements, see: |
| 185 | +**https://faucetlink.to/sepolia** |
| 186 | + |
| 187 | +This page lists all available faucets and their requirements (mainnet ETH balance, account signup, etc.) |
| 188 | + |
| 189 | +### Verify You Received ETH |
| 190 | + |
| 191 | +**Command Line:** |
| 192 | + |
| 193 | +```bash |
| 194 | +# Quick check using public Sepolia RPC |
| 195 | +cast balance "$(cat ~/.dstack/secrets/sepolia-address)" --rpc-url https://ethereum-sepolia-rpc.publicnode.com |
| 196 | +``` |
| 197 | + |
| 198 | +Expected: Non-zero value (e.g., `50000000000000000` = 0.05 ETH, `100000000000000000` = 0.1 ETH in wei) |
| 199 | + |
| 200 | +**MetaMask:** |
| 201 | + |
| 202 | +- Switch to Sepolia network |
| 203 | +- Check balance shown in extension |
| 204 | + |
| 205 | +**Block Explorer:** |
| 206 | + |
| 207 | +```bash |
| 208 | +# Open in browser |
| 209 | +open "https://sepolia.etherscan.io/address/$(cat ~/.dstack/secrets/sepolia-address)" |
| 210 | + |
| 211 | +# Or manually visit with your address |
| 212 | +https://sepolia.etherscan.io/address/YOUR_ADDRESS |
| 213 | +``` |
| 214 | + |
| 215 | +--- |
| 216 | + |
| 217 | +## Step 3: Verify Your Secrets |
| 218 | + |
| 219 | +Check that all required secrets are stored: |
| 220 | + |
| 221 | +```bash |
| 222 | +# List your secrets |
| 223 | +ls -la ~/.dstack/secrets/ |
| 224 | +``` |
| 225 | + |
| 226 | +You should have: |
| 227 | +- `sepolia-address` - Your wallet address |
| 228 | +- `sepolia-private-key` - Your wallet private key |
| 229 | + |
| 230 | +**Test your configuration:** |
| 231 | + |
| 232 | +```bash |
| 233 | +echo "Wallet: $(cat ~/.dstack/secrets/sepolia-address)" |
| 234 | +echo "Balance: $(cast balance "$(cat ~/.dstack/secrets/sepolia-address)" --rpc-url https://ethereum-sepolia-rpc.publicnode.com)" |
| 235 | +``` |
| 236 | + |
| 237 | +--- |
| 238 | + |
| 239 | +## Verification Checklist |
| 240 | + |
| 241 | +Before proceeding to KMS deployment, verify: |
| 242 | + |
| 243 | +- ✅ Wallet created and address saved to `~/.dstack/secrets/sepolia-address` |
| 244 | +- ✅ Private key stored securely in `~/.dstack/secrets/sepolia-private-key` |
| 245 | +- ✅ Wallet has ≥0.1 testnet ETH |
| 246 | +- ✅ Can query balance via cast |
| 247 | + |
| 248 | +--- |
| 249 | + |
| 250 | +## Troubleshooting |
| 251 | + |
| 252 | +For detailed solutions, see the [Prerequisites Troubleshooting Guide](/tutorial/troubleshooting-prerequisites#blockchain-wallet-setup-issues): |
| 253 | + |
| 254 | +- [Faucet not sending ETH](/tutorial/troubleshooting-prerequisites#problem-faucet-not-sending-eth) |
| 255 | +- [RPC endpoint timing out](/tutorial/troubleshooting-prerequisites#problem-rpc-endpoint-timing-out) |
| 256 | +- ["Connection refused" error](/tutorial/troubleshooting-prerequisites#problem-connection-refused-error) |
| 257 | +- [Can't see balance in cast](/tutorial/troubleshooting-prerequisites#problem-cant-see-balance-in-cast) |
| 258 | + |
| 259 | +--- |
| 260 | + |
| 261 | +## Security Best Practices |
| 262 | + |
| 263 | +### DO: |
| 264 | + |
| 265 | +✅ **Follow these practices:** |
| 266 | + |
| 267 | +- Store private keys in encrypted files with restricted permissions (chmod 600) |
| 268 | +- Use environment variables for sensitive data |
| 269 | +- Keep separate wallets for testnet and mainnet |
| 270 | +- Back up your wallet securely (encrypted USB, password manager) |
| 271 | +- Use hardware wallet for mainnet production deployments |
| 272 | + |
| 273 | +### DON'T: |
| 274 | + |
| 275 | +❌ **Avoid these mistakes:** |
| 276 | + |
| 277 | +- Commit private keys to git repositories |
| 278 | +- Share private keys via email, chat, or screenshots |
| 279 | +- Use testnet wallet for mainnet (always use separate wallets) |
| 280 | +- Store private keys in plain text on cloud storage |
| 281 | +- Reuse private keys across projects |
| 282 | + |
| 283 | +--- |
| 284 | + |
| 285 | +## Next Steps |
| 286 | + |
| 287 | +Once your wallet is set up and funded, you can proceed to: |
| 288 | + |
| 289 | +1. **Host Setup:** [TDX Hardware Verification](/tutorial/tdx-hardware-verification) - Begin configuring your TDX-capable server |
| 290 | +2. **Skip Ahead:** If you already have a TDX-enabled server, you'll use this wallet in the KMS deployment phase |
| 291 | + |
| 292 | +Your blockchain wallet is ready for dstack KMS deployment! 🎉 |
0 commit comments