[docs] bring back system-integrators-guide #5763

davidiw · 2022-12-03T20:53:13Z

rename system-integrators-guide to aptos-apis
resurrect the last full version of system-integrators-guide
update with new links stripping basics- from many docs

todo:

cleanup system-integrators-guide with links to updated documentation
add more content to system-integrators-guide covering FAQs

Description

Test Plan

* rename system-integrators-guide to aptos-apis * resurrect the last full version of system-integrators-guide * update with new links stripping basics- from many docs todo: * cleanup system-integrators-guide with links to updated documentation * add more content to system-integrators-guide covering FAQs

* I thought we agreed that we'd not use any special formatting in the docs, why are we line breaking paragraphs? we really need to standardize this :) * Add a section on addressing and full definitions. * Merge How resources are stored and parallel processing they say the same thing redundantly. The argument for indexing doesn't really make sense in this context. I think there's an attempt to get into an advanced topic but it really falls flat.

* Merge paragraphs into a single line in some cases -- this one was mixed * Improve readability of transactions by moving high level together before getting into the components and guts of a transaction * Move the txn state diagram to the end where it is discussed * Separate the content between txns, state, and txn+state * Delete "(fomerly known a script functions)" they haven't been known as that since my last craziness right before testnet freeze :D * Removed some duplicated content

* Mosty good newlines, yay * The text was a little repititious here and there, so I streamlined it a bit * Added in additional context about simulation * Information about prioritization buckets

some tweaks -- I ninja landed a larger change due to some obviously questionable text

This has morphed more into a deep dive of Aptos since it now contains two major sections. We might want to divide this into two sections. At any rate, I did some editing here to make it a bit more cohesive: * Merged assumptions into the beginning of the story * Renamed the lifecycle to journey since it was repititious with the title of the article / section * Moved client submits to after the overview of the story

I'm sure there was a reason for adding that at some point, but this belongs in an FAQ not at the end of a description about different networks

This leverage a lot of Kevin's work to move content around and make this more of an index for the first chunk of content.

this is redundant content that likely belongs in a unified onboarding guide -- like the system-integrators-guide my concern with the aptos-apis is it is bloated and we need to think about breaking it down: Have 1 page per query type: * simple resources * transactions * events * tables In each, both the indexer and REST API. We at least need to figure that out before more editting...

clay-aptos

Belatedly adding some questions to go with direct edits in:
#5795

clay-aptos · 2022-12-07T00:27:48Z

developer-docs-site/docs/concepts/staking.md


-With the configuration set in [staking_config.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move).
+The current on-chain data can be found [here](https://mainnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::staking_config::StakingConfig). With the configuration set defined in [staking_config.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move).


Will this version (`v1) persist? Redirect to latest upon upgrade? Or can we link to a generic? I want to future-proof these links.

There is no future proofing these. The V1 API is stable, there's no guarantee that the V2 API will work the same.

clay-aptos · 2022-12-07T00:33:58Z

developer-docs-site/docs/concepts/staking.md

+
+- Voting power can only change (increase or decrease) on epoch boundary.
+- A validator’s consensus key and the validator and validator fullnode network addresses can only change on epoch boundary.
+- Pending inactive stake cannot be moved into inactive (and thus withdrawable) until before lockup expires.


These many negatives in one sentence are confusing. Perhaps:
"Pending inactive stake can be moved into inactive (and thus withdrawable) only before lockup expires."

This is the original text, I think you're right though.

"Pending inactive stake cannot be move into inactive and thus withdrawable until the lockup expires."

The "before" and the "()" aren't useful.

clay-aptos · 2022-12-07T00:37:10Z

developer-docs-site/docs/concepts/txns-states.md

+
+During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise.
+
+A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted.


Are there any ramifications to this? Do we ding them for submitting duplicate transactions?

Nope there's no penalty for dropped txs

clay-aptos · 2022-12-07T00:58:14Z

developer-docs-site/docs/guides/aptos-apis.md

+
+The REST API offers querying transactions and events in these ways:
+
+* [Transactions for an account](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_account_transactions)


Should these be mainnet targets? Ex.
https://fullnode.mainnet.aptoslabs.com/v1/spec#/operations/get_account_transactions

clay-aptos · 2022-12-07T01:04:31Z

developer-docs-site/docs/guides/aptos-apis.md

+
+### Querying transactions
+
+In Aptos, each transaction is committed as a distinct version to the blockchain. This allows for the convenience of sharing committed transactions by their version number; to do so, query: `https://{rest_server_api}/transactions/by_version/{version}`


Can we define all of the possible values for rest_server_api at the top, as in mainnet, tesnet, and devnet?

clay-aptos · 2022-12-07T01:12:17Z

developer-docs-site/docs/guides/aptos-apis.md

+      "guid": {
+        "id": {
+          "addr": "0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b",
+          "creation_num": "3"


What is creation_num here? Can we define all fields in the list below?

clay-aptos · 2022-12-07T01:46:44Z

developer-docs-site/docs/guides/system-integrators-guide.md

+
+JSON-encoded transactions can be generated via the [REST API](https://fullnode.devnet.aptoslabs.com/v1/spec#/), following these steps:
+
+1. First construct an appropriate JSON payload for the `/transactions/encode_submission` endpoint as demonstrated in the [Python SDK](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L128).


Will these links to code with b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4 persist? Or should we link to the latest version?

latest version doesn't work, because if someone moves code around, the line numbers will point to random content...

We should consider instead using references to the code then:
https://blog.shhdharmen.me/announcing-github-link-get-links-to-code-in-your-github-files-based-on-text-and-forget-the-line-numbers

movekevin · 2022-12-07T07:06:52Z

developer-docs-site/docs/concepts/staking.md


-A validator can participate in the consensus process. However, the validator can acquire the voting power only when they stake, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is made proportionate to the amount of validator's stake. In exchange, the validator is rewarded in proportion to the amount of validator's stake. Hence, the performance of the network, i.e., consensus, is aligned with the validator's interest, i.e., rewards.  
+Anyone can participate in the Aptos consensus process, if they stake sufficient utility coin, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is proportional to the amount of validator's stake. In exchange, the validator is rewarded proportionally to the amount staked. Hence, the performance of the Blockchain is aligned with the validator's interest, i.e., rewards.  


nit: Why not just say APT instead of "utility coin"?

I think you wrote this document first. Note the highlighted text is my changes.

movekevin · 2022-12-07T07:07:32Z

developer-docs-site/docs/concepts/staking.md

@@ -49,6 +48,7 @@ The `OwnerCapability` resource can be used to control the stake pool. Three pers
 - Operator
 - Voter

+


Why add an empty line here?

Sometimes things happen...

movekevin · 2022-12-07T07:09:25Z

developer-docs-site/docs/concepts/txns-states.md

+
+During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise.
+
+A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted.


Nope there's no penalty for dropped txs

movekevin · 2022-12-07T07:10:01Z

developer-docs-site/docs/concepts/txns-states.md

@@ -106,25 +98,23 @@ All operations executed by the blockchain and all account states can be verified
 - The validator nodes agree on the state. 
 - The client does not need to trust the entity from which it is receiving data. For example, if a client fetches the last **n** transactions from an account, a proof can attest that no transactions were added, omitted or modified in the response. The client may also query for the state of an account, ask whether a specific transaction was processed, and so on.

-## Ledger state


Why delete this?

it wasn't, I moved it to "## State" and moved it to before proofs. look up a few lines

movekevin · 2022-12-07T07:12:41Z

developer-docs-site/docs/guides/aptos-apis.md

+
+While either of these may be disabled, storing the state versions is not particularly sustainable. 
+
+Events and transactions pruning can be disabled via setting the [`enable_ledger_pruner`](https://github.com/aptos-labs/aptos-core/blob/cf0bc2e4031a843cdc0c04e70b3f7cd92666afcf/config/src/config/storage_config.rs#L141) to `false`. This is default behavior in Mainnet. In the near future, Aptos will provide indexers that mitigate the need to directly query from a node.


Why not have this on the Running a Fullnode page and just link to that here?

davidiw

looks besides like a new line added, most of the feedback is about identifying additional quirks of the source material -- besides the PR that Clay already sent out to improve the linking ❤️

davidiw · 2022-12-07T14:46:33Z

developer-docs-site/docs/concepts/staking.md


-A validator can participate in the consensus process. However, the validator can acquire the voting power only when they stake, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is made proportionate to the amount of validator's stake. In exchange, the validator is rewarded in proportion to the amount of validator's stake. Hence, the performance of the network, i.e., consensus, is aligned with the validator's interest, i.e., rewards.  
+Anyone can participate in the Aptos consensus process, if they stake sufficient utility coin, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is proportional to the amount of validator's stake. In exchange, the validator is rewarded proportionally to the amount staked. Hence, the performance of the Blockchain is aligned with the validator's interest, i.e., rewards.  


I think you wrote this document first. Note the highlighted text is my changes.

davidiw · 2022-12-07T14:46:44Z

developer-docs-site/docs/concepts/staking.md

@@ -49,6 +48,7 @@ The `OwnerCapability` resource can be used to control the stake pool. Three pers
 - Operator
 - Voter

+


Sometimes things happen...

davidiw · 2022-12-07T14:47:45Z

developer-docs-site/docs/concepts/staking.md

+
+- Voting power can only change (increase or decrease) on epoch boundary.
+- A validator’s consensus key and the validator and validator fullnode network addresses can only change on epoch boundary.
+- Pending inactive stake cannot be moved into inactive (and thus withdrawable) until before lockup expires.


This is the original text, I think you're right though.

"Pending inactive stake cannot be move into inactive and thus withdrawable until the lockup expires."

The "before" and the "()" aren't useful.

davidiw · 2022-12-07T14:49:04Z

developer-docs-site/docs/concepts/txns-states.md

@@ -106,25 +98,23 @@ All operations executed by the blockchain and all account states can be verified
 - The validator nodes agree on the state. 
 - The client does not need to trust the entity from which it is receiving data. For example, if a client fetches the last **n** transactions from an account, a proof can attest that no transactions were added, omitted or modified in the response. The client may also query for the state of an account, ask whether a specific transaction was processed, and so on.

-## Ledger state


it wasn't, I moved it to "## State" and moved it to before proofs. look up a few lines

davidiw · 2022-12-07T14:49:10Z

developer-docs-site/docs/concepts/txns-states.md


-The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream.
+## States


@movekevin here

davidiw · 2022-12-07T14:49:38Z

developer-docs-site/docs/guides/system-integrators-guide.md

+
+JSON-encoded transactions can be generated via the [REST API](https://fullnode.devnet.aptoslabs.com/v1/spec#/), following these steps:
+
+1. First construct an appropriate JSON payload for the `/transactions/encode_submission` endpoint as demonstrated in the [Python SDK](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L128).


latest version doesn't work, because if someone moves code around, the line numbers will point to random content...

* Edit PR #5763 belatedly * Move Aptos Blockchain Deep Dive back down in navigation per reviewer feedback Co-authored-by: Clay Murphy <[email protected]>

* Edit PR aptos-labs#5763 belatedly * Move Aptos Blockchain Deep Dive back down in navigation per reviewer feedback Co-authored-by: Clay Murphy <[email protected]>

davidiw requested a review from movekevin December 3, 2022 20:53

davidiw requested a review from clay-aptos as a code owner December 3, 2022 20:53

davidiw force-pushed the docs branch 4 times, most recently from 17004e1 to 2da83b8 Compare December 5, 2022 05:15

davidiw added 4 commits December 4, 2022 21:16

[docs] gas

9fc9fe5

* Mosty good newlines, yay * The text was a little repititious here and there, so I streamlined it a bit * Added in additional context about simulation * Information about prioritization buckets

davidiw force-pushed the docs branch 2 times, most recently from 088553c to adc563e Compare December 5, 2022 05:49

davidiw added 8 commits December 4, 2022 21:50

[docs] blocks

e4ea554

some tweaks -- I ninja landed a larger change due to some obviously questionable text

[docs] minor tweaks to staking

51df194

[docs] governance cleanups

d705e3c

[docs] nodes -- remove the note around what not to do

fdc2a7c

I'm sure there was a reason for adding that at some point, but this belongs in an FAQ not at the end of a description about different networks

[docs] cleanup system-integrators-guide

7770add

This leverage a lot of Kevin's work to move content around and make this more of an index for the first chunk of content.

[docs] refine transactions in system integrators guide

31d72df

davidiw merged commit a78c488 into aptos-labs:main Dec 6, 2022

davidiw deleted the docs branch December 6, 2022 05:13

clay-aptos pushed a commit that referenced this pull request Dec 7, 2022

Edit PR #5763 belatedly

1bd182d

clay-aptos reviewed Dec 7, 2022

View reviewed changes

movekevin reviewed Dec 7, 2022

View reviewed changes

davidiw commented Dec 7, 2022

View reviewed changes

clay-aptos added a commit that referenced this pull request Dec 8, 2022

Edit PR #5763 belatedly (#5795)

d280cd0

* Edit PR #5763 belatedly * Move Aptos Blockchain Deep Dive back down in navigation per reviewer feedback Co-authored-by: Clay Murphy <[email protected]>

Markuze mentioned this pull request Dec 26, 2022

markuze/aptos perf #5998

Closed

Markuze mentioned this pull request Jan 3, 2023

[Network] Adding AptosPerf Client #6054

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] bring back system-integrators-guide #5763

[docs] bring back system-integrators-guide #5763

davidiw commented Dec 3, 2022

clay-aptos left a comment

clay-aptos Dec 7, 2022

davidiw Dec 7, 2022

clay-aptos Dec 7, 2022

davidiw Dec 7, 2022

clay-aptos Dec 7, 2022

movekevin Dec 7, 2022

clay-aptos Dec 7, 2022

clay-aptos Dec 7, 2022

clay-aptos Dec 7, 2022

clay-aptos Dec 7, 2022

davidiw Dec 7, 2022

clay-aptos Dec 7, 2022

movekevin Dec 7, 2022

davidiw Dec 7, 2022

movekevin Dec 7, 2022

davidiw Dec 7, 2022

movekevin Dec 7, 2022

movekevin Dec 7, 2022

davidiw Dec 7, 2022

movekevin Dec 7, 2022

davidiw left a comment

davidiw Dec 7, 2022

davidiw Dec 7, 2022

davidiw Dec 7, 2022

davidiw Dec 7, 2022

davidiw Dec 7, 2022

davidiw Dec 7, 2022


		With the configuration set in [staking_config.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move).
		The current on-chain data can be found [here](https://mainnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::staking_config::StakingConfig). With the configuration set defined in [staking_config.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move).


		During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise.

		A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted.


		The REST API offers querying transactions and events in these ways:

		* [Transactions for an account](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_account_transactions)


		### Querying transactions

		In Aptos, each transaction is committed as a distinct version to the blockchain. This allows for the convenience of sharing committed transactions by their version number; to do so, query: `https://{rest_server_api}/transactions/by_version/{version}`


		JSON-encoded transactions can be generated via the [REST API](https://fullnode.devnet.aptoslabs.com/v1/spec#/), following these steps:

		1. First construct an appropriate JSON payload for the `/transactions/encode_submission` endpoint as demonstrated in the [Python SDK](https://github.com/aptos-labs/aptos-core/blob/b0fe7ea6687e9c180ebdbac8d8eb984d11d7e4d4/ecosystem/python/sdk/aptos_sdk/client.py#L128).


		A validator can participate in the consensus process. However, the validator can acquire the voting power only when they stake, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is made proportionate to the amount of validator's stake. In exchange, the validator is rewarded in proportion to the amount of validator's stake. Hence, the performance of the network, i.e., consensus, is aligned with the validator's interest, i.e., rewards.
		Anyone can participate in the Aptos consensus process, if they stake sufficient utility coin, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is proportional to the amount of validator's stake. In exchange, the validator is rewarded proportionally to the amount staked. Hence, the performance of the Blockchain is aligned with the validator's interest, i.e., rewards.

		@@ -49,6 +48,7 @@ The `OwnerCapability` resource can be used to control the stake pool. Three pers
		- Operator
		- Voter


		While either of these may be disabled, storing the state versions is not particularly sustainable.

		Events and transactions pruning can be disabled via setting the [`enable_ledger_pruner`](https://github.com/aptos-labs/aptos-core/blob/cf0bc2e4031a843cdc0c04e70b3f7cd92666afcf/config/src/config/storage_config.rs#L141) to `false`. This is default behavior in Mainnet. In the near future, Aptos will provide indexers that mitigate the need to directly query from a node.


		The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream.
		## States

[docs] bring back system-integrators-guide #5763

[docs] bring back system-integrators-guide #5763

Conversation

davidiw commented Dec 3, 2022

Description

Test Plan

clay-aptos left a 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

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

davidiw left a 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