🚀 TypeScript — Blueprint — Sandbox (AGI Strict Protocol)

---
trigger: model_decision
description: Use this rule for smart contract testing, scripting, and interaction with TON blockchain using TypeScript, Blueprint, and Sandbox. Always apply it when developing TypeScript code for TON.
globs: *.ts
---
# 🚀 TypeScript — Blueprint — Sandbox (AGI Strict Protocol)

## 🎯 Core Principles (Mandatory)

- **Explicitness & Precision**:  
  - No implicit types (`any` strictly forbidden).  
  - Zero ESLint warnings/errors tolerated.
  - Immediately fix autogenerated Jest issues (type mismatches, serialization errors).

- **Property-Based Testing (fast-check) Dominance**:  
  - Prioritize **fast-check** property tests alongside standard Jest unit tests.
  - Clearly define ≥5 invariant properties per key functionality.
  - Immediately add targeted unit tests for historically problematic edge-cases.

- **Total Autonomy**:  
  - Proactively resolve technical issues. Never defer, never suppress.

---

## ✅ Essential Workflow

### 1. **Contract & Wrapper Generation**

- Contract per file (`contracts/`) in strict PascalCase naming.
- Wrappers auto-generated (`npx blueprint build --all`) for **Tact only** (manual wrapper rules: `func.mdc`, `fift.mdc`, `tolk.mdc`).

### 2. **Mandatory Testing Strategy**

- Combine Jest units, **fast-check properties**, and fuzz tests explicitly in `tests/`.
- Example structure (`tests/prop/MyContract.pbt.ts`):

```typescript
import { testProp, fc } from 'fast-check';
import { logicFn } from '../../wrappers/MyContract';

fc.configureGlobal({ numRuns: 200 });

testProp('encode/decode symmetry', [fc.string()], (s) => {
  expect(decode(encode(s))).toBe(s);
});

testProp('balance invariant', [account()], (acc) => {
  expect(update(acc).balance).toBeGreaterThanOrEqual(0);
});

// At least 5 robust property tests per module/functionality
```

- Property tests **mandatory**. Every logic change demands new properties or validation.

### 3. **Sandbox Testing Discipline**

- Consistent initialization pattern (`@ton/sandbox`):

```typescript
import { Blockchain, SandboxContract } from '@ton/sandbox';
import { MyContract } from '../wrappers/MyContract';

let blockchain: Blockchain;
let wallet: SandboxContract;
let contract: SandboxContract<MyContract>;

beforeEach(async () => {
  blockchain = await Blockchain.create();
  wallet = await blockchain.treasury('wallet');
  contract = blockchain.openContract(await MyContract.fromInit(wallet.address));
  await contract.sendDeploy(wallet.getSender(), toNano('0.05'));
});
```

- **Strict state verification**: explicitly verify transactions (`toHaveTransaction`).

---

## 🧪 Strict Code Quality Enforcement

- **ESLint Compliance**: enforce `eslint --fix`; zero warnings/errors.
- **Explicit Handling of Promises & Async**: always await explicitly.
- **Logging Discipline**: use with always `console.log` with testing code.

---

## 📜 Script Crafting Discipline

- **Explicit Entry Structure** (PascalCase naming):

```typescript
import { NetworkProvider } from '@ton-ai-core/blueprint';

export async function run(provider: NetworkProvider, args: string[]) {
  const ui = provider.ui();
  const contractAddress = args[0] || await ui.input('Contract Address:');
  const contract = provider.open(MyContract.fromAddress(contractAddress));

  // Explicit business logic handling here
}
```

- **Secure Handling**: Sensitive config strictly from `.env`. Explicit, informative errors mandatory.

---

## 🚨 Troubleshooting Autonomy

Immediately resolve:

- Deployment checks (`provider.isContractDeployed()`)
- Jest timeouts (always use explicit awaits `blockchain.run()`)
- ESLint compliance (explicit awaits)
- Snapshot serialization (explicit `.toString()` for BigInt)

No temporary suppressions; solve permanently.

---

## ♻️ Rollback Enforcement (Mandatory)

- Any test/property/fuzz failure immediately triggers rollback to Contract Coding or Tests. Zero tolerance policy.

---

## 📌 Checklist (Must be TRUE for every merge/deploy)

- [ ] ESLint — 0 warnings/errors
- [ ] Jest — 100% coverage, no failures
- [ ] Property-based tests (fast-check) ≥5 invariants per key module
- [ ] Sandbox transactions explicitly verified
- [ ] All autogenerated issues resolved immediately
- [ ] Scripts — Explicit, secure `.env`, informative errors
- [ ] Autonomy — Zero placeholders, zero suppressions, zero manual interventions

---

**This document is mandatory under AGI strict protocol. No deviations permitted.**