diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/contract-abi.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/contract-abi.adoc index 77d4335c12..99e3b05bdc 100644 --- a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/contract-abi.adoc +++ b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/contract-abi.adoc @@ -18,6 +18,114 @@ The following is an example contract ABI: [tabs] ==== +Cairo v2:: ++ +[source,json] +---- +[ + { + "type": "impl", + "name": "CounterContract", + "interface_name": "new_syntax_test_contract::new_syntax_test_contract::ICounterContract" + }, + { + "type": "interface", + "name": "new_syntax_test_contract::new_syntax_test_contract::ICounterContract", + "items": [ + { + "type": "function", + "name": "increase_counter", + "inputs": [ + { + "name": "amount", + "type": "core::integer::u128" + } + ], + "outputs": [], + "state_mutability": "external" + }, + { + "type": "function", + "name": "decrease_counter", + "inputs": [ + { + "name": "amount", + "type": "core::integer::u128" + } + ], + "outputs": [], + "state_mutability": "external" + }, + { + "type": "function", + "name": "get_counter", + "inputs": [], + "outputs": [ + { + "type": "core::integer::u128" + } + ], + "state_mutability": "view" + } + ] + }, + { + "type": "constructor", + "name": "constructor", + "inputs": [ + { + "name": "initial_counter", + "type": "core::integer::u128" + }, + { + "name": "other_contract_addr", + "type": "core::starknet::contract_address::ContractAddress" + } + ] + }, + { + "type": "event", + "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterIncreased", + "kind": "struct", + "members": [ + { + "name": "amount", + "type": "core::integer::u128", + "kind": "data" + } + ] + }, + { + "type": "event", + "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterDecreased", + "kind": "struct", + "members": [ + { + "name": "amount", + "type": "core::integer::u128", + "kind": "data" + } + ] + }, + { + "type": "event", + "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::Event", + "kind": "enum", + "variants": [ + { + "name": "CounterIncreased", + "type": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterIncreased", + "kind": "nested" + }, + { + "name": "CounterDecreased", + "type": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterDecreased", + "kind": "nested" + } + ] + } +] +---- Cairo v1:: + [source,json] @@ -253,114 +361,6 @@ Cairo v1:: } ] ---- -Cairo v2:: -+ -[source,json] ----- -[ - { - "type": "impl", - "name": "CounterContract", - "interface_name": "new_syntax_test_contract::new_syntax_test_contract::ICounterContract" - }, - { - "type": "interface", - "name": "new_syntax_test_contract::new_syntax_test_contract::ICounterContract", - "items": [ - { - "type": "function", - "name": "increase_counter", - "inputs": [ - { - "name": "amount", - "type": "core::integer::u128" - } - ], - "outputs": [], - "state_mutability": "external" - }, - { - "type": "function", - "name": "decrease_counter", - "inputs": [ - { - "name": "amount", - "type": "core::integer::u128" - } - ], - "outputs": [], - "state_mutability": "external" - }, - { - "type": "function", - "name": "get_counter", - "inputs": [], - "outputs": [ - { - "type": "core::integer::u128" - } - ], - "state_mutability": "view" - } - ] - }, - { - "type": "constructor", - "name": "constructor", - "inputs": [ - { - "name": "initial_counter", - "type": "core::integer::u128" - }, - { - "name": "other_contract_addr", - "type": "core::starknet::contract_address::ContractAddress" - } - ] - }, - { - "type": "event", - "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterIncreased", - "kind": "struct", - "members": [ - { - "name": "amount", - "type": "core::integer::u128", - "kind": "data" - } - ] - }, - { - "type": "event", - "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterDecreased", - "kind": "struct", - "members": [ - { - "name": "amount", - "type": "core::integer::u128", - "kind": "data" - } - ] - }, - { - "type": "event", - "name": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::Event", - "kind": "enum", - "variants": [ - { - "name": "CounterIncreased", - "type": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterIncreased", - "kind": "nested" - }, - { - "name": "CounterDecreased", - "type": "new_syntax_test_contract::new_syntax_test_contract::counter_contract::CounterDecreased", - "kind": "nested" - } - ] - } -] ----- ==== == Cairo v2.3.0 changes @@ -385,7 +385,8 @@ With `v2.3.0` onwards, doing so may result in losing information. To illustrate this, consider the following example: -```rust +[source,cairo] +---- //high-level code defining the events #[event] @@ -416,7 +417,7 @@ enum MyEnum { struct MyStruct { member: u128 } -``` +---- === Variant names different from types @@ -424,7 +425,8 @@ In `v2.3.0` enum variant types can now have any name. As an example the `TestCounterIncreased` variant and the `CounterIncreased` type, as they appear in the ABI: -```json +[source,json] +---- { "type": "event", "name": "::Event", @@ -464,7 +466,7 @@ As an example the `TestCounterIncreased` variant and the `CounterIncreased` type } ] } -``` +---- When the contract emits the `TestCounterIncreased` event, for example by writing `self.emit(CounterIncreased { amount }))`, the event that is emitted has the following keys and data: @@ -481,17 +483,19 @@ The serialization to keys and data is the same in both cases, so this example wi This example shows the `TestEnum` variant entry inside Event: -```json +[source,json] +---- { "name": "TestEnum", "type": "::MyEnum", "kind": "nested" } -``` +---- This example shows the `MyEnum` event entry: -```json +[source,json] +---- { "type": "event", "name": "::MyEnum", @@ -504,11 +508,12 @@ This example shows the `MyEnum` event entry: } ] } -``` +---- This example shows the `MyStruct` event entry: -```json +[source,json] +---- { "type": "event", "name": "::MyStruct", @@ -521,7 +526,7 @@ This example shows the `MyStruct` event entry: } ] } -``` +---- [NOTE] ==== @@ -545,7 +550,8 @@ Allowing variants that are themselves enums (`TestEnum` is an enum variant here) For example, if the high level code is changed to: -```rust +[source,cairo] +---- #[event] #[derive(Drop, starknet::Event)] enum Event { @@ -569,15 +575,15 @@ enum AnotherEnum { struct MyStruct { member: u128, } - -``` +---- then `self.emit(Event::TestEnum(MyEnum::Var1(AnotherEnum::Var2(MyStruct { member: 5 }))))` (as before, `Into` implementations can shorten this) will emit an event with `keys = [sn_keccak(TestEnum), sn_keccak(Var1), sn_keccak(Var2)]` and `data=[5]`. This will look as follows in the ABI (only the relevant parts are shown): -```json +[source,json] +---- { "type": "event", "name": "::Event", @@ -615,7 +621,7 @@ This will look as follows in the ABI (only the relevant parts are shown): } ] } -``` +---- As `TestEnum`, `Var1` and `Var2` are of kind `nested`, a selector should be added to the list of keys, before continuing to recursively serialize. @@ -625,7 +631,8 @@ You might not want to nest enums when serializing the event. For example, if you To avoid nesting, write the following high level code: -```rust +[source,cairo] +---- #[event] #[derive(Drop, starknet::Event)] enum Event { @@ -635,17 +642,18 @@ enum Event { #[flat] TestEnum: MyEnum } -``` +---- By writing the above, the `TestEnum` variant entry in the ABI will change to: -```json +[source,json] +---- { "name": "TestEnum", "type": "::MyEnum", "kind": "flat" } -``` +---- This means that `self.emit(Event::TestEnum(MyEnum::Var1(MyStruct {member: 5})))` will emit an event with `keys=[sn_keccak(Var1)]` and `data=[5]`. @@ -656,7 +664,7 @@ With the transition to `v2.0.0`, the contract ABI underwent some changes. Consider the following high level code that generates the ABI in the following example: -[source, rust] +[source, cairo] ---- #[starknet::interface] trait IOtherContract { @@ -738,13 +746,13 @@ mod counter_contract { Since the `CounterContract` `impl` is annotated with the `#[external(v0)]` attribute, you'll find the following `impl` entry in the ABI: -``` +[source,json] { "type": "impl", "name": "CounterContract", "interface_name": "new_syntax_test_contract::new_syntax_test_contract::ICounterContract" } -``` +---- This means that every function appearing in the `ICounterContract` interface is a possible entry point of the contract.