Hiro Docs

Function Signature

(define-map map-name key-type value-type)

Input:
- map-name: The name of the map
- key-type: The type of the map's keys
- value-type: The type of the map's values
Output: Not applicable (definition statement)

Why it matters

The define-map function is crucial for:

Creating key-value stores within smart contracts.
Efficiently organizing and accessing structured data.
Implementing complex data structures like mappings or dictionaries.
Storing and retrieving contract-specific data associated with unique keys.

When to use it

Use define-map when you need to:

Store and retrieve data associated with unique keys.
Implement lookup tables or dictionaries in your contract.
Organize data that needs to be accessed by a specific identifier.
Create data structures that can be efficiently updated and queried.

Best Practices

Choose appropriate types for keys and values to ensure efficient storage and retrieval.
Use meaningful names for your maps that reflect their purpose in the contract.
Consider using composite keys (tuples) for more complex data relationships.
Be mindful of the gas costs associated with map operations, especially for large datasets.

Practical Example: Simple User Profile System

Let's implement a basic user profile system using define-map:

(define-map UserProfiles principal { name: (string-ascii 50), age: uint, isActive: bool })

(define-public (set-profile (name (string-ascii 50)) (age uint))
  (ok (map-set UserProfiles tx-sender { name: name, age: age, isActive: true }))
)

(define-read-only (get-profile (user principal))
  (default-to { name: "", age: u0, isActive: false } (map-get? UserProfiles user))
)

(define-public (deactivate-profile)
  (match (map-get? UserProfiles tx-sender) profile
    (ok (map-set UserProfiles tx-sender (merge profile { isActive: false })))
    (err u404)
  )
)

;; Usage
(set-profile "Ryan" u38)
(get-profile tx-sender)
(deactivate-profile)

This example demonstrates:

Using define-map to create a user profile storage system.
Implementing functions to set, get, and update profile data.
Using map operations like map-set, map-get?, and merge to manipulate map data.
Handling cases where a profile might not exist using default-to.

Common Pitfalls

Forgetting that maps are not iterable in Clarity; you can't loop through all entries.
Not handling cases where a key might not exist in the map.
Overusing maps for data that might be better suited for other data structures.
Not considering the gas costs of map operations in complex contracts.

map-get?: Used to retrieve a value from a map, returns an optional.
map-set: Used to set or update a value in a map.
map-delete: Used to remove a key-value pair from a map.
map-insert: Used to insert a new key-value pair only if the key doesn't already exist.
merge: Used to merge two maps, combining their key-value pairs.

The define-map function is a powerful tool for creating structured data storage in Clarity smart contracts. It allows developers to implement efficient key-value stores, enabling complex data relationships and lookups. When used effectively, maps can significantly enhance the functionality and organization of data within your smart contracts.

define-map