v1.0.0-alpha.2

Important changes

• ⚠️breaking ⚠️ Support for Cairo 2.7.0-rc.3 for both dojo-lang and katana.
• Subscriptions with Torii can now be updated by providing an array of clauses.

What's Changed

• Update devcontainer image: v1.0.0-alpha.1 by @tarrencev in #2181
• rm useless alloy patches by @tcoratger in #2183
• move to edition 2023_11 by @remybar in #2179
• Update Katana benchmark CI by @kariy in #2184
• feat: update subscription by subscription id & multiple clauses by @Larkooo in #2176
• fix: ensure the snake case is only applied to model name by @glihm in #2185
• Bump blockifier to support Cairo 2.7 by @kariy in #2180
• bench(katana-executor): measure cached state concurrency by @kariy in #2190
• fix(dojo-lang): bump to cairo 2.7.0-rc.3 by @glihm in #2189
• fix: ensure scarb points to the correct plugin version by @glihm in #2194
• feat(dojo-bindgen): signed integers & typescript by @Larkooo in #2191
• Prepare release: v1.0.0-alpha.2 by @tarrencev in #2195
• fix(sozo): update some clap arguments by @lambda-0x in #2196
• fix(sozo): use Provider trait and avoid manifest read when possible by @glihm in #2197

Full Changelog: v1.0.0-alpha.1...v1.0.0-alpha.2

v1.0.0-alpha.1

Important changes

This new alpha brings new capabilities for Dojo at different levels:

• A new model API to interact with your models data. When a model is processed by the Dojo plugin, <ModelName>Trait and <ModelName>EntityTrait are generated. The <ModelName>Trait deals with the full model data (including the keys). The <ModelName>EntityTrait doesn't contain the key, only the data and the entity_id (currently stored with a __id field).
  They allow interacting with model's data in an efficient manner, without expanding more code at each use (which was the case using the macro):

  use path::to::MovesTrait;
  
  // Each key of the entity is a distinct parameter after the world.
  let mut moves = MovesTrait::get(world, player);
  moves.remaining -= 1;
  // They keys being present in the type, only the world is required to set the data.
  moves.set(world);
  moves.delete(world);

  If you only have to deal with entity_id instead of all the keys, you can use the <ModelName>EntityTrait:

  // The entity may come computed from the keys, or a simple `felt252` holding the value.
  let move_id = MovesTrait::entity_id_from_keys(player);
  let move_id = registered_moves[n];
  // Get in the same fashion as before, but only using the `entity_id`. This returns a `<ModelName>Entity` and not the full model with keys.
  let mut moves = MovesEntityTrait::get(world, move_id);
  moves.remaining -= 1;
  // `Update` is used over `set` to make the distinction here with a `set` where keys are used to ensure Torii
  // knows the full keys.
  moves.update(world);
  // You can also delete:
  moves.delete(world);

  Both of the traits are using the same Torii event (EntityUpdated), which makes them both usable right away in Torii with subscriptions.

  Even if available in the API, the get/set_member_name(...) are not yet available in Torii. They may not be used to now as it will compile, but Torii will not index such changes.

  The macros get!, set! and delete! are still available, and use the new functions under the hood (hence more efficient and producing less code).

  Examples: entity_id access and get.

• Namespaces have been improved, to support the re-use of models from other libraries.
  The new way to configure namespace if the following:

  [tool.dojo.world.namespace]
  default = "dojo_examples"

  Having this instead of the package name as default namespace, allow configuration across profiles.
  Now, if you need to import a library, you may want to map the namespace to choose your own:

  [tool.dojo.world.namespace]
  default = "dojo_examples"
  mappings = { "armory-Flatbow" = "dojo_examples_weapons", "bestiary" = "dojo_examples_foes" }

  In this case, you can use the mappings. You can define a mapping for a very specific model/contract using its tag (armory-Flatbow) to define its namespace into your project. Or you can choose to remap all the models/contracts using the namespace name (bestiary).

  All the other models/contracts that don't have mappings, will be using the default namespace.

  Due to compiler limitations, there are two edge cases:

  • If in your project you want to change the namespace some models/contracts using the attribute #[dojo::contract(namespace: "nm") then you will have to use #[dojo::contract(namespace: "nm", nomapping: true)] to ensure it doesn't fallback into the default namespace.
  • When you write a library that exposes models, if you want the user to be able to define mappings specific for your library or targeted models/contracts, you must define an explicit namespace using the attribute #[dojo::model(namespace: "nm")]. This way, nm will be able to be remapped by the user of your library.

  Examples: defining a library model and remapping the model's namespace specifically.

  Remember that if you want the model to be registered by sozo, you will have to declare it inside the build-external-contract as shown here. Without this, you can still using the model/contract, but it will not be registered and managed by sozo.

• Add support for Cairo features: you can now use the features (similar to rust for those familiar with the crab language). Using features, you can determine which part of a Cairo module has to be included at compile time.

  [features]
  # Default is a special feature, where you can enable some features by default without passing them explicitly.
  default = ["dungeon"]
  # Defining a feature is only adding a line like this.
  dungeon = []

  Then in the code, you can do the following:

  #[cfg(feature: 'dungeon')]
  use dungeon::Goblin;

  It is important to note that, in Cairo, you can't use the #[cfg(feature: ...)] inside a function to add/remove some statements. But can be use anywhere else (mod, use, struct, etc...).

• A new macro selector_from_tag! to compute the selector of a model/contract based on it's tag, expanded at compile time.

  let selector = selector_from_tag!("dojo_examples-Moves");

• World's contract registry: With the rework of the world to support the new model API, a contracts registry has also been added. This contract's registry allows you to query the world for a specific contract's address in a very deterministic manner.

  let (class_hash, address) = world.contract(selector_from_tag!("dojo_examples-Moves"));

  This avoid having to inject addresses during initialization, and not have to change the code each time contract's address may change.

• Scarb now allows you to use a merge strategy when defining multiple profiles. This means, for each profile you declare, all the keys that are not found for a profile will fallback on the default profile (dev). Example here.

• SDKs: With this new release, the SDKs will be updated, to ensure you have the tag as identifier for your queries and subscriptions to be compatible with the new changes.

What's Changed

• refactor: update manifest structure by @lambda-0x in #2153
• refactor(torii-grpc): empty hashed keys in subscription match all entities by @Larkooo in #2154
• feat: bump cairo and scarb to latest nightly by @glihm in #2152
• feat(dojo-bindgen): add namespace to unity bindgen by @Larkooo in #2155
• fix selector functions for models and contracts by @remybar in #2156
• chore: use version sensitive deps from katana-cairo + some unused deps clean up by @kariy in #2163
• added missing_debug_implementations lint by @g4titanx in #2016
• bump account_sdk to rev 199d87d on main by @kariy in #2165
• fix(compiler): use provided metadata to support feature flags by @lambda-0x in #2167
• feat(sozo): support for feature flags by @lambda-0x in #2112
• fix: use merge-strategy instead of copying profile by @lambda-0x in #2170
• fix(sozo): remove generate overlay command by @lambda-0x in #2168
• fix(sozo): ensure overlays can support any resource type by @glihm in #2169
• refactor(katana-db): database transaction abstractions by @kariy in #2171
• refactor(katana-db): main database trait by @kariy in #2173
• refactor(torii): remove executor from world table & write class hash by @Larkooo in #2166
• feat: add support for model from other libraries by @glihm in #2172
• feat(core): model get/set functions by @remybar in #2159
• fix cairo file metadata for contracts and models by @remybar in #2175
• feat: add support for signed integers by @EjembiEmmanuel in #2161
• Prepare release: v1.0.0-alpha.1 by @tarrencev in #2178

New Contributors

• @g4titanx made their first contribution in #2016

Full Changelog: v1.0.0-alpha.0...v1.0.0-alpha.1

v1.0.0-alpha.0

1.0.0-alpha.0

Introduction to namespaces

First alpha for Dojo 1.0.0 comes with the namespaces for contracts and models, which is the latest major changes that was expected to walk toward stabilisation.

This implies that anytime one wants to refer to a contract or a model, the namespace + the name of the contract/model must be provided. For this, a new term is introduce: a tag.

A tag is a unique identifier of a contract/model containing the namespace and the name separated by -:
dojo_examples-actions or dojo_examples-Position.

For model names, the regex is [_a-zA-Z] enforced by Cairo syntax. The exact same regex is expected for the namespace, and will be enforced by sozo (currently not enforced by the contract, but torii will be updated to ignore any invalid namespace and sozo to emit error).

To provide a namespace:

#[dojo::model(namespace: "ns")]
struct MyModel {
...
}

#[dojo::contract(namespace: "ns2")]
mod actions {
...
}

Or at the project level, into the Scarb.toml:

[tool.dojo.world]
namespace = "my_ns"

sozo commands have been updated to take in account the tag, or if no namespace is given, the default namespace is used from the Scarb.toml.

# Before
sozo execute dojo_examples::actions::actions spawn

# Implicit default namespace
sozo execute actions spawn

# Explicit namespace
sozo execute nm2-other_contract spawn

torii has also been updated to use this tag in order to query a specific model, and every model returned by torii now contains the tag instead of the name of the model.

Other important updates

• The compiler bug has been fixed, now the diagnostics are pointing correctly to the line with the actual error.
• The new Felt type from starknet-io/types-rs is now supported all over the stack.
• In the Scarb.tom, two new entries inside [tool.dojo.world] are required: namespace and seed. Before the seed was the package name. However, this package name is not configurable by profile. Now you can adjust it depending on the profile (same for namespace).
• The overlays folder is now at the same level of the manifests one. This ensures nothing that is user-edited can be deleted while cleaning the manifests.

Coming work

• Language server is now better as all macros are recognized, but still not fully functional (not giving in red all errors inside dojo contract). We need to wait some updates on that from dependencies.
• SDKs are currently being updated, soon they will offer full support for 1.0.0-alpha.x.
• Support for libraries (like Origami), to ensure that a namespace can be override to ease the re-use of models declared in an other library.
• A big bump to the devX with a new syntax that will come to complement macro usage: #2138.
• Support for signed integers.
• Contract registry to not hard code addresses and call an other system easily.

What's Changed

• feat: sozo init remove git by @EjembiEmmanuel in #2139
• fix: override block_id method of ConnectedAccount for SozoAccount by @lambda-0x in #2140
• feat(katana): add better node bindings by @kariy in #2142
• refactor(katana-runner): use the new bindings by @kariy in #2143
• breaking: Felt type migration + 0.7.1 RPC update by @kariy in #2126
• fix(katana-node-bindings): use new Felt by @glihm in #2146
• docs(katana-node-bindings): add json log docs by @kariy in #2145
• feat: namespaces by @glihm in #2148
• fix: ensure metadata loading errors are correctly logged by @glihm in #2149
• Prepare release: v1.0.0-alpha.0 by @tarrencev in #2150

New Contributors

• @EjembiEmmanuel made their first contribution in #2139

Full Changelog: v0.7.3...v1.0.0-alpha.0

v0.7.3

Important notes

This release is mostly for Torii stability and availability on Slot.

• New composite clause support.
• More flexibility on the key filtering for subscriptions.
• Fix pending block indexing when receipt is missing, mostly for public networks.

What's Changed

• chore(torii-libp2p): use rev by @Larkooo in #2104
• test(katana): messaging e2e test by @fabrobles92 in #1925
• fix(torii): ensure torii doesn't stop on model processor fail by @glihm in #2093
• feat(katana): always include Controller class by default by @kariy in #2107
• feat(torii-core): add entities deletions to susbcription broker by @Larkooo in #2106
• Prepare release: v0.7.3-alpha.1 by @tarrencev in #2110
• feat(torii-grpc): support multiple entity models in queries & complex keys clause for subscriptions + queries by @Larkooo in #2095
• dev: clean up dependencies by @lambda-0x in #2102
• fix(torii-client): emtpty sub for event message by @Larkooo in #2115
• feat(saya): load starknet account from CLI by @neotheprogramist in #2054
• feat(torii-grpc): composite query by @Larkooo in #2113
• fix(torii-core): update entity timestamp on update by @Larkooo in #2118
• refactor(torii-client): remove storage packed size check by @Larkooo in #2116
• refactor(torii-grpc): use Option for felt as keys wildcard by @Larkooo in #2119
• fix(torii-core): silently retry fetching pending txn until we have it by @Larkooo in #2125
• fix unsafe precondition check by @tcoratger in #2129
• chore: remove dbg! macro by @kariy in #2131
• Prepare release: v0.7.3 by @tarrencev in #2133

Full Changelog: v0.7.3-alpha.0...v0.7.3

v0.7.3-alpha.0

What's Changed

• Update devcontainer image: v0.7.2 by @tarrencev in #2091
• feat(torii-grpc): add events subscription by @Larkooo in #2065
• refactor(sozo): use a wrapper type as the concrete account type by @kariy in #2068
• fix(sozo): dev subcommand by @lambda-0x in #2080
• [saya] Publish proof to Celestia by @neotheprogramist in #2053
• feat(sozo): add Cartridge's Controller-based account by @kariy in #2069
• feat(katana): injects controller account in genesis config by @kariy in #2089
• Prepare release: v0.7.3-alpha.0 by @tarrencev in #2103

Full Changelog: v0.7.2...v0.7.3-alpha.0

v0.7.2

Notable changes

This release is mostly including Torii server updates to handle deletion or models and arrays inside models in a better way. Indexation do the pending block should also be enhanced.

What's Changed

• Update devcontainer image: v0.7.1 by @tarrencev in #2077
• fix(torii): handle array of unknown enum variants and empty arrays by @Larkooo in #2078
• refactor(torii): delete entity in all tables & array references for entity delete! by @Larkooo in #2072
• fix(katana-rpc): only include successful transactions in pending block by @kariy in #2082
• refactor(torii-core): ignore invalid txs that are included in the pending block by @Larkooo in #2081
• Prepare release: v0.7.2 by @tarrencev in #2090

Full Changelog: v0.7.1...v0.7.2

v0.7.1

Notable changes:

1. Fix of the namespace compilation issue for library like Origami. Now the sozo build command is supported again for namespaces, but other commands are not, which is expected for the moment. A future support for --package option will come.
2. Fix of the Dojo binaries that had some dependencies not using rustls-tls, which caused issues with slot. This version should now be compatible and a new test in the CI will ensure this is correctly checked before the version can be released.
3. self and world param can be used but in a exclusive manner. So until you need it, you should inject the world using world param. If required by some cairo trait like generate_trait, you can still use self inside a dojo::contract.
4. Fix of array handling in unity SDK for Torii.

What's Changed

• Update devcontainer image: v0.7.0 by @tarrencev in #2052
• fix(dojo-bindgen): array length before array items by @Larkooo in #2060
• fix(torii): fix table name using reserved sql keywords by @Larkooo in #2062
• refactor(sozo): dont use explicit account type by @kariy in #2061
• fix(sozo): allow sozo build in workspace and proper error for other cases by @glihm in #2059
• fix(migrate): when init_calldata depends on contract that was already deployed by @lambda-0x in #2058
• fix(ci): ensure katana runs in debian:bookworm-slim by @tarrencev in #2073
• [dojo-core]: update gas logs by @notV4l in #1877
• Prepare release: v0.7.1 by @tarrencev in #2076
• fix: allow the use of self and world in an exclusive manner by @glihm in #2063

Full Changelog: v0.7.0...v0.7.1

v0.7.0

Notable changes

1. Stabilizing the toolchain components to support the new types, mainly on Torii database and subscriptions.
2. Bug fix that prevented Torii client to work with gRPC on Firefox and Safari.
3. ⚠️ BREAKING ⚠️ Enforce the use of world injection in both dojo interfaces and systems implementations. Also, the ABI generated for the Dojo contract will output the correct state mutability of the systems depending on if ref world: IWorldDispatcher or world: @IWorldDispatcher is injected. You can find an example in the repo where both the interface and the implementation injects the world to generate an external function (most systems will be external).
4. You can now skip the migration of some contracts based on the profile.
5. Saya scheduler is integrated to the toolchain.

Known issues

• When a compilation error occur inside a Dojo contract, the diagnostic gives the line of the attribute instead of the accurate line.
• The language server is still being worked on.

The book is being updated, and the next two weeks will have the focus mainly on shipping the namespaces and starknet foundry testing among other things.

What's Changed

• Update devcontainer image: v0.7.0-alpha.5 by @tarrencev in #2019
• fix: reenable metadata upload test by @glihm in #2022
• feat(torii-grpc): finalize join sql query to support new layout by @Larkooo in #2017
• feat(sozo): make few argument global by @lambda-0x in #2029
• fix: metadata update use bytearray by @Larkooo in #2031
• feat(torii-libp2p): support new layout types for SNIP-12 typed data by @Larkooo in #2032
• feat(sozo): add a subcommand to generate overlay files by @lambda-0x in #2025
• update dead links by @taikoonwang in #2036
• [saya] Scheduler by @neotheprogramist in #1917
• feat(spawn-and-move): modify example to take use of new layout for offchain msg by @Larkooo in #2042
• [dev] add foundry tools to the dev container by @glihm in #2045
• refactor(torii-libp2p): use cainome + integration test by @Larkooo in #2044
• fix: fix RPC version checking by @glihm in #2048
• fix(ci): add missing path to foundry binaries by @glihm in #2051
• [trick] to unlock toriiClient with safari/firefox by @notV4l in #2038
• feat(dojo-bindgen): 2d+ arrays, bytearrays and enums serialization by @Larkooo in #2028
• feat(core): add state mutability computation from world param by @glihm in #2049
• feat: ability to skip migration of certain contracts/models by @lambda-0x in #2026
• Prepare release: v0.7.0 by @tarrencev in #2055
• fix: ensure pkg-config is also installed by @glihm in #2056

New Contributors

• @taikoonwang made their first contribution in #2036

Full Changelog: v0.7.0-alpha.5...v0.7.0

v0.7.0-alpha.5

Notable changes

1. Bug fix on dojoup script which was stuck after the installation of the binaries + help message not displayed.
2. Bug fix to ensure any package of dojo can be built separately without error.
3. Sozo now supports init calldata. The concept is the following: you can now define a dojo_init function into your dojo contracts. This function will be callable only once, at the moment where the contract is deployed (in the same transaction). Once again, the overlays inside manifests are used for that purpose. Only two variables are currently available, to get contract_address and class_hash of an other contract in the world. More info to come in the book.
4. Sozo now supports some prefixes to pass call data with execute (use sozo execute --help for more info):
   • u256
   • sstr: short string (31 chars)
   • str: long string (ByteArray)
   • Any other item is processed as a felt
5. Sozo model commands have been reworked + a new layout command:
   • sozo model schema <ModelName>: retrieves the schema of a model to see the types from the on-chain data.
   • sozo model layout <ModelName>: shows the computed layout in memory for your model. This gives you a detailed view of the number of bits used by each fields, and if packed, it gives you the exact bits layout. You can use this command on Position and Moves of the spawn-and-move example to see the differences between layouts.
   • sozo model get <ModelName> <KEYS>: retrieves the data on-chain from the dojo storage of the world for the given model and keys.
6. A new derive attribute IntrospectPacked is now required to be derived on each struct inside a model you want to be packed by dojo. As a recall, IntrospectPacked models are stored with all the fields sequentially (as dojo did initially), which has the benefit of a very short footprint in the storage, but less flexibility for model upgrade. You have an example in the repo.
7. Torii now supports indexing models with multidimensional arrays.

Targeted features for for the 0.7.0 (which will ends up being the first iteration for 1.0):

• Cairo 2.6 support (currently only a CI problem to be fixed to ensure correct publication of the releases.
• New storage layout [1/2] with: Nested structs, Array<T>, ByteArray.
• New storage layout [2/2] with: Enums rework to fully support custom enumeration without the same type limitation we currently have.
• Sozo support for constructor / initializer pattern with arguments.
• Update of Torii to support the new types + the new storage layout.
• Starknet foundry for testing
• Namespaces to register / access models.

What's Changed

• Update devcontainer image: v0.7.0-alpha.4 by @tarrencev in #1991
• Katana and ArgentX wallet by @Matth26 in #1958
• chore: remove debug log by @Larkooo in #1996
• Update README.md - Getting Started Link by @mgrunwaldt in #2000
• Unified crate for Cairo deps used in Katana by @kariy in #1999
• docs(sozo): update error message for more context by @lambda-0x in #2005
• refactor(torii-core): fix double pending indexing & use btreemap for sorted blocks by @Larkooo in #2009
• fix(torii-grpc): layout decoding by @Larkooo in #2011
• feat: init calldata for dojo contract by @lambda-0x in #1964
• Sozo model layout and commands by @remybar in #2002
• feat(torii-core): multi dimensional array support by @Larkooo in #1994
• feat(sozo): in build stats add bytecode and class size of casm class by @lambda-0x in #2004
• [dojo-core] use const array for pow2 by @notV4l in #1878
• feat: katana runner log path option by @EvolveArt in #2015
• fix: scarb bump for LS by @glihm in #2012
• feat(dojo-bindgen): support new layout types by @Larkooo in #1954
• Prepare release: v0.7.0-alpha.5 by @tarrencev in #2018

New Contributors

• @mgrunwaldt made their first contribution in #2000

Full Changelog: v0.7.0-alpha.4...v0.7.0-alpha.5

v0.7.0-alpha.4

⚠️ Breaking changes ⚠️

Before diving into the storage layout in detail, some breaking changes and features:

1. Models are now defined with an attribute instead of a derive. #[dojo::model]. This will allow in the future to have some additional inputs to this attribute. Example in spawn-and-move.
2. Before, the models were identified by their name. Now, they are identified by the selector of their name. This breaks the storage slot computation for a model. We will present in a subsequent PR/documentation how backward compatibility can be achieved if it’s still necessary.
3. Sozo now supports from prefixes to pass a call data: u256, sstr for short string, str for ByteArray. sozo execute --help for details and examples. If you need an other prefix, please don't hesitate to open a PR by implementing the decode trait as shown here or an issue.

Important notes on the storage layout

The book will also be updated once the version is stabilized.

1. You can now use ByteArray, Array and Option into models as show in the example. The nested level for array is for now 1 dimension (Torii limitation), but will soon be unlocked for arrays with multiple dimensions.
2. Enumerations can now have variants with different types (including the new supported types).
3. Introspect is now automatically derived for any struct with the model attributes. However, if you want to have the same behavior as the dojo storage before (all the fields packed sequentially), you should derive IntrospectPacked instead.
4. At the moment, you can't have a model inside an other model. You should use intermediate structs instead.
5. Models keys are only primitive type for now. You can’t use a ByteArray, Array or an other structure as key. ByteArray should be unlocked in the future.
6. In an Option<T>, the inner type T can’t be a tuple. An easy workaround is to use a struct instead.
7. GraphQL is still in iteration to support any type combination, please report any model that is not indexed by Torii and served correctly with GraphQL schemas. Here are some example of new type query. Tuples are different than array, you must use the index prefixed with _.

# Array<Vec2>
array {
  x
  y
}

# Option<Vec2>
enum {
  # inner type
  Some {
    x
    y  
  }
  option
}

# (u8, Vec2)
tuple {
  _0
  _1 {
    x
    y
  }
}

# ByteArray
bytearray

9. #1989 will be re-open targeting main to add new sozo commands and give more insights on the storage layout and schema for a model to ensure you can inspect how models are stored precisely.

Targeted features for for the 0.7.0 (which will ends up being the first iteration for 1.0):

• Cairo 2.6 support (currently only a CI problem to be fixed to ensure correct publication of the releases.
• New storage layout [1/2] with: Nested structs, Array<T>, ByteArray.
• New storage layout [2/2] with: Enums rework to fully support custom enumeration without the same type limitation we currently have.
• Sozo support for constructor / initializer pattern with arguments (#1964)
• Update of Torii to support the new types + the new storage layout.
• Starknet foundry for testing
• Namespaces to register / access models.

What's Changed

• Remove sozo as a dependency of katana-runner crate by @kariy in #1988
• Update devcontainer image: v0.7.0-alpha.3 by @tarrencev in #1961
• [Katana] Allow choosing the class in the genesis file without affecting the actual class hash by @Yogalholic in #1975
• refactor(katana): replace cursor-based api with by block basis for simplicity by @kariy in #1986
• Refactor saya to fetch the traces using the new API by @kariy in #1987
• Add doc comments for L1HandlerTx by @kariy in #1980
• fix(katana): l1/l2 messaging hash computations by @kariy in #1981
• feat: new layout support by @Larkooo in #1970
• Prepare release: v0.7.0-alpha.4 by @tarrencev in #1990

New Contributors

• @Yogalholic made their first contribution in #1975

Full Changelog: v0.7.0-alpha.3...v0.7.0-alpha.4