Voltar para Documentação

Docs Técnicas

Storage

Storage is contract-local persistent state.

O conteúdo abaixo vem das fontes técnicas do repositório e é prerenderizado no site para leitura direta por pessoas, crawlers e agentes.

Storage is contract-local persistent state.

Scalar Fields

python
storage:
    active: bool = False
    owner: Address
    principal_due: u128 = 0

Read and write with self.field:

python
self.active = True
return self.principal_due

For Address, the default empty value is only a pre-construction sentinel. Runtime writes and accounting effects reject the empty/zero address, so contracts should not use zero address as business state. Use @construct plus explicit boolean or state fields for initialization and absence.

Sparse Maps

python
storage:
    balances: Map[Address, u128, 64]

@view
def balance_of(owner: Address) -> u128:
    return self.balances[owner]

@tx
def set_balance(owner: Address, amount: u128):
    self.balances[owner] = amount

Nested sparse maps are supported for allowance-style storage:

python
storage:
    allowances: Map[Address, Map[Address, u128]]

@view
def allowance(owner: Address, spender: Address) -> u128:
    return self.allowances[owner][spender]

@tx
def approve(spender: Address, amount: u128):
    let owner = ctx.caller
    self.allowances[owner][spender] = amount

Sparse Vectors

python
storage:
    checkpoints: Vec[u64, 8]

@tx
def mark(slot: u64, value: u64):
    self.checkpoints[slot] = value

Struct Fields

python
storage:
    terms: Struct[LoanTerms{
        principal: u128,
        rate_ppm: u64,
        active: bool
    }]

Read and write individual fields with .:

python
self.terms.active = True
self.terms.principal = amount
return self.terms.rate_ppm

Struct fields are stored sparsely. Writing a field stores only that field, not the whole struct at once.

Structs cannot appear in public entrypoint parameters or return values. Use separate scalar reads to expose struct data:

python
@view
def get_principal() -> u128:
    return self.terms.principal

Default Removal

Assigning the default value to a map or vector slot removes the sparse persisted entry.

python
self.balances[owner] = 0
self.checkpoints[slot] = 0

Storage Meaning

Use storage for business state, not for fake ledger balances.

Good storage:

  • active/inactive state;
  • borrower/lender identity;
  • pending requested amount;
  • last accrual timestamp;
  • business lifecycle markers.

Bad storage:

  • a shadow of spendable ledger balance;
  • manual liability balances that should be journaled;
  • correction history that should be represented by ledger correction lineage.