README.md

# Ginie — Smart Contract LLM

[![npm](https://img.shields.io/badge/npm-30k%2B_weekly_downloads-red)](https://npmjs.com/package/ginie-sdk)
[![Website](https://img.shields.io/badge/Website-ginie.xyz-blue)](https://ginie.xyz)
[![License](https://img.shields.io/badge/License-MIT-green)](https://opensource.org/licenses/MIT)
[![Demo](https://img.shields.io/badge/Demo-Live-brightgreen)](https://huggingface.co/spaces/GinieAI/Ginie-Demo)
[![Canton](https://img.shields.io/badge/Canton_Network-Supported-purple)](https://canton.network)

The first AI model purpose-built to generate, compile, audit, and deploy smart contracts across institutional and public blockchains. Plain English in. Production-ready contract out. On-chain in under 90 seconds.

---

## What is Ginie?

Ginie is the developer layer for the next generation of on-chain applications. The friction keeping developers off-chain is not the blockchain itself — it is the specialised languages, compiler toolchains, and security requirements that sit between an idea and a deployed contract. Ginie removes all of that.

Write a description. Get a contract that compiles, passes security checks, and deploys — across Solidity (Ethereum, Avalanche, Camp Network), Daml (Canton Network), and Rust (Vara Network).

Canton Network processes $6 trillion in tokenised assets, backed by Goldman Sachs, JPMorgan, and DTCC. Every institution building on it needs smart contracts. Ginie writes them.

---

## Quickstart
```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

tokenizer = AutoTokenizer.from_pretrained("GinieAI/Solidity-LLM")
model = AutoModelForCausalLM.from_pretrained(
    "GinieAI/Solidity-LLM",
    torch_dtype=torch.bfloat16,
    device_map="auto"
)

prompt = """### Instruction:
Write a Solidity ERC20 token contract with minting, burning, and owner controls.

### Response:
"""

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(
    **inputs,
    max_new_tokens=800,
    temperature=0.7,
    do_sample=True,
    pad_token_id=tokenizer.eos_token_id
)

print(tokenizer.decode(outputs[0], skip_special_tokens=True))
```

**npm SDK** — 30,000+ active weekly downloads
```bash
npm install ginie-sdk
```
```javascript
import { Ginie } from 'ginie-sdk'

const ginie = new Ginie({ apiKey: 'your-key' })

const contract = await ginie.generate({
  prompt: 'ERC20 token with vesting schedule for a startup',
  chain: 'ethereum',
  audit: true
})

console.log(contract.code)
console.log(contract.securityScore)
console.log(contract.compiled)
```

---

## Model Details

### Model Description

- **Developed by:** [Ginie AI](https://ginie.xyz)
- **Model type:** Causal LM — Code Generation
- **Language:** English instructions → Solidity / Daml
- **Parameters:** 2 Billion
- **Architecture:** 32 Transformer blocks
- **Context length:** 2048 tokens
- **Precision:** bfloat16
- **Tokenizer:** GPT2Tokenizer
- **Finetuned from:** [Chain-GPT/Solidity-LLM](https://huggingface.co/Chain-GPT/Solidity-LLM)
- **License:** MIT

### Model Sources

- **Demo:** [huggingface.co/spaces/GinieAI/Ginie-Demo](https://huggingface.co/spaces/GinieAI/Ginie-Demo)
- **Website:** [ginie.xyz](https://ginie.xyz)
- **npm SDK:** [npmjs.com/package/ginie-sdk](https://npmjs.com/package/ginie-sdk)

---

## Uses

### Direct Use

- ERC20, ERC721, ERC1155 token contracts
- DeFi protocols — staking, liquidity pools, yield farming
- DAO and governance contracts
- Multisig wallets and escrow agreements
- NFT marketplaces
- Automated compliance and audit loops

### Downstream Use

- Integrated into IDEs and smart contract development platforms
- Embedded in agentic pipelines for autonomous contract deployment
- npm SDK for direct integration in any JavaScript or TypeScript project

### Out-of-Scope Use

- Production deployment without expert review
- Formal legal or compliance auditing
- Non-code generation tasks

### Bias, Risks, and Limitations

- May reflect patterns from web-scraped Solidity including outdated or insecure practices
- Can generate syntactically valid but logically incorrect contracts
- Security score is indicative — not a substitute for a professional audit
- All generated contracts must be reviewed before mainnet deployment

---

## How to Get Started

See the [Quickstart](#quickstart) section above. For streaming output:
```python
from transformers import AutoModelForCausalLM, AutoTokenizer, TextStreamer
import torch

tokenizer = AutoTokenizer.from_pretrained("GinieAI/Solidity-LLM")
model = AutoModelForCausalLM.from_pretrained(
    "GinieAI/Solidity-LLM",
    torch_dtype=torch.bfloat16,
    device_map="auto"
)

prompt = """### Instruction:
Write a Solidity staking contract with reward distribution.

### Response:
"""

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
streamer = TextStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True)

model.generate(
    **inputs,
    max_new_tokens=1000,
    temperature=0.7,
    do_sample=True,
    streamer=streamer,
    pad_token_id=tokenizer.eos_token_id
)
```

---

## Training Details

### Training Data

- [AlfredPros/smart-contracts-instructions](https://huggingface.co/datasets/AlfredPros/smart-contracts-instructions) — 6,000 instruction-output pairs
- Filtered: Solidity >= 0.5, token length 200–4000, compilable contracts only
- Deduplicated and validated before training

### Training Procedure

- **Method:** LoRA fine-tuning (rank 16, alpha 16)
- **Base:** Chain-GPT/Solidity-LLM → Salesforce/codegen-2B-multi
- **Epochs:** 3
- **Precision:** bfloat16
- **Framework:** Unsloth + HuggingFace TRL
- **Validation:** Slither static analysis + solc compilation check

---

## Evaluation

Evaluated on 100 held-out Solidity prompts. Compilation measured via `solc`. Security measured via [Slither](https://github.com/crytic/slither).

| Metric | Ginie v1 | GPT-4o mini | DeepSeek-Coder-7B |
|---|---|---|---|
| Compilation rate | **83%** | 78% | 75% |
| OpenZeppelin compliance | **65%** | 61% | 58% |
| Gas efficiency | **72%** | 65% | 63% |
| Security score | **58%** | 54% | 51% |

Ginie achieves the highest compilation rate at 2B parameters — domain specialisation over general-purpose scale.

---

## Chains Supported

| Blockchain | Language | Status |
|---|---|---|
| Ethereum | Solidity | Live |
| Avalanche | Solidity | Live |
| Camp Network | Solidity | Live |
| Canton Network | Daml | v3 roadmap |
| Vara Network | Rust | v3 roadmap |

---

## Roadmap

| Version | What ships |
|---|---|
| v1.0 (current) | Solidity generation — 2B params, 83% compile rate |
| v2.0 | Expanded corpus — DISL + Zellic, 7,800+ examples, security score 70%+ |
| v3.0 | Daml + Rust — Canton Network and Vara Network |
| v4.0 | Weekly retraining flywheel on verified user prompts |

---

## Citation
```bibtex
@misc{ginie2025,
  title     = {Ginie: Smart Contract LLM for Institutional Blockchain},
  author    = {Ginie AI},
  year      = {2025},
  url       = {https://huggingface.co/GinieAI/Solidity-LLM},
  note      = {Fine-tuned from Chain-GPT/Solidity-LLM (Salesforce/codegen-2B-multi)}
}
```

---

## License and Attribution

Released under the MIT License. Built on [Chain-GPT/Solidity-LLM](https://huggingface.co/Chain-GPT/Solidity-LLM) by ChainGPT, fine-tuned from [Salesforce/codegen-2B-multi](https://huggingface.co/Salesforce/codegen-2B-multi). Full credit to the original authors.

---

[ginie.xyz](https://ginie.xyz) · [npm SDK](https://npmjs.com/package/ginie-sdk) · [Live demo](https://huggingface.co/spaces/GinieAI/Ginie-Demo)

> Smart contracts generated by Ginie require expert review before production deployment. Security scores are indicative and do not constitute a formal audit.