api-design
/api-design
Podaje dobre praktyki projektowania API inteligentnych kontraktów CosmWasm: typy komunikatów, interfejsy execute i query oraz ergonomia API.
- Autor
- axone-protocol ↗
- Repozytorium
- contracts ↗
- Licencja
- BSD-3-Clause
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
BSD-3-Clause, otwarta.
Co robi i kiedy
Podaje dobre praktyki projektowania API inteligentnych kontraktów CosmWasm: typy komunikatów, interfejsy execute i query oraz ergonomia API.
Oryginalny opis (EN)
Best practices for designing CosmWasm smart contract APIs. Use when defining message types, designing execute/query interfaces, or optimizing API ergonomics.
Jak działa
- Core Principles
- Message Type Patterns
- Abstract SDK Integration
- Documentation Standards
- Serde Patterns
Podgląd SKILL.md
---
name: api-design
description: Best practices for designing CosmWasm smart contract APIs. Use when defining message types, designing execute/query interfaces, or optimizing API ergonomics.
license: BSD-3-Clause
metadata:
author: axone.xyz
version: "1.0"
---
# CosmWasm API Design Best Practices
## Core Principles
1. **Minimalism** - Include only what's necessary; avoid bloated APIs
2. **Clarity** - Names should be self-documenting
3. **Consistency** - Follow established patterns across all contracts
4. **Documentation** - Every public type and field must have doc comments
## Message Type Patterns
### InstantiateMsg
```rust
/// Contract instantiation message
#[cosmwasm_schema::cw_serde]
#[derive(Default)]
pub struct MyContractInstantiateMsg {
/// Optional configuration parameter with sensible default
#[serde(default)]
pub some_config: Option<String>,
}
```
**Guidelines:**
- Derive `Default` when possible for easier testing
- Use `#[serde(default)]` for optional fields
- Keep required fields minimal
- Document each field
### ExecuteMsg
```rust
/// Contract execute messages
#[cosmwasm_schema::cw_serde]
#[derive(cw_orch::ExecuteFns)]
pub enum MyContractExecuteMsg {
/// Update the contract configuration
UpdateConfig {
/// New admin address (optional)
new_admin: Option<String>,
},
/// Process an action with the given parameters
ProcessAction {
/// Unique identifier for the action
action_id: String,
/// Amount to process
amount: Uint128,
},
}
```
**Guidelines:**
- Use verb-based names (Update, Process, Create, Remove)
- Group related parameters in structs if >3 fields
- Document each variant AND each field
- Derive `ExecuteFns` for cw-orch integration
### QueryMsg
```rust
/// Contract query messages
#[cosmwasm_schema::cw_serde]
#[derive(cw_orch::QueryFns, QueryResponses)]
pub enum MyContractQueryMsg {
/// Get the current configuration
#[returns(ConfigResponse)]
Config {},
/// Get item by ID
#[returns(ItemResponse)]
Item {
/// The item identifier
id: String,
},
/// List all items with pagination
#[returns(ItemsResponse)]
Items {
/// Start after this ID for pagination
start_after: Option<String>,
/// Maximum number of items to return
limit: Option<u32>,
},
}
```
**Guidelines:**
- Always include `#[returns(ResponseType)]` attribute
- Use noun-based names for queries
- Include pagination for list queries (`start_after`, `limit`)
- Derive `QueryFns` and `QueryResponses`
### Response Types
```rust
#[cosmwasm_schema::cw_serde]
pub struct ConfigResponse {
/// Current admin address
pub admin: Addr,
/// Whether the contract is paused
pub paused: bool,
}
#[cosmwasm_schema::cw_serde]
pub struct ItemsResponse {
/// List of items
pub items: Vec<ItemInfo>,
}
```
**Guidelines:**
- Response types should mirror what clients need
- Use specific types (Addr, Uint128) not strings
- Document all fields
## Abstract SDK Integration
Use the `app_msg_types!` macro to generate wrapper types:
```rust
use crate::contract::MyContract;
use cosmwasm_schema::QueryResponses;
// Generates ExecuteMsg, QueryMsg, InstantiateMsg wrappers
abstract_app::app_msg_types!(MyContract, MyContractExecuteMsg, MyContractQueryMsg);
```
## Documentation Standards
### Rust Doc Comments
```rust
/// Brief one-line description of the variant.
///
/// Optional longer description that explains:
/// - When to use this
/// - Side effects
/// - Related messages
///
/// # Errors
///
/// Returns `ContractError::Unauthorized` if caller is not admin.
```
### Field Documentation
Every field must have a doc comment:
- Describe what the field represents
- Mention default values if applicable
- Note any constraints (min/max values, format)
## Serde Patterns
### Optional Fields with Defaults
```rust
#[serde(default)]
pub optional_field: Option<String>,
#[serde(default = "default_limit")]
pub limit: u32,
fn default_limit() -> u32 {
10
}
```
### Flatten for Nested Configs
```rust
#[cosmwasm_schema::cw_serde]
pub struct InstantiateMsg {
#[serde(flatten)]
pub base_config: BaseConfig,
pub custom_field: String,
}
```
### Rename for JSON Clarity
```rust
#[serde(rename = "owner")]
pub owner_addr: Addr,
```
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · axone-protocol/contracts | 100 | BSD-3-Clause |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 029b683a76f8 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100api
Podaje wzorce i dobre praktyki projektowania REST API przy tworzeniu endpointów i tras. - 100cosmwasm-contract
Opisuje strukturę kontraktów Axone i wzorce Abstract SDK: szkielet i refaktoryzacja kontraktów, granice warstw, podpinanie entrypointów AppContract oraz metadane i odpowiedzi modułów. - 100rust-testing
Podpowiada wzorce testów jednostkowych, integracyjnych i danych testowych dla kontraktów CosmWasm w projekcie Axone. - 100api-design-patterns
Podaje wzorce projektowania API RESTful, obsługi błędów, wersjonowania i dobrych praktyk, także przy przeglądzie endpointów. - 100api-design-assistant
Projektuje i przegląda API, sugerując endpointy, parametry, typy zwracane i dobre praktyki, z naciskiem na REST i specyfikacje OpenAPI. - 100postgresql
Projektuje schematy specyficzne dla PostgreSQL: dobre praktyki, typy danych, indeksowanie, ograniczenia i wzorce wydajności oraz dodatkowe możliwości silnika.