Skip to content

Commit

Permalink
Changed AsciiDoc source language from Rust to Cairo in contract-abi.adoc
Browse files Browse the repository at this point in the history
  • Loading branch information
stoobie committed Feb 29, 2024
1 parent 3c59244 commit 610676d
Showing 1 changed file with 29 additions and 21 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -416,15 +417,16 @@ enum MyEnum {
struct MyStruct {
member: u128
}
```
----

=== Variant names different from types

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": "<namespace>::Event",
Expand Down Expand Up @@ -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:

Expand All @@ -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": "<namespace>::MyEnum",
"kind": "nested"
}
```
----

This example shows the `MyEnum` event entry:

```json
[source,json]
----
{
"type": "event",
"name": "<namespace>::MyEnum",
Expand All @@ -504,11 +508,12 @@ This example shows the `MyEnum` event entry:
}
]
}
```
----

This example shows the `MyStruct` event entry:

```json
[source,json]
----
{
"type": "event",
"name": "<namespace>::MyStruct",
Expand All @@ -521,7 +526,7 @@ This example shows the `MyStruct` event entry:
}
]
}
```
----

[NOTE]
====
Expand All @@ -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 {
Expand All @@ -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": "<namespace>::Event",
Expand Down Expand Up @@ -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.

Expand All @@ -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 {
Expand All @@ -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": "<namespace>::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]`.

Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit 610676d

Please sign in to comment.