Dojo World Management

Manage your Dojo world's permissions, namespaces, resource registration, and access control policies.

When to Use This Skill

"Configure world permissions"
"Set up namespace access"
"Grant writer permissions"
"Manage resource ownership"

What This Skill Does

Handles world management:

Namespace configuration
Resource registration
Writer permissions
Owner permissions
Role-based access
Permission transfers

Quick Start

Configure permissions:

"Grant writer permission to my system"

Namespace setup:

"Create a namespace for my game"

Transfer ownership:

"Transfer world ownership to new address"

World Concepts

World Contract

Central registry that:

Manages all models and systems
Controls permissions
Handles namespaces
Stores metadata

Namespaces

Logical groupings of resources:

Models belong to namespaces
Systems belong to namespaces
Permissions granted per namespace
Prevents naming conflicts

Permissions

Two types:

Owner: Full control (grant/revoke permissions)
Writer: Can write to models

Permission Management

Granting Writer Permission

Allow a system to write to models:

sozo auth grant writer \
    MODEL_NAME,SYSTEM_ADDRESS \
    --world WORLD_ADDRESS

Example:

# Grant actions system writer to Position model
sozo auth grant writer \
    Position,0x123... \
    --world 0xabc...

Granting Owner Permission

Transfer ownership or grant admin access:

sozo auth grant owner \
    RESOURCE_NAME,NEW_OWNER_ADDRESS \
    --world WORLD_ADDRESS

Revoking Permissions

Remove access:

sozo auth revoke writer \
    MODEL_NAME,SYSTEM_ADDRESS \
    --world WORLD_ADDRESS

Namespace Management

Creating Namespace

sozo auth create-namespace \
    my_namespace \
    --world WORLD_ADDRESS

Registering Resources

# Register model to namespace
sozo auth register model \
    Position \
    --namespace my_namespace \
    --world WORLD_ADDRESS

# Register system to namespace
sozo auth register contract \
    actions \
    --namespace my_namespace \
    --world WORLD_ADDRESS

Common Permission Patterns

Game System Permissions

Grant system access to all game models:

# Actions system can write to Position
sozo auth grant writer Position,ACTIONS_ADDRESS

# Actions system can write to Health
sozo auth grant writer Health,ACTIONS_ADDRESS

# Actions system can write to Inventory
sozo auth grant writer Inventory,ACTIONS_ADDRESS

Admin System

Grant admin system owner permissions:

sozo auth grant owner Position,ADMIN_SYSTEM_ADDRESS
sozo auth grant owner Config,ADMIN_SYSTEM_ADDRESS

Multi-System Architecture

Different systems for different aspects:

# Movement system writes to Position
sozo auth grant writer Position,MOVEMENT_SYSTEM

# Combat system writes to Health
sozo auth grant writer Health,COMBAT_SYSTEM

# Inventory system writes to Inventory
sozo auth grant writer Inventory,INVENTORY_SYSTEM

World API

In Systems (Cairo)

Check permissions:

#[dojo::contract]
pub mod system {
    fn restricted_action(ref self: ContractState) {
        let world = self.world_default();

        // Only owner can call
        world.assert_owner(get_caller_address());

        // Or check writer
        world.assert_writer(get_caller_address());
    }
}

Grant permissions from system:

fn setup_permissions(ref self: ContractState) {
    let world = self.world_default();

    // Grant writer permission
    world.grant_writer(MODEL_SELECTOR, system_address);

    // Grant owner permission
    world.grant_owner(RESOURCE_SELECTOR, new_owner);
}

Authorization Patterns

Public Systems

Anyone can call:

fn spawn(ref self: ContractState) {
    // No permission check - anyone can spawn
    let player = get_caller_address();
    world.write_model(@Position { player, x: 0, y: 0 });
}

Owner-Only Systems

Only world owner:

fn admin_function(ref self: ContractState) {
    let world = self.world_default();
    world.assert_owner(get_caller_address());

    // Admin logic
}

Writer-Only Systems

Only authorized writers:

fn internal_update(ref self: ContractState) {
    let world = self.world_default();
    world.assert_writer(get_caller_address());

    // Update logic
}

Custom Authorization

Check specific conditions:

fn guild_action(ref self: ContractState, guild_id: u32) {
    let player = get_caller_address();

    // Read player's guild membership
    let member: GuildMember = world.read_model((guild_id, player));
    assert(member.role >= OFFICER, 'not authorized');

    // Guild logic
}

Metadata Management

World Metadata

Set world information:

fn set_metadata(ref self: ContractState) {
    let world = self.world_default();

    world.set_metadata_uri("https://example.com/metadata.json");
}

Resource Metadata

Set model/system metadata:

world.set_resource_metadata(
    MODEL_SELECTOR,
    "ipfs://QmHash..."
);

Security Best Practices

Principle of Least Privilege

Grant minimal permissions:

# ❌ Don't grant owner when writer is enough
sozo auth grant owner Position,SYSTEM_ADDRESS

# ✅ Grant only writer
sozo auth grant writer Position,SYSTEM_ADDRESS

Audit Permissions Regularly

# Check who has access to model
sozo auth list writers Position --world WORLD_ADDRESS

# Check owners
sozo auth list owners Position --world WORLD_ADDRESS

Secure Owner Key

Use hardware wallet for owner account
Consider multi-sig for production
Rotate keys if compromised

Test Permission Checks

#[test]
#[should_panic(expected: ('not authorized',))]
fn test_unauthorized_access() {
    let unauthorized = starknet::contract_address_const::<0x999>();
    prank(world, unauthorized);

    system.admin_function();  // Should panic
}

World Management Checklist

Initial Setup

Permission Configuration

Grant writer permissions to all systems
Set up admin accounts
Configure authorization in systems
Test permission checks
Document permission structure

Production Readiness

Common Scenarios

Setting Up New Game

# 1. Deploy world
sozo migrate --name my_game

# 2. Record addresses from manifest
WORLD_ADDRESS=...
ACTIONS_ADDRESS=...

# 3. Grant permissions
sozo auth grant writer Position,$ACTIONS_ADDRESS --world $WORLD_ADDRESS
sozo auth grant writer Health,$ACTIONS_ADDRESS --world $WORLD_ADDRESS

# 4. Verify
sozo auth list writers Position --world $WORLD_ADDRESS

Adding New System

# 1. Deploy new system
sozo migrate --world WORLD_ADDRESS

# 2. Grant necessary permissions
sozo auth grant writer NewModel,NEW_SYSTEM_ADDRESS --world WORLD_ADDRESS

# 3. Test
sozo execute new_system test_function --world WORLD_ADDRESS

Transferring Ownership

# Transfer world ownership
sozo auth transfer-ownership NEW_OWNER_ADDRESS --world WORLD_ADDRESS

Troubleshooting

"Not authorized" errors

Check writer permissions granted
Verify system address is correct
Ensure caller has required permission

"Resource not found"

Verify resource is registered
Check namespace is correct
Ensure resource is deployed

"Permission denied"

Check owner permissions
Verify transaction from correct account
Ensure not trying to grant higher than owned

Next Steps

After world setup:

Test all permission checks
Document permission structure
Set up monitoring for permission changes
Configure client with appropriate accounts

Related Skills

dojo-deploy: Deploy world first
dojo-system: Add authorization to systems
dojo-review: Audit permission setup
dojo-migrate: Update permissions after changes

dojo-world