Voltar para Documentação

Docs Técnicas

Intrinsic Reference

All intrinsics are built into the TREA runtime. You cannot shadow them with function definitions. Collection intrinsics (vec_*, map_*) return new values — assign the result back to the storage field to persist the change.

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

All intrinsics are built into the TREA runtime. You cannot shadow them with function definitions. Collection intrinsics (vec_*, map_*) return new values — assign the result back to the storage field to persist the change.

Context

Read-only fields injected at execution time. Available in any entrypoint body.

| Name | Type | Description | | ---- | ---- | ----------- | | ctx.caller | Address | Account that submitted the ContractCall transaction | | ctx.block_timestamp | u64 | Deterministic block timestamp (unix seconds) | | ctx.block_height | u64 | Block height at execution time | | ctx.asset | AssetId | Asset selected for the contract call | | ctx.tx_id | String | Current transaction id — use as lineage key for receipts | | ctx.contract_id | String | Current contract instance id | | ctx.family_id | String | Contract family id (shared across versions) | | ctx.version_id | String | Accepted contract version id for this party |

Context Methods

| Intrinsic | Signature | Returns | Description | | --------- | --------- | ------- | ----------- | | ctx.vault | () | Address | Deterministic implicit vault address for the current contract |

Context KYC Queries

These read deterministic ledger KYC state. They never fetch private evidence from a validator during contract execution.

| Intrinsic | Signature | Returns | Description | | --------- | --------- | ------- | ----------- | | ctx.kyc_verified | (account: Address) | bool | Active, non-revoked verified state | | ctx.kyc_level | (account: Address) | KycLevel | Comparable KYC level | | ctx.kyc_compat | (account: Address, schema: String) | bool | Schema compatibility check | | ctx.kyc_verifier | (account: Address) | Address | Verifier address for the public status | | ctx.kyc_expires_at | (account: Address) | u64 | Expiration timestamp or 0 |

Guards

python
require(condition, "label")       # abort unless condition is True
assert(condition, "label")        # same semantics; use for invariants
fail("label")                     # unconditional abort
fail("label", "detail_message")   # abort with extra detail

require and assert are semantically identical — prefer require for caller-visible preconditions and assert for internal invariants.

Events

python
emit EventName(field1, field2, ...)

Events are declared in the contract body with @event. Emitting a declared event persists it to the execution output. Undeclared event names are rejected at verification.

Journal

send

python
send(amount, from_address, to_address)

Simple balance movement. Lowers to available credit/debit lines (EQ3_4 residual). Use when the posting structure is balance-in / balance-out with no obligation recognition.

post

python
post(plan)

Emit an explicit governed posting plan produced by a posting intrinsic. The ledger validates the plan against the AllowedEdge graph before commit.

line\_generator

python
line_generator(owner, bucket, op, amount)

Build a single posting line. Compose with lines_generator.

| Param | Type | Description | | ----- | ---- | ----------- | | owner | Address | Account that owns the bucket movement | | bucket | String | Chart-of-accounts bucket code | | op | String | Operation kind label | | amount | u128 | Amount |

lines\_generator

python
lines_generator(asset, operation_kind, line1, line2, ...)

Assemble a posting plan from explicit lines. Pass lines produced by line_generator.

Collections — Vec

Vectors are ordered, bounded, sparse-persisted lists. Declare with Vec[T, max] in storage. All vec intrinsics are pure — assign the result back to persist:

python
self.items = vec_push(self.items, new_item)

| Intrinsic | Signature | Returns | Description | | --------- | --------- | ------- | ----------- | | vec_push | (vec, item) | Vec | New vec with item appended | | vec_pop | (vec) | Vec | New vec with last element removed | | vec_len | (vec) | u64 | Current element count | | vec_get | (vec, index: u64) | T | Element at index; fails if out of bounds | | vec_contains | (vec, value) | bool | True if value is present |

Iteration — use a for loop:

python
for item in self.items:
    emit Seen(item)

Collections — Map

Maps are sparse key→value stores. Declare with Map[K, V, max] in storage. All map intrinsics are pure — assign the result back to persist:

python
self.balances = map_set(self.balances, owner, amount)

Missing keys return the zero default, not an error.

| Intrinsic | Signature | Returns | Description | | --------- | --------- | ------- | ----------- | | map_get | (map, key) | V | Value for key, or zero default if absent | | map_set | (map, key, value) | Map | New map with key → value | | map_remove | (map, key) | Map | New map with key deleted | | map_contains | (map, key) | bool | True if key has a non-default entry | | map_len | (map) | u64 | Number of non-default entries |

Corrections

Corrections bind a new posting plan to a source transaction id. Use ctx.tx_id from the original transaction as source_tx_id.

python
reverse(source_tx_id, asset, operation_kind?, line1, ...)
reversal(source_tx_id, asset, operation_kind?, line1, ...)  # alias for reverse
counterpost(source_tx_id, asset, operation_kind?, line1, ...)
reclassify(source_tx_id, asset, line1, line2)

| Intrinsic | Effect | | --------- | ------ | | reverse / reversal | Full reversal of original posting | | counterpost | Partial or offsetting counterpost | | reclassify | Move from one bucket to another within same account |

Loan

python
loan.accrue_interest(principal, rate_ppm, from_ts, to_ts) -> u128

Deterministic interest calculation. rate_ppm is the annual rate in parts-per-million. from_ts / to_ts are unix timestamps (seconds). Returns accrued amount as u128.

python
loan.origination_lines(asset, lender, borrower, amount) -> PostingPlan
loan.accrual_lines(asset, lender, borrower, amount)     -> PostingPlan
loan.repayment_lines(asset, lender, borrower, amount)   -> PostingPlan

Each produces a canonical double-entry posting plan:

| Intrinsic | Operation kind | Ledger effect | | --------- | -------------- | ------------- | | loan.origination_lines | LoanOrigination | Disbursement — lender available → borrower available | | loan.accrual_lines | LoanAccrual | Accrue receivable on lender, payable on borrower | | loan.repayment_lines | LoanRepayment | Settle accrued obligation and reduce principal |

Pass the result to post(...).

Financial Balance Helpers

| Intrinsic | Signature | Returns | Description | | --------- | --------- | ------- | ----------- | | credit | (position: Balance[T], amount: u128) | statement | Increase tracked balance | | debit | (position: Balance[T], amount: u128) | statement | Decrease tracked balance; underflow fails | | amount_of | (position: Balance[T]) | u128 | Read tracked balance |

credit must be justified by a matching debit or a recognized ctx.* issuance source in the same transaction. Plain integer math is not money.

Spending Intent

python
spending.verify_intent(card_pubkey, card_curve, vault_id, merchant,
                       token_id, amount, nonce, expires_at,
                       signed_intent) -> bool

Verifies a PaymentIntentV1 ECDSA signature over the canonical card payload. Supported curves are secp256k1 and p256.

Factory

python
derive_child_id(template_id: String, requester: Address, salt: String) -> Address

Returns the deterministic child contract id used by std.factory.ProductTemplate.

Fees

python
fees.charge_lines(asset, payer, payee, amount)         -> PostingPlan
fees.accrual_lines(asset, payer, payee, amount)        -> PostingPlan
fees.settlement_lines(asset, payer, payee, amount)     -> PostingPlan

| Intrinsic | Description | | --------- | ----------- | | fees.charge_lines | Direct fee charge (available swap — no obligation recognition) | | fees.accrual_lines | Recognize fee obligation (receivable on payee, payable on payer) | | fees.settlement_lines | Settle accrued fee obligation |

Yield

python
yield.accrue_interest(principal, rate_ppm, from_ts, to_ts) -> u128
yield.accrual_lines(asset, issuer, holder, amount)         -> PostingPlan
yield.realization_lines(asset, issuer, holder, amount)     -> PostingPlan

yield.accrue_interest uses the same formula as loan.accrue_interest.

| Intrinsic | Description | | --------- | ----------- | | yield.accrual_lines | Recognize yield entitlement (payable on issuer, receivable on holder) | | yield.realization_lines | Settle yield entitlement in cash |

Installments

python
installments.schedule_lines(asset, debtor, creditor, amount)  -> PostingPlan
installments.payment_lines(asset, debtor, creditor, amount)   -> PostingPlan

| Intrinsic | Description | | --------- | ----------- | | installments.schedule_lines | Recognize installment obligation | | installments.payment_lines | Settle one scheduled installment |

FX

python
fx.conversion_lines(asset, seller, buyer, amount) -> PostingPlan

Governed FX conversion posting for one leg of a currency swap. Both legs must be posted in separate ContractCall transactions or within the same contract call if the contract holds both sides.

Insurance

python
insurance.premium_lines(asset, insured, insurer, amount)    -> PostingPlan
insurance.reserve_lines(asset, insurer, beneficiary, amount) -> PostingPlan
insurance.payout_lines(asset, insurer, beneficiary, amount)  -> PostingPlan

| Intrinsic | Description | | --------- | ----------- | | insurance.premium_lines | Insured pays insurer (available swap) | | insurance.reserve_lines | Insurer locks available into payable reserve | | insurance.payout_lines | Settle claim from reserve to beneficiary |

Provisioning Loss

python
provisioning_loss.provision_lines(asset, debtor, creditor, amount)  -> PostingPlan
provisioning_loss.writeoff_lines(asset, debtor, creditor, amount)   -> PostingPlan
provisioning_loss.recovery_lines(asset, debtor, creditor, amount)   -> PostingPlan

| Intrinsic | Description | | --------- | ----------- | | provision_lines | Reduce receivable and create loss provision | | writeoff_lines | Permanent loss recognition | | recovery_lines | Restore receivable on cash recovery |

NFA (Non-Fungible Assets)

python
nfa.transfer_lines(asset, from, to, amount)     -> PostingPlan
nfa.encumber_lines(asset, owner, reserve, amount) -> PostingPlan
nfa.release_lines(asset, owner, reserve, amount)  -> PostingPlan

| Intrinsic | Description | | --------- | ----------- | | nfa.transfer_lines | Non-fungible asset title transfer | | nfa.encumber_lines | Lock available into payable reserve | | nfa.release_lines | Release from reserve back to available |

Emit

python
emit Name(arg1, arg2, ...)

Emits a declared @event. Events must be declared in the contract body before use. Emitting an undeclared event is a verifier error. Events do not affect storage or postings — they are audit annotations on the execution output.