dotdog 0.3.5 → 0.4.0

package/kits/defi/SPEC.dog

@@ -0,0 +1,21 @@
+# DeFi Protocol
+
+> Yield-bearing vault. Users deposit tokens, earn yield via strategies, withdraw with returns.
+
+## Product
+
+A yield vault. Users deposit USDC, vault deploys capital into strategies, users withdraw with accrued yield.
+
+### Flow
+```
+User approves Vault → deposit(amount) → Vault mints Shares → Strategy earns yield → User withdraws with returns
+```
+
+## Architecture
+
+| Component | Role |
+|-----------|------|
+| Vault | ERC-4626 vault. Deposits, withdrawals, share minting. |
+| Strategy | Yield source. Lending, LP, staking. |
+| Share | ERC-20 token representing vault ownership. |
+| Yield | Accrued returns distributed to shareholders. |

package/kits/defi/constitution.dog

@@ -0,0 +1,8 @@
+# Constitution — DeFi
+
+## Principles
+
+1. **ERC-4626 compliance** — standard vault interface
+2. **No admin withdrawal** — owner cannot drain user deposits
+3. **Slippage protection** — deposits and withdrawals respect bounds
+4. **Strategy isolation** — one strategy failure cannot drain vault

package/kits/defi/data-model.dog

@@ -0,0 +1,131 @@
+# Data Model — DeFi
+
+## Entities
+
+### Entity: Vault
+
+ERC-4626 compliant yield vault.
+
+```yaml
+entity: Vault
+type: contract
+properties:
+  name:
+    type: string
+    required: true
+  symbol:
+    type: string
+    required: true
+  underlying:
+    type: string
+    required: true
+  totalAssets:
+    type: number
+    required: true
+  performanceFee:
+    type: number
+    required: false
+states: [initialized, active, paused, emergency]
+lifecycle: initialized → active → paused → emergency
+```
+
+### Entity: Strategy
+
+Yield-generating strategy.
+
+```yaml
+entity: Strategy
+type: contract
+properties:
+  name:
+    type: string
+    required: true
+  vault:
+    type: string
+    required: true
+  apy:
+    type: number
+    required: true
+  tvl:
+    type: number
+    required: true
+  risk:
+    type: enum
+    required: true
+states: [proposed, active, harvesting, closed]
+lifecycle: proposed → active → harvesting → closed
+```
+
+### Entity: Share
+
+ERC-20 token representing vault ownership.
+
+```yaml
+entity: Share
+type: contract
+properties:
+  vault:
+    type: string
+    required: true
+  totalSupply:
+    type: number
+    required: true
+  pricePerShare:
+    type: number
+    required: true
+states: [active]
+lifecycle: active → active
+```
+
+### Entity: Yield
+
+Accrued returns from strategies.
+
+```yaml
+entity: Yield
+type: event
+properties:
+  amount:
+    type: number
+    required: true
+  strategy:
+    type: string
+    required: true
+  timestamp:
+    type: number
+    required: true
+states: [harvested, distributed]
+lifecycle: harvested → distributed
+```
+
+## Relationships
+
+### Relationship: Vault → Strategy
+
+```yaml
+relationship: Vault -> Strategy
+verb: deploys
+cardinality: 1:N
+required: true
+description: Vault deploys capital into strategies
+```
+
+### Relationship: Strategy → Yield
+
+```yaml
+relationship: Strategy -> Yield
+verb: produces
+cardinality: 1:N
+required: true
+description: Strategy harvests yield
+```
+
+### Relationship: Vault → Share
+
+```yaml
+relationship: Vault -> Share
+verb: mints
+cardinality: 1:1
+required: true
+description: Vault mints shares on deposit
+```

package/kits/erc20/SPEC.dog

@@ -0,0 +1,20 @@
+# ERC20 Token
+
+> Fungible token spec. ERC20 compliant. Mint, burn, transfer, approve.
+
+## Product
+
+A standard ERC20 token. Users hold balances, transfer tokens, approve spenders.
+
+### Flow: User transfers tokens
+```
+User calls transfer(to, amount) → Token updates balances → Transfer event emitted
+```
+
+## Architecture
+
+| Component | Role |
+|-----------|------|
+| Token | ERC20 contract: mint, burn, transfer, approve |
+| Balance | Per-address token balance |
+| Allowance | Per-spender approved amount |

package/kits/erc20/constitution.dog

@@ -0,0 +1,8 @@
+# Constitution — ERC20
+
+## Principles
+
+1. **ERC20 compliance** — implements IERC20 interface
+2. **No admin rug** — owner cannot seize user balances
+3. **Zero-address protection** — cannot transfer to address(0)
+4. **Event emission** — all state changes emit events

package/kits/erc20/data-model.dog

@@ -0,0 +1,97 @@
+# Data Model — ERC20
+
+## Entities
+
+### Entity: Token
+
+An ERC20-compliant fungible token.
+
+```yaml
+entity: Token
+type: contract
+properties:
+  name:
+    type: string
+    required: true
+  symbol:
+    type: string
+    required: true
+  decimals:
+    type: number
+    required: true
+  totalSupply:
+    type: number
+    required: true
+  owner:
+    type: string
+    required: true
+states: [deployed, active, paused]
+lifecycle: deployed → active → paused
+```
+
+### Entity: Transfer
+
+A token transfer between two addresses.
+
+```yaml
+entity: Transfer
+type: event
+properties:
+  from:
+    type: string
+    required: true
+  to:
+    type: string
+    required: true
+  amount:
+    type: number
+    required: true
+  timestamp:
+    type: number
+    required: true
+states: [pending, confirmed]
+lifecycle: pending → confirmed
+```
+
+### Entity: Approval
+
+An allowance for a spender to transfer tokens.
+
+```yaml
+entity: Approval
+type: event
+properties:
+  owner:
+    type: string
+    required: true
+  spender:
+    type: string
+    required: true
+  amount:
+    type: number
+    required: true
+states: [pending, confirmed]
+lifecycle: pending → confirmed
+```
+
+## Relationships
+
+### Relationship: Transfer → Token
+
+```yaml
+relationship: Transfer -> Token
+verb: modifies
+cardinality: N:1
+required: true
+description: Transfer modifies token balances
+```
+
+### Relationship: Approval → Token
+
+```yaml
+relationship: Approval -> Token
+verb: authorizes
+cardinality: N:1
+required: true
+description: Approval authorizes spender for token
+```

package/kits/hackathon/SPEC.dog

@@ -0,0 +1,20 @@
+# Hackathon Starter
+
+> Build fast. Ship working. This is your foundation.
+
+## Product
+
+A web3 application. Built for a hackathon. Works in a live demo.
+
+### Flow
+```
+User connects wallet → App reads chain state → User submits transaction → App confirms onchain → Demo complete
+```
+
+## Architecture
+
+| Component | Role |
+|-----------|------|
+| UI | Frontend: wallet connection, transaction button |
+| Contract | Onchain logic: storage, verification |
+| RPC | Chain connection: read state, submit tx |

package/kits/hackathon/constitution.dog

@@ -0,0 +1,8 @@
+# Constitution — Hackathon
+
+## Principles
+
+1. **Demo works** — must run in a live demo
+2. **Readable in 2 minutes** — judges understand it fast
+3. **Onchain proof** — transaction hash verifies activity
+4. **No novel crypto** — reuse existing standards

package/kits/hackathon/data-model.dog

@@ -0,0 +1,64 @@
+# Data Model — Hackathon
+
+## Entities
+
+### Entity: User
+
+A connected wallet. The app's user.
+
+```yaml
+entity: User
+type: entity
+properties:
+  address:
+    type: string
+    required: true
+  chainId:
+    type: number
+    required: true
+  balance:
+    type: number
+    required: false
+states: [disconnected, connected, transacting]
+lifecycle: disconnected → connected → transacting
+```
+
+### Entity: Transaction
+
+An onchain action by the user.
+
+```yaml
+entity: Transaction
+type: event
+properties:
+  hash:
+    type: string
+    required: true
+  from:
+    type: string
+    required: true
+  to:
+    type: string
+    required: true
+  value:
+    type: number
+    required: true
+  status:
+    type: enum
+    required: true
+states: [pending, confirmed, failed]
+lifecycle: pending → confirmed
+lifecycle: pending → failed
+```
+
+## Relationships
+
+### Relationship: User → Transaction
+
+```yaml
+relationship: User -> Transaction
+verb: submits
+cardinality: 1:N
+required: true
+description: User submits transactions
+```

package/kits/nft/SPEC.dog

@@ -0,0 +1,21 @@
+# NFT Collection
+
+> Non-fungible token collection. ERC-721 compliant. Mint, transfer, metadata.
+
+## Product
+
+An NFT collection. Users mint tokens with metadata. Tokens are unique, transferable, and have royalty support.
+
+### Flow
+```
+Creator deploys Collection → User mints Token → Token has metadata → User transfers Token → Royalty paid to creator
+```
+
+## Architecture
+
+| Component | Role |
+|-----------|------|
+| Collection | ERC-721 contract. Mint, burn, transfer. |
+| Token | Unique NFT with metadata URI. |
+| Metadata | JSON: name, description, image, attributes. |
+| Royalty | Secondary sale fee paid to creator. |

package/kits/nft/constitution.dog

@@ -0,0 +1,8 @@
+# Constitution — NFT
+
+## Principles
+
+1. **ERC-721 compliance** — implements IERC721 interface
+2. **Metadata permanence** — tokenURI must be immutable or IPFS-backed
+3. **Royalty enforcement** — EIP-2981 compliant
+4. **No admin rug** — owner cannot seize tokens

package/kits/nft/data-model.dog

@@ -0,0 +1,131 @@
+# Data Model — NFT
+
+## Entities
+
+### Entity: Collection
+
+ERC-721 compliant NFT collection.
+
+```yaml
+entity: Collection
+type: contract
+properties:
+  name:
+    type: string
+    required: true
+  symbol:
+    type: string
+    required: true
+  totalSupply:
+    type: number
+    required: true
+  owner:
+    type: string
+    required: true
+  royaltyBps:
+    type: number
+    required: false
+states: [deployed, active, paused]
+lifecycle: deployed → active → paused
+```
+
+### Entity: Token
+
+A unique NFT within a collection.
+
+```yaml
+entity: Token
+type: entity
+properties:
+  tokenId:
+    type: number
+    required: true
+  owner:
+    type: string
+    required: true
+  tokenURI:
+    type: string
+    required: true
+  collection:
+    type: string
+    required: true
+states: [unminted, minted, transferred, burned]
+lifecycle: unminted → minted → transferred → burned
+```
+
+### Entity: Metadata
+
+JSON metadata for an NFT token.
+
+```yaml
+entity: Metadata
+type: entity
+properties:
+  name:
+    type: string
+    required: true
+  description:
+    type: string
+    required: true
+  image:
+    type: string
+    required: true
+  attributes:
+    type: json
+    required: false
+states: [draft, published]
+lifecycle: draft → published
+```
+
+### Entity: Royalty
+
+Secondary sale royalty payment.
+
+```yaml
+entity: Royalty
+type: event
+properties:
+  creator:
+    type: string
+    required: true
+  amount:
+    type: number
+    required: true
+  salePrice:
+    type: number
+    required: true
+states: [pending, paid]
+lifecycle: pending → paid
+```
+
+## Relationships
+
+### Relationship: Collection → Token
+
+```yaml
+relationship: Collection -> Token
+verb: mints
+cardinality: 1:N
+required: true
+description: Collection mints unique tokens
+```
+
+### Relationship: Token → Metadata
+
+```yaml
+relationship: Token -> Metadata
+verb: references
+cardinality: 1:1
+required: true
+description: Token references its metadata
+```
+
+### Relationship: Token → Royalty
+
+```yaml
+relationship: Token -> Royalty
+verb: triggers
+cardinality: 1:N
+required: false
+description: Transfer triggers royalty payment
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotdog",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "CLI tool for structured software specifications. Validate .dog files, compile .dag graphs, query via MCP.",
   "type": "module",
   "main": "dist/cli.js",
@@ -12,7 +12,8 @@
     "dist/",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "kits/"
   ],
   "keywords": [
     "specification",