Contract Lab Tutorial: Revisions, AI Rewrite, Validate, Deploy

Route: /dashboard/organization/contract-lab

This tutorial walks through the complete daily workflow in Contract Lab:

1. Create a project
2. Edit draft files
3. Save and compare revisions
4. Use AI generation and rewrite
5. Validate and queue deployment

1. Open Contract Lab

From an active organization workspace, go to Contract Lab in the sidebar.

You should see:

• Create Contract Project
• Revision Composer
• Contract IDE
• Revision History And Diff
• Deployments

2. Create a Contract Project

In Create Contract Project:

1. Fill Project name (required)
2. Optionally fill Description
3. Click Create Project

After creation:

• The project is automatically selected in Revision Composer.
• Contract Lab auto-creates the first revision from the default Dubhe template (based on the 101 stack scaffold).

3. Compose and Save a Revision

In Revision Composer:

1. Confirm Project
2. Set Revision summary
3. Optionally set Prompt, RPC URL, and Deploy notes
4. Click Save Revision

Saved revisions appear in the History tab below.

4. Edit Draft Files in Contract IDE

In Contract IDE:

• Select files from the left file list
• Edit content in Monaco editor (syntax highlight, line numbers, shortcuts)
• Add a file with sources/new_contract.move + Add
• Delete files with Del (except Move.toml)
• Use Raw Files JSON for direct JSON-level editing

5. Compare Revisions in Diff

Go to Revision History And Diff -> Diff:

1. Choose Base revision
2. Choose Target (another revision or Draft)
3. Choose File
4. Review side-by-side diff (left = base, right = target)

Status badges show each file change: added, deleted, modified, unchanged.

6. Use History Actions

In History, each revision supports:

• Load To Draft: load snapshot into current draft editor
• Set As Diff Base / Set As Diff Target: quick diff setup
• Queue Deploy This Revision: queue this specific revision
• Rollback To This Revision: create a new latest revision from this snapshot

7. AI Actions

Available AI operations:

• AI Generate + Save: generate full revision from Prompt
• AI Generate + Queue Deploy: generate and queue in one step
• AI Rewrite Current File: rewrite only selected file based on instruction

AI output is validated against Dubhe Stack conventions before being accepted. If generated files do not match required Dubhe structure, the request is rejected.

Dubhe gate is enforced in five layers:

1. Prompt contract: model is instructed to output Dubhe-compatible full JSON files only
2. File safety: paths and file map are sanitized (Move.toml required, safe relative paths only)
3. Dubhe semantic rules:
   • Move.toml must include package name/edition/addresses and Dubhe = { local = "...dubhe..." }
   • required files like sources/codegen/genesis.move, sources/scripts/deploy_hook.move, sources/codegen/dapp_key.move
   • genesis.move must include dapp_system::create_dapp(...) and <package>::deploy_hook::run(...)
   • at least one sources/systems/*.move must use dubhe::dapp_service::DappHub
4. Compile gate: server runs CONTRACT_VALIDATE_COMMAND (if configured)
5. Queue gate: only validated drafts/revisions can enter deployment queue

When rejected, backend returns deterministic violation lines like: [rule_code] <file-path>: <message>.

Recommended prompt style:

• Clearly state module name and target behavior
• Specify constraints (for example no breaking changes)
• Ask for deterministic outputs when needed

8. Validate and Deploy

Deployment-related actions in IDE:

• Validate Draft: runs server-side validation command
• Save + Validate + Queue Deploy: one-click pipeline for save -> validate -> queue
• Queue Latest Revision: queue latest saved revision from composer

Validation logs appear in Validation Output. Deployment results appear in Deployments with status: queued, running, succeeded, failed, canceled. The deployments list auto-refreshes periodically and shows:

• Package (on-chain package id)
• Digest (transaction digest)

9. Development-Only Worker

In non-production environments, Run Worker lets you process queued deployments manually.

• Set Max tasks per batch
• Click Run Worker Batch
• Inspect returned worker output

Alternative (recommended for continuous local testing): run worker as a container.

cd /Users/henryliu/obelisk/website
npm run contract:worker:docker:up:local
npm run contract:worker:docker:logs

Stop it with:

npm run contract:worker:docker:down

10. Common Troubleshooting

Draft editor disabled

Files JSON is invalid means Raw Files JSON is malformed. Fix it to re-enable IDE editing.

Cannot queue deployment

Check:

• Organization role is owner or admin
• Subscription plan allows deployment features
• Queue capacity is not exceeded

Validation fails

Review Validation Output logs first, then fix draft files and run Validate Draft again.

11. Fast AI E2E Test (Recommended)

Use this checklist to verify the complete AI -> deploy path:

1. Start app:
   • npm run dev
2. Start worker (choose one):
   • In UI: Run Worker Batch (development only), or
   • Docker worker: npm run contract:worker:docker:up:local
3. Open /dashboard/organization/contract-lab
4. Create a project (initial Dubhe template revision is created automatically)
5. In Revision Composer, enter a prompt like:
   • Add a new entry function to counter::counter_system that decrements value by u32 with underflow guard
6. Click AI Generate + Queue Deploy (network: testnet)
7. Watch Deployments move from queued to succeeded
8. Copy Package and Digest for chain verification