API 2.0 #149

avive · 2021-06-07T15:54:39Z

Draft PR to review and discuss GlobalState service changes to support Spacemesh Apps in release 0.3.

proto/spacemesh/v1/app_types.proto

proto/spacemesh/v1/global_state.proto

proto/spacemesh/v1/app_types.proto

lrettig · 2021-06-12T19:38:20Z

proto/spacemesh/v1/app_types.proto

+// Information about an app template in the global state store
+message Template {
+    TemplateAddress address = 1; // template address
+    string name = 2; // template name


See comment in issue, I don't understand why this is required

proto/spacemesh/v1/app_types.proto

lrettig · 2021-06-12T19:44:28Z

proto/spacemesh/v1/app_types.proto

+// but is convenient to return them directly as part of apps' metadata.
+message App {
+    AccountId address = 1; // App's address in global space
+    string name = 2; // short descriptive name


Do we need this?

I think it is good to have a short app name that describes it. I think that it is something that is set by spwaner and spawn time per app.

lrettig · 2021-06-12T19:44:38Z

proto/spacemesh/v1/app_types.proto

+    AccountId address = 1; // App's address in global space
+    string name = 2; // short descriptive name
+    TemplateAddress template_address = 3; // App's template address
+    LayerNumber spawn_layer = 4; // Layer in which app was spawned


Why is this needed?

Which field? These are all meta-data about an app which is useful. It is useful to know in which layer an app was deployed to the mesh although this info can be obtained from the spawn transaction - it is just convince to include some metadata that can be obtained from transactions about the app in response to this call because the intent of the caller is to get this data.

lrettig · 2021-06-12T19:45:32Z

proto/spacemesh/v1/app_types.proto

+    repeated Template templates = 2;
+}
+
+// A request to get an app's variable by var id


Instead of "variable" can we give these a more descriptive name, e.g., state entry?

@YaronWittenstein said these are called "storage variables" in SVM

lrettig · 2021-06-12T19:45:59Z

proto/spacemesh/v1/app_types.proto

+// A request to get an app's variable by var id
+message GetVariableRequest {
+    AccountId address = 1; // app's address
+    LayerNumber layer_number = 2; // requested value as of a layer. Pass MAX_UI32 to get latest value


As noted in the issue, will only work for archival nodes! What do non-archival nodes do if this is specified? Error?

See my comment there - full nodes will hold state for n layers back and archive nodes since genesis but from an api level it is good to have this like this and nodes will return not_found status if they can't satisfy this specific request for a layer which is not recent.

I think that works, but for the record, we cannot force full nodes to hold intermediate state for any minimum number of layers since this is extraprotocol

lrettig · 2021-06-12T19:46:13Z

proto/spacemesh/v1/app_types.proto

+message GetVariableRequest {
+    AccountId address = 1; // app's address
+    LayerNumber layer_number = 2; // requested value as of a layer. Pass MAX_UI32 to get latest value
+    uint32 id = 3; // app's var id - var's unique identifier


Where does the caller look this up?

Caller has the app's schema which includes the variable ids.

Add name to log entry

Co-authored-by: Lane Rettig <lanerettig@gmail.com>

avive · 2021-06-29T08:07:19Z

@lrettig @YaronWittenstein - I've updated the api to reflect the design review session feedback. I still believe we should have a strongly typed GetVariable() method which is very useful for quick access to app state by dapps. Perhaps we can proceed before another review session by you guys just reviewing the most recent changes? The relent types are in app_types.proto, var_types.proto and global_state.proto

proto/spacemesh/v1/api_config.yaml

proto/spacemesh/v1/app_types.proto

proto/spacemesh/v1/global_state_types.proto

proto/spacemesh/v1/types.proto

proto/spacemesh/v1/var_types.proto

avive · 2021-07-06T16:41:34Z

@YaronWittenstein @lrettig - please check the code - I think I've incorporated everything we talked about and removed non-app related changes from this pr.

lrettig · 2021-07-06T16:53:48Z

proto/spacemesh/v1/app_types.proto

-    string target_svm_version = 4; // at deploy time
-    string kind = 5; // e.g. WASM
-    repeated bytes code = 6; // wasm code
+    string target_svm_version = 1; // at deploy time


I think this should be an int not a string

lrettig · 2021-07-06T16:53:58Z

proto/spacemesh/v1/app_types.proto

-    string kind = 5; // e.g. WASM
-    repeated bytes code = 6; // wasm code
+    string target_svm_version = 1; // at deploy time
+    string kind = 2; // e.g. WASM


this should be an enum not a string

lrettig · 2021-07-06T17:28:32Z

proto/spacemesh/v1/app_types.proto

-    Code code = 2; // template wasm code. Provided if caller specified to get code.
-    bytes metadata = 3; // storage layout, api, header. Provided if caller specified to get metadata and template include metadata.
+    Code code = 1; // template wasm code. Provided if caller specified to get code.
+    bytes metadata = 2; // storage layout, api, header. Provided if caller specified to get metadata and template include metadata.


Suggested change

bytes metadata = 2; // storage layout, api, header. Provided if caller specified to get metadata and template include metadata.

bytes metadata = 2; // storage layout, api, header. Provided if caller specified to get metadata and template including metadata. Caller is responsible for decoding.

lrettig · 2021-07-06T17:28:56Z

proto/spacemesh/v1/app_types.proto

 }

 enum TemplateDataFlags {
    TEMPLATE_DATA_FLAGS_UNSPECIFIED = 0;
    TEMPLATE_DATA_FLAGS_CODE = 1;
    TEMPLATE_DATA_FLAGS_METADATA = 2;
+    // may need deploy data section - tbd - based on deploy tx format. Understand eth one.


Suggested change

// may need deploy data section - tbd - based on deploy tx format. Understand eth one.

// TODO: may need deploy data section - tbd - based on deploy tx format. Understand eth one.

lrettig · 2021-07-06T17:29:54Z

proto/spacemesh/v1/app_types.proto

+    AccountId address = 1; // App's address in global space
+    string name = 2; // short descriptive name (optional)
+    TemplateAddress template_address = 3; // App's template address
+    LayerNumber spawn_layer = 4; // Layer in which app was spawned


as discussed today, these also belong in metadata, as they're not required by SVM. they can optionally be automatically populated at deploy time if the deployer requests this, and pays for it.

lrettig · 2021-07-06T17:30:07Z

proto/spacemesh/v1/app_types.proto

+    repeated Template templates = 2;
+}
+
+// A request to get an app's variable by var id


@YaronWittenstein said these are called "storage variables" in SVM

lrettig · 2021-07-06T17:30:57Z

proto/spacemesh/v1/global_state_types.proto

-        TRANSACTION_RESULT_INSTANTIATION_FAILED = 9; // error creating an instance from a template
-        TRANSACTION_RESULT_DEPLOY_FAILED = 10; // error deploying a template to the mesh
+        TRANSACTION_RESULT_RUNTIME_EXCEPTION = 2; // app code execution exception=
+        TRANSACTION_RESULT_VALIDATION_FAILED = 3; // TBD


Suggested change

TRANSACTION_RESULT_VALIDATION_FAILED = 3; // TBD

TRANSACTION_RESULT_VALIDATION_FAILED = 3; // TODO: do we need this? can an invalid tx ever make it into a superblock?

avive · 2021-07-06T18:17:27Z

Renamed pr to api 2.0 as it is not going to be backward compatible with 1.x api due to some breaking changes.

lrettig · 2021-07-06T23:48:10Z

Renamed pr to api 2.0 as it is not going to be backward compatible with 1.x api due to some breaking changes.

I think we need to update this so the output proto files go into proto/spacemesh/v2 (rather than v1), that should cause the CI tests to pass. We also need to add a separate set of checks for v2, and we should also update the README accordingly.

avive added 5 commits June 7, 2021 16:06

svm types (wip)

62ab5cb

factor out app types from global state types

83788fb

rough modeling of app related api methods

28b7a9e

fix typo

79518b9

use app template address

cd3d333

avive added the feature label Jun 7, 2021

avive added this to the v1.2 milestone Jun 7, 2021

avive requested review from YaronWittenstein and lrettig June 7, 2021 15:54

avive added 2 commits June 7, 2021 19:08

Document new app related api methods

aaecca9

Build go api files

f25eca9

YaronWittenstein suggested changes Jun 8, 2021

View reviewed changes

avive added 7 commits June 8, 2021 10:21

review based changes

8b761df

review changes

30c5d77

buf check lint -> buf lint

5da4c0d

Update buf version to latest

aefa126

Add support for apps to TransactionReceipt (wip)

ba7636a

additional receipt related data items

983a1fa

Additional receipt related comments

8cb8045

lrettig requested changes Jun 12, 2021

View reviewed changes

avive and others added 10 commits June 13, 2021 13:08

Add 0.3 layer status

53928e8

Add epoch number to Activation

792b855

GlobalStateHash -> GlobalStateRoot (review feedback)

7ddfa53

Update buf syntax to remove some warnings

96c425e

Add name to log entry

Revert break non backward compatible changes

e80b2b9

meta-data -> metadata

7a5b7d7

Add app related methods http rules

17b7818

revert tx http rule

bf17959

Remove all google.rpc.Status data items - each response has it built-in

7102720

Update proto/spacemesh/v1/app_types.proto

b154129

Co-authored-by: Lane Rettig <lanerettig@gmail.com>

avive added 5 commits June 27, 2021 11:44

Update app types based on design review session

cc9a547

update app types

56fef31

size -> primitve_count

860da78

template related api changes based on design review

3712df7

app related 0.3 features - design review feedback

f523aab

refactor app types and additional comments

5c75e00

lrettig requested changes Jul 6, 2021

View reviewed changes

avive added 2 commits July 6, 2021 19:38

Update app apis based on design review session

d56ffb3

fix typo in method name

b33b286

avive added 2 commits July 6, 2021 19:46

fixed wrong field number

c7057d8

formatting

111608f

lrettig requested changes Jul 6, 2021

View reviewed changes

avive changed the title ~~Sm0.3 update (WIP)~~ API 2.0 Jul 6, 2021

avive mentioned this pull request Jul 28, 2021

API 2.0 #146

Open

YaronWittenstein mentioned this pull request Jul 29, 2021

in EVM/solidity, pretty sure this is a repeated set of field names and values rather than a single blob (per context/name) spacemeshos/svm#325

Open

dshulyak closed this Nov 9, 2023

lrettig deleted the sm0.3-update branch November 9, 2023 15:45

API 2.0 #149

API 2.0 #149

avive commented Jun 7, 2021

lrettig Jun 12, 2021

lrettig Jun 12, 2021

avive Jun 13, 2021

lrettig Jun 12, 2021

avive Jun 13, 2021

lrettig Jun 12, 2021

lrettig Jul 6, 2021

lrettig Jun 12, 2021

avive Jun 13, 2021

lrettig Jul 6, 2021

lrettig Jun 12, 2021

avive Jun 13, 2021

avive commented Jun 29, 2021

avive commented Jul 6, 2021

lrettig Jul 6, 2021

lrettig Jul 6, 2021

lrettig Jul 6, 2021

lrettig Jul 6, 2021

lrettig Jul 6, 2021

lrettig Jul 6, 2021

lrettig Jul 6, 2021

avive commented Jul 6, 2021

lrettig commented Jul 6, 2021

	bytes metadata = 2; // storage layout, api, header. Provided if caller specified to get metadata and template include metadata.
	bytes metadata = 2; // storage layout, api, header. Provided if caller specified to get metadata and template including metadata. Caller is responsible for decoding.

	// may need deploy data section - tbd - based on deploy tx format. Understand eth one.
	// TODO: may need deploy data section - tbd - based on deploy tx format. Understand eth one.

	TRANSACTION_RESULT_VALIDATION_FAILED = 3; // TBD
	TRANSACTION_RESULT_VALIDATION_FAILED = 3; // TODO: do we need this? can an invalid tx ever make it into a superblock?

API 2.0 #149

API 2.0 #149

Conversation

avive commented Jun 7, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

avive commented Jun 29, 2021

avive commented Jul 6, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

avive commented Jul 6, 2021

lrettig commented Jul 6, 2021