Skip to content

Finish canoto Migration #2037

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 33 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
e88ad71
migrate morpheusvm to canoto
RodrigoVillar Apr 27, 2025
1ea0777
migrate tests to new abi
RodrigoVillar Apr 27, 2025
87efcb9
migrate vm
RodrigoVillar Apr 27, 2025
29f6d2d
migrate api
RodrigoVillar Apr 27, 2025
ad3aae9
migrate auth
RodrigoVillar Apr 27, 2025
2f99ffc
remove type parser
RodrigoVillar Apr 27, 2025
d6951d3
rename to canotoParser
RodrigoVillar Apr 27, 2025
db4b8ff
migrate abi
RodrigoVillar Apr 27, 2025
140bf6b
migrate bls
RodrigoVillar Apr 28, 2025
a5643b3
morpheusvm nit
RodrigoVillar Apr 28, 2025
48b1eba
calculateCanotoCache nit
RodrigoVillar Apr 28, 2025
d4e5d3d
migrate cmd
RodrigoVillar Apr 28, 2025
ad3494a
nit
RodrigoVillar Apr 28, 2025
c8430ec
auth nit
RodrigoVillar Apr 28, 2025
90b41cd
migrate abi + chain
RodrigoVillar Apr 28, 2025
2afef59
go mod nit
RodrigoVillar Apr 28, 2025
fa09a38
go mod tidy
RodrigoVillar Apr 28, 2025
81148b5
Merge branch 'main' into finish-canoto-migration
RodrigoVillar Apr 28, 2025
a09f292
migrate indexer client
RodrigoVillar Apr 28, 2025
d79ab8a
migrate chain
RodrigoVillar Apr 28, 2025
006737c
remove serialize
RodrigoVillar Apr 28, 2025
0dbe668
abi pointer nit
RodrigoVillar Apr 28, 2025
f16d281
migrate abi
RodrigoVillar Apr 28, 2025
2747cfd
Merge branch 'main' into finish-canoto-migration
RodrigoVillar Apr 28, 2025
b3cbd5a
update READMEs
RodrigoVillar Apr 28, 2025
3b033c0
testParser nit
RodrigoVillar Apr 28, 2025
1988bbf
update README
RodrigoVillar Apr 28, 2025
dafc83b
README nit
RodrigoVillar Apr 28, 2025
39de484
morpheusVM nit
RodrigoVillar Apr 28, 2025
4bf762a
consistent usage of ok
RodrigoVillar Apr 28, 2025
7aa7526
clean up cli
RodrigoVillar Apr 28, 2025
f6d8b38
cmd lint
RodrigoVillar Apr 28, 2025
35e44a9
auth nit
RodrigoVillar Apr 28, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 39 additions & 71 deletions abi/README.md
Original file line number Diff line number Diff line change
@@ -1,98 +1,66 @@
# ABI Package

## Overview
The ABI package provides functionality for marshaling and unmarshaling actions. It is designed to work across different language implementations.
The ABI package provides functionality for marshaling and unmarshaling actions.
It uses the [Canoto](https://github.com/StephenButtolph/canoto) serialization
protocol and is designed to work across different language implementations.

## ABI Format
The ABI is defined in JSON format, as shown in the `abi.json` file:
```json
{
"actions": [
"actionsSpec": [
{
"id": 1,
"action": "MockObjectSingleNumber"
},
"name": "TestAction",
"fields": [
{
"fieldNumber": 1,
"name": "NumComputeUnits",
"typeUint": 4
},

]
}
],
"types": [
"outputsSpec": [
{
"name": "MockObjectSingleNumber",
"name": "TestOutput",
"fields": [
{
"name": "Field1",
"type": "uint16"
}
"fieldNumber": 1,
"name": "Bytes",
"typeBytes": true
},
]
},
}
],
"actionTypes": [
{
"name": "TestAction",
"id": 0
}
],
"outputTypes": [
{
"name": "TestOutput",
"id": 0
}
]
}
```

The ABI consists of two main sections:
- actions: A list of action definitions, each with a typeID and action name (action name specifies the type)
- types: A dictionary of types including their name and corresponding fields

The type in each field must either be included in the ABI's `types` or in the list of [Supported Primitive Types](#supported-primitive-types).

## Test Vectors
This implementation provides `testdata/` for implementations in any other language.

To verify correctness, an implementation can implement the following pseudocode:
```
abi = abi.json

for filename in testdata/*.hex:
if filename.endswith(".hash.hex"):
continue
expectedHex = readFile(filename)
json = readFile(filename.replace(".hex", ".json"))
The ABI consists of the following sections:
- `actionsSpec`: a list of action definitions, according to the Canoto specification
- `outputsSpec`: a list of output definitions, according to the Canoto specification
- `actionTypes`: a dictionary of all available actions and their corresponding typeIDs
- `outputTypes`: a dictionary of all available outputs and their corresponding typeIDs

actualHex = Marshal(abi, json)
if actualHex != expectedHex:
raise "Hex values do not match"

```
The type in an action/output field must be a [supported canoto type](https://github.com/StephenButtolph/canoto?tab=readme-ov-file#supported-types).

## ABI Verification
Frontends can use the ABI to display proper action and field names. For a wallet to verify it knows what it's signing, it must ensure that a canonical hash of the ABI is included in the message it signs.

A correct VM will verify the signature against the same ABI hash, such that verification fails if the wallet signed an action against a different than expected ABI.

This enables frontends to provide a verifiable display of what they are asking users to sign.

## Constraints
- Actions require an ID, other structs / types do not require one
- Multiple structs with the same name from different packages are not supported
- Maps are not supported; use slices or arrays instead
- Built-in type `codec.Address` included as a special case

## Generating Golang Bindings
Use cmd/abigen to automatically generate Go bindings from an ABI's JSON.

For example, to auto-generate golang bindings for the test ABI provided in `./abi/testdata/abi.json` run:

```sh
go run ./cmd/abigen/ ./abi/testdata/abi.json ./example.go --package=testpackage
```

This should generate the same code that is present in `./abi/mockabi_test.go`.

## Supported Primitive Types

| Type | Range/Description | JSON Serialization | Binary Serialization |
|-----------|----------------------------------------------------------|--------------------|---------------------------------------|
| `bool` | true or false | boolean | 1 byte |
| `uint8` | numbers from 0 to 255 | number | 1 byte |
| `uint16` | numbers from 0 to 65535 | number | 2 bytes |
| `uint32` | numbers from 0 to 4294967295 | number | 4 bytes |
| `uint64` | numbers from 0 to 18446744073709551615 | number | 8 bytes |
| `int8` | numbers from -128 to 127 | number | 1 byte |
| `int16` | numbers from -32768 to 32767 | number | 2 bytes |
| `int32` | numbers from -2147483648 to 2147483647 | number | 4 bytes |
| `int64` | numbers from -9223372036854775808 to 9223372036854775807 | number | 8 bytes |
| `Address` | 33 byte array | base64 | 33 bytes |
| `string` | string | string | uint16 length + bytes |
| `[]T` | for any `T` in the above list, serialized as an array | array | uint32 length + elements |
| `[x]T` | for any `T` in the above list, serialized as an array | array | uint32 length + elements |
| `[]uint8` | byte slice | base64 | uint32 length + bytes |
| `[x]uint8`| byte array | array of numbers | x bytes |

Loading