49 lines
2.5 KiB
Markdown
49 lines
2.5 KiB
Markdown
---
|
|
id: LSN-0019
|
|
ticket: asset-load-asset-id-int-contract
|
|
title: Asset Load ABI Must Converge with Asset Table Identity
|
|
created: 2026-03-27
|
|
tags: [asset, runtime, abi]
|
|
---
|
|
|
|
## Context
|
|
|
|
The runtime had already converged on numeric asset identity in the cartridge model:
|
|
|
|
- `AssetId` was `i32`;
|
|
- `preload` used `{ asset_id, slot }`;
|
|
- cartridge bootstrap validated preload entries against `asset_table` by `asset_id`.
|
|
|
|
The remaining inconsistency was the public runtime syscall surface. `asset.load` still accepted a string identifier plus an explicit asset kind, forcing the runtime to keep a `name_to_id` translation path alive even though `asset_table` already carried canonical identity and bank classification.
|
|
|
|
## Key Decisions
|
|
|
|
### Asset Load Asset ID Int Contract
|
|
|
|
**What:**
|
|
`asset.load` now uses the canonical runtime form `asset.load(asset_id, slot)`. The public ABI no longer accepts string asset names or an explicit `asset_type` argument.
|
|
|
|
**Why:**
|
|
Once `asset_table` exists, asset kind is derivable from `asset_id`. Keeping `asset_type` in the ABI only duplicates information and creates a second place for disagreement. Keeping string names in the load path also preserves a shadow identity model that the runtime no longer needs.
|
|
|
|
**Trade-offs:**
|
|
This is a hard cut with no compatibility layer. Legacy producers that still emit name-based asset loads must update, but the runtime stays simpler and the contract becomes unambiguous.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
- Treat `asset_table` as the single source of truth for operational asset identity.
|
|
- Infer internal bank-qualified slot routing from the resolved `AssetEntry` rather than from caller-supplied ABI fields.
|
|
- Keep human-readable names as metadata and telemetry only, not as runtime lookup keys.
|
|
|
|
## Pitfalls
|
|
|
|
- If preload, loader validation, and on-demand runtime loading use different identity forms, the system develops a split contract that is easy to document incorrectly and hard to evolve safely.
|
|
- ABI migrations that leave dual support for both names and IDs tend to preserve ambiguity longer than intended.
|
|
- Removing a public parameter such as `asset_type` may also remove previously observable error states, so tests and specs must be updated together.
|
|
|
|
## Takeaways
|
|
|
|
- When a cartridge-wide identity table already exists, public runtime surfaces should use that identity directly.
|
|
- Derivable ABI fields should not remain public inputs once the derivation source is canonical.
|
|
- Asset preload and on-demand asset load should follow the same identity model end to end.
|