From 1072c689341dfcb98e024ed0d166515f4d071320 Mon Sep 17 00:00:00 2001 From: Roman Khimov Date: Wed, 31 Jan 2024 15:46:42 +0300 Subject: [PATCH 1/4] *: update for the API version 2.15.0 Signed-off-by: Roman Khimov --- 20-api-v2/00-intro.md | 2 ++ 20-api-v2/object.md | 21 ++++++++++++++++++++- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/20-api-v2/00-intro.md b/20-api-v2/00-intro.md index 9a9c603..e973fa8 100644 --- a/20-api-v2/00-intro.md +++ b/20-api-v2/00-intro.md @@ -17,6 +17,8 @@ popular, simple, and time-tested tools relevant for most languages and platforms. Although gRPC is used now, we have everything to transfer structures through other protocols, e.g. JSON-RPC. +The API described below corresponds to the [version 2.15.0](https://github.com/nspcc-dev/neofs-api/releases/tag/v2.15.0). + ## Nodes and their identification NeoFS API does not differentiate client and server. All members of the network diff --git a/20-api-v2/object.md b/20-api-v2/object.md index f827dd2..14fdb7a 100644 --- a/20-api-v2/object.md +++ b/20-api-v2/object.md @@ -374,7 +374,26 @@ Get hash of object's payload part response body. | ----- | ---- | ----------- | | type | ChecksumType | Checksum algorithm type | | hash_list | bytes | List of range hashes in a binary format | - + +### Method Replicate + +Save replica of the object on the NeoFS storage node. Both client and +server must authenticate NeoFS storage nodes matching storage policy of +the container referenced by the replicated object. Thus, this operation is +purely system: regular users should not pay attention to it but use Put. + +Statuses: +- **OK** (0, SECTION_SUCCESS): \ + the object has been successfully replicated; +- **INTERNAL_SERVER_ERROR** (1024, SECTION_FAILURE_COMMON): \ + internal server error described in the text message; +- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ + the client does not authenticate any NeoFS storage node matching storage + policy of the container referenced by the replicated object +- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ + the container to which the replicated object is associated was not found. + + ### Message GetResponse.Body.Init Initial part of the `Object` structure stream. Technically it's a From faedb9e41c9a2400b0c3d91f85be755a23f5245c Mon Sep 17 00:00:00 2001 From: Roman Khimov Date: Wed, 31 Jan 2024 19:14:39 +0300 Subject: [PATCH 2/4] Makefile: adapt to post-v0.19.1 contract changes Repository was restructured a bit. Signed-off-by: Roman Khimov --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 7209301..4006fa8 100644 --- a/Makefile +++ b/Makefile @@ -117,7 +117,7 @@ update_api: update_api_v2 .ONESHELL: update_contracts: - @for f in `find ${CONTRACTS_DIR} -mindepth 2 -maxdepth 2 -type f ! -path '*/nns/*' -name '*_contract.go' -exec dirname {} \; | sort -u `; + @for f in `find ${CONTRACTS_DIR} -mindepth 3 -maxdepth 3 -type f ! -path '*/nns/*' -name 'contract.go' -exec dirname {} \; | sort -u `; do echo "Documentation for $$(basename $$f)"; gomarkdoc --template-file file=templates/contracts-file.tmpl \ From 188e9eb3515c06d7223932a885bec1838e33b059 Mon Sep 17 00:00:00 2001 From: Roman Khimov Date: Wed, 31 Jan 2024 19:15:17 +0300 Subject: [PATCH 3/4] templates: update to gomarkdoc v1.1.0 It uses a new parser and has changed some functions as well. Signed-off-by: Roman Khimov --- templates/contracts-doc.tmpl | 16 +++++++++------- templates/contracts-func.tmpl | 7 +++---- templates/contracts-package.tmpl | 22 ++++++++++------------ 3 files changed, 22 insertions(+), 23 deletions(-) diff --git a/templates/contracts-doc.tmpl b/templates/contracts-doc.tmpl index c99c780..78e1f00 100644 --- a/templates/contracts-doc.tmpl +++ b/templates/contracts-doc.tmpl @@ -1,9 +1,11 @@ -{{- range .Blocks -}} - {{- if eq .Kind "paragraph" -}} - {{- paragraph .Text -}} - {{- else if eq .Kind "code" -}} - {{- codeBlock "" .Text -}} - {{- else if eq .Kind "header" -}} - {{- header (add .Level 1) .Text -}} +{{- range (iter .Blocks) -}} + {{- "\n" -}} + {{- if eq .Entry.Kind "paragraph" -}} + {{- template "text" .Entry.Spans -}} + {{- else if eq .Entry.Kind "code" -}} + {{- codeBlock "" (include "text" .Entry.Spans) -}} + {{- else if eq .Entry.Kind "header" -}} + {{- header (add .Entry.Level 1) (include "text" .Entry.Spans) -}} {{- end -}} + {{- "\n" -}} {{- end -}} diff --git a/templates/contracts-func.tmpl b/templates/contracts-func.tmpl index 2bc982e..48a6a65 100644 --- a/templates/contracts-func.tmpl +++ b/templates/contracts-func.tmpl @@ -1,8 +1,7 @@ -{{- .Name | rawHeader (add .Level 3) -}} +{{.Name | rawHeader (add .Level 3)}} -{{- codeBlock "go" .Signature -}} - -{{- template "doc" .Doc -}} +{{codeBlock "go" .Signature}} +{{template "doc" .Doc -}} {{- range .Examples -}} {{- template "example" . -}} diff --git a/templates/contracts-package.tmpl b/templates/contracts-package.tmpl index 63163af..2efb712 100644 --- a/templates/contracts-package.tmpl +++ b/templates/contracts-package.tmpl @@ -1,17 +1,15 @@ -{{- if eq .Name "main" -}} - {{- header .Level .Dirname -}} -{{- else -}} - {{- .Name | printf "%s contract" | header (add .Level 2) -}} -{{- end -}} +{{if eq .Name "main"}} + {{- header .Level .Dirname}} +{{else}} + {{- .Name | printf "%s contract" | header (add .Level 2)}} +{{end}} -{{- template "doc" .Doc -}} +{{template "doc" .Doc}} {{- range .Examples -}} {{- template "example" . -}} -{{- end -}} - -{{- header (add .Level 3) "Contract methods" -}} - -{{- range .Funcs -}} - {{- template "func" . -}} +{{- end}} +{{header (add .Level 3) "Contract methods"}} +{{range .Funcs -}} + {{- "\n"}}{{template "func" .}} {{- end -}} From 8781a70d69de6c418f26c73b4dc62a3fbc71b592 Mon Sep 17 00:00:00 2001 From: Roman Khimov Date: Wed, 31 Jan 2024 19:16:52 +0300 Subject: [PATCH 4/4] blockchain: update to v0.19.1 contract API Some changes are caused by the new gomarkdoc version. Signed-off-by: Roman Khimov --- 06-blockchain/02-contracts.md | 2 + 06-blockchain/03-alphabet.md | 37 ++++++------ 06-blockchain/03-audit.md | 33 +++++------ 06-blockchain/03-balance.md | 85 +++++++++++---------------- 06-blockchain/03-container.md | 101 ++++++++++++++++++++++----------- 06-blockchain/03-neofs.md | 75 ++++++++++++------------ 06-blockchain/03-neofsid.md | 29 +++++----- 06-blockchain/03-netmap.md | 75 ++++++++++++------------ 06-blockchain/03-processing.md | 23 ++++---- 06-blockchain/03-proxy.md | 23 ++++---- 06-blockchain/03-reputation.md | 25 ++++---- 11 files changed, 266 insertions(+), 242 deletions(-) diff --git a/06-blockchain/02-contracts.md b/06-blockchain/02-contracts.md index de1fae9..0cbbcfe 100644 --- a/06-blockchain/02-contracts.md +++ b/06-blockchain/02-contracts.md @@ -1 +1,3 @@ ## NeoFS Smart Contracts + +The API described below corresponds to [neofs-contract v0.19.1](https://github.com/nspcc-dev/neofs-contract/releases/tag/v0.19.1). diff --git a/06-blockchain/03-alphabet.md b/06-blockchain/03-alphabet.md index bb331ab..6f3f84f 100644 --- a/06-blockchain/03-alphabet.md +++ b/06-blockchain/03-alphabet.md @@ -1,14 +1,16 @@ ### alphabet contract -Alphabet contract is a contract deployed in NeoFS sidechain\. -Alphabet contract is designed to support GAS production and vote for new validators in the sidechain\. NEO token is required to produce GAS and vote for a new committee\. It can be distributed among alphabet nodes of the Inner Ring\. However\, some of them may be malicious\, and some NEO can be lost\. It will destabilize the economic of the sidechain\. To avoid it\, all 100\,000\,000 NEO are distributed among all alphabet contracts\. -To identify alphabet contracts\, they are named with letters of the Glagolitic alphabet\. Names are set at contract deploy\. Alphabet nodes of the Inner Ring communicate with one of the alphabetical contracts to emit GAS\. To vote for a new list of side chain committee\, alphabet nodes of the Inner Ring create multisignature transactions for each alphabet contract\. +Package alphabet contains implementation of Alphabet contract deployed in NeoFS sidechain. + +Alphabet contract is designed to support GAS production and vote for new validators in the sidechain. NEO token is required to produce GAS and vote for a new committee. It can be distributed among alphabet nodes of the Inner Ring. However, some of them may be malicious, and some NEO can be lost. It will destabilize the economic of the sidechain. To avoid it, all 100,000,000 NEO are distributed among all alphabet contracts. + +To identify alphabet contracts, they are named with letters of the Glagolitic alphabet. Names are set at contract deploy. Alphabet nodes of the Inner Ring communicate with one of the alphabetical contracts to emit GAS. To vote for a new list of side chain committee, alphabet nodes of the Inner Ring create multisignature transactions for each alphabet contract. #### Contract notifications -Alphabet contract does not produce notifications to process\. +Alphabet contract does not produce notifications to process. #### Contract methods @@ -18,11 +20,9 @@ Alphabet contract does not produce notifications to process\. func Emit() ``` -Emit method produces sidechain GAS and distributes it among Inner Ring nodes and proxy contract\. It can be invoked only by an Alphabet node of the Inner Ring\. +Emit method produces sidechain GAS and distributes it among Inner Ring nodes and proxy contract. It can be invoked only by an Alphabet node of the Inner Ring. -To produce GAS\, an alphabet contract transfers all available NEO from the contract account to itself\. If notary is enabled\, 50% of the GAS in the contract account are transferred to proxy contract\. 43\.75% of the GAS are equally distributed among all Inner Ring nodes\. Remaining 6\.25% of the GAS stay in the contract\. - -If notary is disabled\, 87\.5% of the GAS are equally distributed among all Inner Ring nodes\. Remaining 12\.5% of the GAS stay in the contract\. +To produce GAS, an alphabet contract transfers all available NEO from the contract account to itself. 50% of the GAS in the contract account are transferred to proxy contract. 43.75% of the GAS are equally distributed among all Inner Ring nodes. Remaining 6.25% of the GAS stay in the contract. ##### Gas @@ -30,7 +30,7 @@ If notary is disabled\, 87\.5% of the GAS are equally distributed among all Inne func Gas() int ``` -GAS returns the amount of the sidechain GAS stored in the contract account\. +Gas returns the amount of the sidechain GAS stored in the contract account. ##### Name @@ -38,7 +38,7 @@ GAS returns the amount of the sidechain GAS stored in the contract account\. func Name() string ``` -Name returns the Glagolitic name of the contract\. +Name returns the Glagolitic name of the contract. ##### Neo @@ -46,23 +46,23 @@ Name returns the Glagolitic name of the contract\. func Neo() int ``` -NEO returns the amount of sidechain NEO stored in the contract account\. +Neo returns the amount of sidechain NEO stored in the contract account. ##### OnNEP17Payment ```go -func OnNEP17Payment(from interop.Hash160, amount int, data interface{}) +func OnNEP17Payment(from interop.Hash160, amount int, data any) ``` -OnNEP17Payment is a callback for NEP\-17 compatible native GAS and NEO contracts\. +OnNEP17Payment is a callback for NEP\-17 compatible native GAS and NEO contracts. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked only by committee\. +Update method updates contract source code and manifest. It can be invoked only by committee. ##### Version @@ -70,7 +70,7 @@ Update method updates contract source code and manifest\. It can be invoked only func Version() int ``` -Version returns the version of the contract\. +Version returns the version of the contract. ##### Vote @@ -78,8 +78,7 @@ Version returns the version of the contract\. func Vote(epoch int, candidates []interop.PublicKey) ``` -Vote method votes for the sidechain committee\. It requires multisignature from Alphabet nodes of the Inner Ring\. - -This method is used when governance changes the list of Alphabet nodes of the Inner Ring\. Alphabet nodes share keys with sidechain validators\, therefore it is required to change them as well\. To do that\, NEO holders \(which are alphabet contracts\) should vote for a new committee\. +Vote method votes for the sidechain committee. It requires multisignature from Alphabet nodes of the Inner Ring. +This method is used when governance changes the list of Alphabet nodes of the Inner Ring. Alphabet nodes share keys with sidechain validators, therefore it is required to change them as well. To do that, NEO holders \(which are alphabet contracts\) should vote for a new committee. diff --git a/06-blockchain/03-audit.md b/06-blockchain/03-audit.md index 2fcd83b..0478cb4 100644 --- a/06-blockchain/03-audit.md +++ b/06-blockchain/03-audit.md @@ -1,14 +1,16 @@ ### audit contract -Audit contract is a contract deployed in NeoFS sidechain\. -Inner Ring nodes perform audit of the registered containers during every epoch\. If a container contains StorageGroup objects\, an Inner Ring node initializes a series of audit checks\. Based on the results of these checks\, the Inner Ring node creates a DataAuditResult structure for the container\. The content of this structure makes it possible to determine which storage nodes have been examined and see the status of these checks\. Regarding this information\, the container owner is charged for data storage\. -Audit contract is used as a reliable and verifiable storage for all DataAuditResult structures\. At the end of data audit routine\, Inner Ring nodes send a stable marshaled version of the DataAuditResult structure to the contract\. When Alphabet nodes of the Inner Ring perform settlement operations\, they make a list and get these AuditResultStructures from the audit contract\. +Package audit contains implementation of Audit contract deployed in NeoFS sidechain. + +Inner Ring nodes perform audit of the registered containers during every epoch. If a container contains StorageGroup objects, an Inner Ring node initializes a series of audit checks. Based on the results of these checks, the Inner Ring node creates a DataAuditResult structure for the container. The content of this structure makes it possible to determine which storage nodes have been examined and see the status of these checks. Regarding this information, the container owner is charged for data storage. + +Audit contract is used as a reliable and verifiable storage for all DataAuditResult structures. At the end of data audit routine, Inner Ring nodes send a stable marshaled version of the DataAuditResult structure to the contract. When Alphabet nodes of the Inner Ring perform settlement operations, they make a list and get these AuditResultStructures from the audit contract. #### Contract notifications -Audit contract does not produce notifications to process\. +Audit contract does not produce notifications to process. #### Contract methods @@ -18,9 +20,9 @@ Audit contract does not produce notifications to process\. func Get(id []byte) []byte ``` -Get method returns a stable marshaled DataAuditResult structure\. +Get method returns a stable marshaled DataAuditResult structure. -The ID of the DataAuditResult can be obtained from listing methods\. +The ID of the DataAuditResult can be obtained from listing methods. ##### List @@ -28,7 +30,7 @@ The ID of the DataAuditResult can be obtained from listing methods\. func List() [][]byte ``` -List method returns a list of all available DataAuditResult IDs from the contract storage\. +List method returns a list of all available DataAuditResult IDs from the contract storage. ##### ListByCID @@ -36,7 +38,7 @@ List method returns a list of all available DataAuditResult IDs from the contrac func ListByCID(epoch int, cid []byte) [][]byte ``` -ListByCID method returns a list of DataAuditResult IDs generated during the specified epoch for the specified container\. +ListByCID method returns a list of DataAuditResult IDs generated during the specified epoch for the specified container. ##### ListByEpoch @@ -44,7 +46,7 @@ ListByCID method returns a list of DataAuditResult IDs generated during the spec func ListByEpoch(epoch int) [][]byte ``` -ListByEpoch method returns a list of DataAuditResult IDs generated during the specified epoch\. +ListByEpoch method returns a list of DataAuditResult IDs generated during the specified epoch. ##### ListByNode @@ -52,7 +54,7 @@ ListByEpoch method returns a list of DataAuditResult IDs generated during the sp func ListByNode(epoch int, cid []byte, key interop.PublicKey) [][]byte ``` -ListByNode method returns a list of DataAuditResult IDs generated in the specified epoch for the specified container by the specified Inner Ring node\. +ListByNode method returns a list of DataAuditResult IDs generated in the specified epoch for the specified container by the specified Inner Ring node. ##### Put @@ -60,17 +62,17 @@ ListByNode method returns a list of DataAuditResult IDs generated in the specifi func Put(rawAuditResult []byte) ``` -Put method stores a stable marshalled \`DataAuditResult\` structure\. It can be invoked only by Inner Ring nodes\. +Put method stores a stable marshalled \`DataAuditResult\` structure. It can be invoked only by Inner Ring nodes. -Inner Ring nodes perform audit of containers and produce \`DataAuditResult\` structures\. They are stored in audit contract and used for settlements in later epochs\. +Inner Ring nodes perform audit of containers and produce \`DataAuditResult\` structures. They are stored in audit contract and used for settlements in later epochs. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked only by committee\. +Update method updates contract source code and manifest. It can be invoked only by committee. ##### Version @@ -78,6 +80,5 @@ Update method updates contract source code and manifest\. It can be invoked only func Version() int ``` -Version returns the version of the contract\. - +Version returns the version of the contract. diff --git a/06-blockchain/03-balance.md b/06-blockchain/03-balance.md index b9358c6..a353c40 100644 --- a/06-blockchain/03-balance.md +++ b/06-blockchain/03-balance.md @@ -1,16 +1,18 @@ ### balance contract -Balance contract is a contract deployed in NeoFS sidechain\. -Balance contract stores all NeoFS account balances\. It is a NEP\-17 compatible contract\, so it can be tracked and controlled by N3 compatible network monitors and wallet software\. -This contract is used to store all micro transactions in the sidechain\, such as data audit settlements or container fee payments\. It is inefficient to make such small payment transactions in the mainchain\. To process small transfers\, balance contract has higher \(12\) decimal precision than native GAS contract\. +Package balance contains implementation of Balance contract deployed in NeoFS sidechain. -NeoFS balances are synchronized with mainchain operations\. Deposit produces minting of NEOFS tokens in Balance contract\. Withdraw locks some NEOFS tokens in a special lock account\. When NeoFS contract transfers GAS assets back to the user\, the lock account is destroyed with burn operation\. +Balance contract stores all NeoFS account balances. It is a NEP\-17 compatible contract, so it can be tracked and controlled by N3 compatible network monitors and wallet software. + +This contract is used to store all micro transactions in the sidechain, such as data audit settlements or container fee payments. It is inefficient to make such small payment transactions in the mainchain. To process small transfers, balance contract has higher \(12\) decimal precision than native GAS contract. + +NeoFS balances are synchronized with mainchain operations. Deposit produces minting of NEOFS tokens in Balance contract. Withdraw locks some NEOFS tokens in a special lock account. When NeoFS contract transfers GAS assets back to the user, the lock account is destroyed with burn operation. #### Contract notifications -Transfer notification\. This is a NEP\-17 standard notification\. +Transfer notification. This is a NEP\-17 standard notification. ``` Transfer: @@ -22,7 +24,7 @@ Transfer: type: Integer ``` -TransferX notification\. This is an enhanced transfer notification with details\. +TransferX notification. This is an enhanced transfer notification with details. ``` TransferX: @@ -36,7 +38,7 @@ TransferX: type: ByteArray ``` -Lock notification\. This notification is produced when a lock account is created\. It contains information about the mainchain transaction that has produced the asset lock\, the address of the lock account and the NeoFS epoch number until which the lock account is valid\. Alphabet nodes of the Inner Ring catch notification and initialize Cheque method invocation of NeoFS contract\. +Lock notification. This notification is produced when a lock account is created. It contains information about the mainchain transaction that has produced the asset lock, the address of the lock account and the NeoFS epoch number until which the lock account is valid. Alphabet nodes of the Inner Ring catch notification and initialize Cheque method invocation of NeoFS contract. ``` Lock: @@ -52,26 +54,6 @@ Lock: type: Integer ``` -Mint notification\. This notification is produced when user balance is replenished from deposit in the mainchain\. - -``` -Mint: - - name: to - type: Hash160 - - name: amount - type: Integer -``` - -Burn notification\. This notification is produced after user balance is reduced when NeoFS contract has transferred GAS assets back to the user\. - -``` -Burn: - - name: from - type: Hash160 - - name: amount - type: Integer -``` - #### Contract methods ##### BalanceOf @@ -80,7 +62,7 @@ Burn: func BalanceOf(account interop.Hash160) int ``` -BalanceOf is a NEP\-17 standard method that returns NeoFS balance of the specified account\. +BalanceOf is a NEP\-17 standard method that returns NeoFS balance of the specified account. ##### Burn @@ -88,11 +70,11 @@ BalanceOf is a NEP\-17 standard method that returns NeoFS balance of the specifi func Burn(from interop.Hash160, amount int, txDetails []byte) ``` -Burn is a method that transfers assets from a user account to an empty account\. It can be invoked only by Alphabet nodes of the Inner Ring\. +Burn is a method that transfers assets from a user account to an empty account. It can be invoked only by Alphabet nodes of the Inner Ring. -It produces Burn\, Transfer and TransferX notifications\. +It produces Transfer and TransferX notifications. -Burn method is invoked by Alphabet nodes of the Inner Ring when they process Cheque notification from NeoFS contract\. It means that locked assets have been transferred to the user in the mainchain\, therefore the lock account should be destroyed\. Before that\, Alphabet nodes should synchronize precision of mainchain GAS contract and Balance contract\. Burn decreases total supply of NEP\-17 compatible NeoFS token\. +Burn method is invoked by Alphabet nodes of the Inner Ring when they process Cheque notification from NeoFS contract. It means that locked assets have been transferred to the user in the mainchain, therefore the lock account should be destroyed. Before that, Alphabet nodes should synchronize precision of mainchain GAS contract and Balance contract. Burn decreases total supply of NEP\-17 compatible NeoFS token. ##### Decimals @@ -100,7 +82,7 @@ Burn method is invoked by Alphabet nodes of the Inner Ring when they process Che func Decimals() int ``` -Decimals is a NEP\-17 standard method that returns precision of NeoFS balances\. +Decimals is a NEP\-17 standard method that returns precision of NeoFS balances. ##### Lock @@ -108,11 +90,11 @@ Decimals is a NEP\-17 standard method that returns precision of NeoFS balances\. func Lock(txDetails []byte, from, to interop.Hash160, amount, until int) ``` -Lock is a method that transfers assets from a user account to the lock account related to the user\. It can be invoked only by Alphabet nodes of the Inner Ring\. +Lock is a method that transfers assets from a user account to the lock account related to the user. It can be invoked only by Alphabet nodes of the Inner Ring. -It produces Lock\, Transfer and TransferX notifications\. +It produces Lock, Transfer and TransferX notifications. -Lock method is invoked by Alphabet nodes of the Inner Ring when they process Withdraw notification from NeoFS contract\. This should transfer assets to a new lock account that won't be used for anything beside Unlock and Burn\. +Lock method is invoked by Alphabet nodes of the Inner Ring when they process Withdraw notification from NeoFS contract. This should transfer assets to a new lock account that won't be used for anything beside Unlock and Burn. ##### Mint @@ -120,11 +102,11 @@ Lock method is invoked by Alphabet nodes of the Inner Ring when they process Wit func Mint(to interop.Hash160, amount int, txDetails []byte) ``` -Mint is a method that transfers assets to a user account from an empty account\. It can be invoked only by Alphabet nodes of the Inner Ring\. +Mint is a method that transfers assets to a user account from an empty account. It can be invoked only by Alphabet nodes of the Inner Ring. -It produces Mint\, Transfer and TransferX notifications\. +It produces Transfer and TransferX notifications. -Mint method is invoked by Alphabet nodes of the Inner Ring when they process Deposit notification from NeoFS contract\. Before that\, Alphabet nodes should synchronize precision of mainchain GAS contract and Balance contract\. Mint increases total supply of NEP\-17 compatible NeoFS token\. +Mint method is invoked by Alphabet nodes of the Inner Ring when they process Deposit notification from NeoFS contract. Before that, Alphabet nodes should synchronize precision of mainchain GAS contract and Balance contract. Mint increases total supply of NEP\-17 compatible NeoFS token. ##### NewEpoch @@ -132,9 +114,9 @@ Mint method is invoked by Alphabet nodes of the Inner Ring when they process Dep func NewEpoch(epochNum int) ``` -NewEpoch is a method that checks timeout on lock accounts and returns assets if lock is not available anymore\. It can be invoked only by NewEpoch method of Netmap contract\. +NewEpoch is a method that checks timeout on lock accounts and returns assets if lock is not available anymore. It can be invoked only by NewEpoch method of Netmap contract. -It produces Transfer and TransferX notifications\. +It produces Transfer and TransferX notifications. ##### Symbol @@ -142,7 +124,7 @@ It produces Transfer and TransferX notifications\. func Symbol() string ``` -Symbol is a NEP\-17 standard method that returns NEOFS token symbol\. +Symbol is a NEP\-17 standard method that returns NEOFS token symbol. ##### TotalSupply @@ -150,17 +132,17 @@ Symbol is a NEP\-17 standard method that returns NEOFS token symbol\. func TotalSupply() int ``` -TotalSupply is a NEP\-17 standard method that returns total amount of main chain GAS in NeoFS network\. +TotalSupply is a NEP\-17 standard method that returns total amount of main chain GAS in NeoFS network. ##### Transfer ```go -func Transfer(from, to interop.Hash160, amount int, data interface{}) bool +func Transfer(from, to interop.Hash160, amount int, data any) bool ``` -Transfer is a NEP\-17 standard method that transfers NeoFS balance from one account to another\. It can be invoked only by the account owner\. +Transfer is a NEP\-17 standard method that transfers NeoFS balance from one account to another. It can be invoked only by the account owner. -It produces Transfer and TransferX notifications\. TransferX notification will have empty details field\. +It produces Transfer and TransferX notifications. TransferX notification will have empty details field. ##### TransferX @@ -168,19 +150,19 @@ It produces Transfer and TransferX notifications\. TransferX notification will h func TransferX(from, to interop.Hash160, amount int, details []byte) ``` -TransferX is a method for NeoFS balance to be transferred from one account to another\. It can be invoked by the account owner or by Alphabet nodes\. +TransferX is a method for NeoFS balance to be transferred from one account to another. It can be invoked by the account owner or by Alphabet nodes. -It produces Transfer and TransferX notifications\. +It produces Transfer and TransferX notifications. -TransferX method expands Transfer method by having extra details argument\. TransferX method also allows to transfer assets by Alphabet nodes of the Inner Ring with multisignature\. +TransferX method expands Transfer method by having extra details argument. TransferX method also allows to transfer assets by Alphabet nodes of the Inner Ring with multisignature. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked only by committee\. +Update method updates contract source code and manifest. It can be invoked only by committee. ##### Version @@ -188,6 +170,5 @@ Update method updates contract source code and manifest\. It can be invoked only func Version() int ``` -Version returns the version of the contract\. - +Version returns the version of the contract. diff --git a/06-blockchain/03-container.md b/06-blockchain/03-container.md index 32215e1..733a772 100644 --- a/06-blockchain/03-container.md +++ b/06-blockchain/03-container.md @@ -1,12 +1,14 @@ ### container contract -Container contract is a contract deployed in NeoFS sidechain\. -Container contract stores and manages containers\, extended ACLs and container size estimations\. Contract does not perform sanity or signature checks of containers or extended ACLs\, it is done by Alphabet nodes of the Inner Ring\. Alphabet nodes approve it by invoking the same Put or SetEACL methods with the same arguments\. + +Package container contains implementation of Container contract deployed in NeoFS sidechain. + +Container contract stores and manages containers, extended ACLs and container size estimations. Contract does not perform sanity or signature checks of containers or extended ACLs, it is done by Alphabet nodes of the Inner Ring. Alphabet nodes approve it by invoking the same Put or SetEACL methods with the same arguments. #### Contract notifications -containerPut notification\. This notification is produced when a user wants to create a new container\. Alphabet nodes of the Inner Ring catch the notification and validate container data\, signature and token if present\. +containerPut notification. This notification is produced when a user wants to create a new container. Alphabet nodes of the Inner Ring catch the notification and validate container data, signature and token if present. ``` containerPut: @@ -20,7 +22,7 @@ containerPut: type: ByteArray ``` -containerDelete notification\. This notification is produced when a container owner wants to delete a container\. Alphabet nodes of the Inner Ring catch the notification and validate container ownership\, signature and token if present\. +containerDelete notification. This notification is produced when a container owner wants to delete a container. Alphabet nodes of the Inner Ring catch the notification and validate container ownership, signature and token if present. ``` containerDelete: @@ -32,7 +34,7 @@ containerDelete: type: ByteArray ``` -setEACL notification\. This notification is produced when a container owner wants to update an extended ACL of a container\. Alphabet nodes of the Inner Ring catch the notification and validate container ownership\, signature and token if present\. +setEACL notification. This notification is produced when a container owner wants to update an extended ACL of a container. Alphabet nodes of the Inner Ring catch the notification and validate container ownership, signature and token if present. ``` setEACL: @@ -46,7 +48,7 @@ setEACL: type: ByteArray ``` -StartEstimation notification\. This notification is produced when Storage nodes should exchange estimation values of container sizes among other Storage nodes\. +StartEstimation notification. This notification is produced when Storage nodes should exchange estimation values of container sizes among other Storage nodes. ``` StartEstimation: @@ -54,7 +56,7 @@ StartEstimation: type: Integer ``` -StopEstimation notification\. This notification is produced when Storage nodes should calculate average container size based on received estimations and store it in Container contract\. +StopEstimation notification. This notification is produced when Storage nodes should calculate average container size based on received estimations and store it in Container contract. ``` StopEstimation: @@ -64,13 +66,31 @@ StopEstimation: #### Contract methods +##### Alias + +```go +func Alias(cid []byte) string +``` + +Alias method returns a string with an alias of the container if it's set \(Null otherwise\). + +If the container doesn't exist, it panics with NotFoundError. + +##### ContainersOf + +```go +func ContainersOf(owner []byte) iterator.Iterator +``` + +ContainersOf iterates over all container IDs owned by the specified owner. If owner is nil, it iterates over all containers. + ##### Count ```go func Count() int ``` -Count method returns the number of registered containers\. +Count method returns the number of registered containers. ##### Delete @@ -78,11 +98,27 @@ Count method returns the number of registered containers\. func Delete(containerID []byte, signature interop.Signature, token []byte) ``` -Delete method removes a container from the contract storage if it has been invoked by Alphabet nodes of the Inner Ring\. Otherwise\, it produces containerDelete notification\. +Delete method removes a container from the contract storage if it has been invoked by Alphabet nodes of the Inner Ring. Otherwise, it produces containerDelete notification. -Signature is a RFC6979 signature of the container ID\. Token is optional and should be a stable marshaled SessionToken structure from API\. +Signature is a RFC6979 signature of the container ID. Token is optional and should be a stable marshaled SessionToken structure from API. -If the container doesn't exist\, it panics with NotFoundError\. +If the container doesn't exist, it panics with NotFoundError. + +##### IterateAllContainerSizes + +```go +func IterateAllContainerSizes(epoch int) iterator.Iterator +``` + +IterateAllContainerSizes method returns iterator over all container size estimations that have been registered for the specified epoch. Items returned from this iterator are key\-value pairs with keys having container ID as a prefix and values being Estimation structures. + +##### IterateContainerSizes + +```go +func IterateContainerSizes(epoch int, cid interop.Hash256) iterator.Iterator +``` + +IterateContainerSizes method returns iterator over specific container size estimations that have been registered for the specified epoch. The iterator items are Estimation structures. ##### List @@ -90,7 +126,7 @@ If the container doesn't exist\, it panics with NotFoundError\. func List(owner []byte) [][]byte ``` -List method returns a list of all container IDs owned by the specified owner\. +List method returns a list of all container IDs owned by the specified owner. ##### ListContainerSizes @@ -98,7 +134,9 @@ List method returns a list of all container IDs owned by the specified owner\. func ListContainerSizes(epoch int) [][]byte ``` -ListContainerSizes method returns the IDs of container size estimations that has been registered for the specified epoch\. +ListContainerSizes method returns the IDs of container size estimations that have been registered for the specified epoch. + +Deprecated: please use IterateAllContainerSizes API, this one is not convenient to use and limited in the number of items it can return. It will be removed in future versions. ##### NewEpoch @@ -106,15 +144,15 @@ ListContainerSizes method returns the IDs of container size estimations that has func NewEpoch(epochNum int) ``` -NewEpoch method removes all container size estimations from epoch older than epochNum \+ 3\. It can be invoked only by NewEpoch method of the Netmap contract\. +NewEpoch method removes all container size estimations from epoch older than epochNum \+ 3. It can be invoked only by NewEpoch method of the Netmap contract. ##### OnNEP11Payment ```go -func OnNEP11Payment(a interop.Hash160, b int, c []byte, d interface{}) +func OnNEP11Payment(a interop.Hash160, b int, c []byte, d any) ``` -OnNEP11Payment is needed for registration with contract as the owner to work\. +OnNEP11Payment is needed for registration with contract as the owner to work. ##### Owner @@ -122,9 +160,9 @@ OnNEP11Payment is needed for registration with contract as the owner to work\. func Owner(containerID []byte) []byte ``` -Owner method returns a 25 byte Owner ID of the container\. +Owner method returns a 25 byte Owner ID of the container. -If the container doesn't exist\, it panics with NotFoundError\. +If the container doesn't exist, it panics with NotFoundError. ##### Put @@ -132,9 +170,9 @@ If the container doesn't exist\, it panics with NotFoundError\. func Put(container []byte, signature interop.Signature, publicKey interop.PublicKey, token []byte) ``` -Put method creates a new container if it has been invoked by Alphabet nodes of the Inner Ring\. Otherwise\, it produces containerPut notification\. +Put method creates a new container if it has been invoked by Alphabet nodes of the Inner Ring. Otherwise, it produces containerPut notification. -Container should be a stable marshaled Container structure from API\. Signature is a RFC6979 signature of the Container\. PublicKey contains the public key of the signer\. Token is optional and should be a stable marshaled SessionToken structure from API\. +Container should be a stable marshaled Container structure from API. Signature is a RFC6979 signature of the Container. PublicKey contains the public key of the signer. Token is optional and should be a stable marshaled SessionToken structure from API. ##### PutContainerSize @@ -142,9 +180,9 @@ Container should be a stable marshaled Container structure from API\. Signature func PutContainerSize(epoch int, cid []byte, usedSize int, pubKey interop.PublicKey) ``` -PutContainerSize method saves container size estimation in contract memory\. It can be invoked only by Storage nodes from the network map\. This method checks witness based on the provided public key of the Storage node\. +PutContainerSize method saves container size estimation in contract memory. It can be invoked only by Storage nodes from the network map. This method checks witness based on the provided public key of the Storage node. -If the container doesn't exist\, it panics with NotFoundError\. +If the container doesn't exist, it panics with NotFoundError. ##### PutNamed @@ -152,7 +190,7 @@ If the container doesn't exist\, it panics with NotFoundError\. func PutNamed(container []byte, signature interop.Signature, publicKey interop.PublicKey, token []byte, name, zone string) ``` -PutNamed is similar to put but also sets a TXT record in nns contract\. Note that zone must exist\. +PutNamed is similar to put but also sets a TXT record in nns contract. Note that zone must exist. ##### SetEACL @@ -160,11 +198,11 @@ PutNamed is similar to put but also sets a TXT record in nns contract\. Note tha func SetEACL(eACL []byte, signature interop.Signature, publicKey interop.PublicKey, token []byte) ``` -SetEACL method sets a new extended ACL table related to the contract if it was invoked by Alphabet nodes of the Inner Ring\. Otherwise\, it produces setEACL notification\. +SetEACL method sets a new extended ACL table related to the contract if it was invoked by Alphabet nodes of the Inner Ring. Otherwise, it produces setEACL notification. -EACL should be a stable marshaled EACLTable structure from API\. Signature is a RFC6979 signature of the Container\. PublicKey contains the public key of the signer\. Token is optional and should be a stable marshaled SessionToken structure from API\. +EACL should be a stable marshaled EACLTable structure from API. Protocol version and container reference must be set in 'version' and 'container\_id' fields respectively. Signature is a RFC6979 signature of the Container. PublicKey contains the public key of the signer. Token is optional and should be a stable marshaled SessionToken structure from API. -If the container doesn't exist\, it panics with NotFoundError\. +If the container doesn't exist, it panics with NotFoundError. ##### StartContainerEstimation @@ -172,7 +210,7 @@ If the container doesn't exist\, it panics with NotFoundError\. func StartContainerEstimation(epoch int) ``` -StartContainerEstimation method produces StartEstimation notification\. It can be invoked only by Alphabet nodes of the Inner Ring\. +StartContainerEstimation method produces StartEstimation notification. It can be invoked only by Alphabet nodes of the Inner Ring. ##### StopContainerEstimation @@ -180,15 +218,15 @@ StartContainerEstimation method produces StartEstimation notification\. It can b func StopContainerEstimation(epoch int) ``` -StopContainerEstimation method produces StopEstimation notification\. It can be invoked only by Alphabet nodes of the Inner Ring\. +StopContainerEstimation method produces StopEstimation notification. It can be invoked only by Alphabet nodes of the Inner Ring. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked by committee only\. +Update method updates contract source code and manifest. It can be invoked by committee only. ##### Version @@ -196,6 +234,5 @@ Update method updates contract source code and manifest\. It can be invoked by c func Version() int ``` -Version returns the version of the contract\. - +Version returns the version of the contract. diff --git a/06-blockchain/03-neofs.md b/06-blockchain/03-neofs.md index 84bf225..c403115 100644 --- a/06-blockchain/03-neofs.md +++ b/06-blockchain/03-neofs.md @@ -1,16 +1,18 @@ ### neofs contract -NeoFS contract is a contract deployed in NeoFS mainchain\. -NeoFS contract is an entry point to NeoFS users\. This contract stores all NeoFS related GAS\, registers new Inner Ring candidates and produces notifications to control the sidechain\. -While mainchain committee controls the list of Alphabet nodes in native RoleManagement contract\, NeoFS can't change more than 1\\3 keys at a time\. NeoFS contract contains the actual list of Alphabet nodes in the sidechain\. +Package neofs contains implementation of NeoFS contract deployed in NeoFS mainchain. -Network configuration is also stored in NeoFS contract\. All changes in configuration are mirrored in the sidechain with notifications\. +NeoFS contract is an entry point to NeoFS users. This contract stores all NeoFS related GAS, registers new Inner Ring candidates and produces notifications to control the sidechain. + +While mainchain committee controls the list of Alphabet nodes in native RoleManagement contract, NeoFS can't change more than 1\\3 keys at a time. NeoFS contract contains the actual list of Alphabet nodes in the sidechain. + +Network configuration is also stored in NeoFS contract. All changes in configuration are mirrored in the sidechain with notifications. #### Contract notifications -Deposit notification\. This notification is produced when user transfers native GAS to the NeoFS contract address\. The same amount of NEOFS token will be minted in Balance contract in the sidechain\. +Deposit notification. This notification is produced when user transfers native GAS to the NeoFS contract address. The same amount of NEOFS token will be minted in Balance contract in the sidechain. ``` Deposit: @@ -24,7 +26,7 @@ Deposit: type: Hash256 ``` -Withdraw notification\. This notification is produced when a user wants to withdraw GAS from the internal NeoFS balance and has paid fee for that\. +Withdraw notification. This notification is produced when a user wants to withdraw GAS from the internal NeoFS balance and has paid fee for that. ``` Withdraw: @@ -36,7 +38,7 @@ Withdraw: type: Hash256 ``` -Cheque notification\. This notification is produced when NeoFS contract has successfully transferred assets back to the user after withdraw\. +Cheque notification. This notification is produced when NeoFS contract has successfully transferred assets back to the user after withdraw. ``` Cheque: @@ -50,7 +52,7 @@ Cheque: type: ByteArray ``` -Bind notification\. This notification is produced when a user wants to bind public keys with the user account \(OwnerID\)\. Keys argument is an array of ByteArray\. +Bind notification. This notification is produced when a user wants to bind public keys with the user account \(OwnerID\). Keys argument is an array of ByteArray. ``` Bind: @@ -60,7 +62,7 @@ Bind: type: Array ``` -Unbind notification\. This notification is produced when a user wants to unbind public keys with the user account \(OwnerID\)\. Keys argument is an array of ByteArray\. +Unbind notification. This notification is produced when a user wants to unbind public keys with the user account \(OwnerID\). Keys argument is an array of ByteArray. ``` Unbind: @@ -70,7 +72,7 @@ Unbind: type: Array ``` -AlphabetUpdate notification\. This notification is produced when Alphabet nodes have updated their lists in the contract\. Alphabet argument is an array of ByteArray\. It contains public keys of new alphabet nodes\. +AlphabetUpdate notification. This notification is produced when Alphabet nodes have updated their lists in the contract. Alphabet argument is an array of ByteArray. It contains public keys of new alphabet nodes. ``` AlphabetUpdate: @@ -80,7 +82,7 @@ AlphabetUpdate: type: Array ``` -SetConfig notification\. This notification is produced when Alphabet nodes update NeoFS network configuration value\. +SetConfig notification. This notification is produced when Alphabet nodes update NeoFS network configuration value. ``` SetConfig @@ -100,7 +102,7 @@ SetConfig func AlphabetAddress() interop.Hash160 ``` -AlphabetAddress returns 2\\3n\+1 multisignature address of alphabet nodes\. It is used in sidechain notary disabled environment\. +AlphabetAddress returns 2\\3n\+1 multisignature address of alphabet nodes. It is used in sidechain notary disabled environment. ##### AlphabetList @@ -108,7 +110,7 @@ AlphabetAddress returns 2\\3n\+1 multisignature address of alphabet nodes\. It i func AlphabetList() []common.IRNode ``` -AlphabetList returns an array of alphabet node keys\. It is used in sidechain notary disabled environment\. +AlphabetList returns an array of alphabet node keys. It is used in sidechain notary disabled environment. ##### AlphabetUpdate @@ -116,9 +118,9 @@ AlphabetList returns an array of alphabet node keys\. It is used in sidechain no func AlphabetUpdate(id []byte, args []interop.PublicKey) ``` -AlphabetUpdate updates a list of alphabet nodes with the provided list of public keys\. It can be invoked only by alphabet nodes\. +AlphabetUpdate updates a list of alphabet nodes with the provided list of public keys. It can be invoked only by alphabet nodes. -This method is used in notary disabled sidechain environment\. In this case\, the actual alphabet list should be stored in the NeoFS contract\. +This method is used in notary disabled sidechain environment. In this case, the actual alphabet list should be stored in the NeoFS contract. ##### Bind @@ -126,9 +128,9 @@ This method is used in notary disabled sidechain environment\. In this case\, th func Bind(user []byte, keys []interop.PublicKey) ``` -Bind method produces notification to bind the specified public keys in NeoFSID contract in the sidechain\. It can be invoked only by specified user\. +Bind method produces notification to bind the specified public keys in NeoFSID contract in the sidechain. It can be invoked only by specified user. -This method produces Bind notification\. This method panics if keys are not 33 byte long\. User argument must be a valid 20 byte script hash\. +This method produces Bind notification. This method panics if keys are not 33 byte long. User argument must be a valid 20 byte script hash. ##### Cheque @@ -136,17 +138,17 @@ This method produces Bind notification\. This method panics if keys are not 33 b func Cheque(id []byte, user interop.Hash160, amount int, lockAcc []byte) ``` -Cheque transfers GAS back to the user from the contract account\, if assets were successfully locked in NeoFS balance contract\. It can be invoked only by Alphabet nodes\. +Cheque transfers GAS back to the user from the contract account, if assets were successfully locked in NeoFS balance contract. It can be invoked only by Alphabet nodes. -This method produces Cheque notification to burn assets in sidechain\. +This method produces Cheque notification to burn assets in sidechain. ##### Config ```go -func Config(key []byte) interface{} +func Config(key []byte) any ``` -Config returns configuration value of NeoFS configuration\. If the key does not exists\, returns nil\. +Config returns configuration value of NeoFS configuration. If the key does not exist, returns nil. ##### InnerRingCandidateAdd @@ -154,9 +156,9 @@ Config returns configuration value of NeoFS configuration\. If the key does not func InnerRingCandidateAdd(key interop.PublicKey) ``` -InnerRingCandidateAdd adds a key to a list of Inner Ring candidates\. It can be invoked only by the candidate itself\. +InnerRingCandidateAdd adds a key to a list of Inner Ring candidates. It can be invoked only by the candidate itself. -This method transfers fee from a candidate to the contract account\. Fee value is specified in NeoFS network config with the key InnerRingCandidateFee\. +This method transfers fee from a candidate to the contract account. Fee value is specified in NeoFS network config with the key InnerRingCandidateFee. ##### InnerRingCandidateRemove @@ -164,9 +166,9 @@ This method transfers fee from a candidate to the contract account\. Fee value i func InnerRingCandidateRemove(key interop.PublicKey) ``` -InnerRingCandidateRemove removes a key from a list of Inner Ring candidates\. It can be invoked by Alphabet nodes or the candidate itself\. +InnerRingCandidateRemove removes a key from a list of Inner Ring candidates. It can be invoked by Alphabet nodes or the candidate itself. -This method does not return fee back to the candidate\. +This method does not return fee back to the candidate. ##### InnerRingCandidates @@ -174,15 +176,15 @@ This method does not return fee back to the candidate\. func InnerRingCandidates() []common.IRNode ``` -InnerRingCandidates returns an array of structures that contain an Inner Ring candidate node key\. +InnerRingCandidates returns an array of structures that contain an Inner Ring candidate node key. ##### OnNEP17Payment ```go -func OnNEP17Payment(from interop.Hash160, amount int, data interface{}) +func OnNEP17Payment(from interop.Hash160, amount int, data any) ``` -OnNEP17Payment is a callback for NEP\-17 compatible native GAS contract\. It takes no more than 9000\.0 GAS\. Native GAS has precision 8\, and NeoFS balance contract has precision 12\. Values bigger than 9000\.0 can break JSON limits for integers when precision is converted\. +OnNEP17Payment is a callback for NEP\-17 compatible native GAS contract. It takes no more than 9000.0 GAS. Native GAS has precision 8, and NeoFS balance contract has precision 12. Values bigger than 9000.0 can break JSON limits for integers when precision is converted. ##### SetConfig @@ -190,7 +192,7 @@ OnNEP17Payment is a callback for NEP\-17 compatible native GAS contract\. It tak func SetConfig(id, key, val []byte) ``` -SetConfig key\-value pair as a NeoFS runtime configuration value\. It can be invoked only by Alphabet nodes\. +SetConfig key\-value pair as a NeoFS runtime configuration value. It can be invoked only by Alphabet nodes. ##### Unbind @@ -198,17 +200,17 @@ SetConfig key\-value pair as a NeoFS runtime configuration value\. It can be inv func Unbind(user []byte, keys []interop.PublicKey) ``` -Unbind method produces notification to unbind the specified public keys in NeoFSID contract in the sidechain\. It can be invoked only by the specified user\. +Unbind method produces notification to unbind the specified public keys in NeoFSID contract in the sidechain. It can be invoked only by the specified user. -This method produces Unbind notification\. This method panics if keys are not 33 byte long\. User argument must be a valid 20 byte script hash\. +This method produces Unbind notification. This method panics if keys are not 33 byte long. User argument must be a valid 20 byte script hash. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked only by sidechain committee\. +Update method updates contract source code and manifest. It can be invoked only by sidechain committee. ##### Version @@ -216,7 +218,7 @@ Update method updates contract source code and manifest\. It can be invoked only func Version() int ``` -Version returns version of the contract\. +Version returns version of the contract. ##### Withdraw @@ -224,8 +226,7 @@ Version returns version of the contract\. func Withdraw(user interop.Hash160, amount int) ``` -Withdraw initializes gas asset withdraw from NeoFS\. It can be invoked only by the specified user\. - -This method produces Withdraw notification to lock assets in the sidechain and transfers withdraw fee from a user account to each Alphabet node\. If notary is enabled in the mainchain\, fee is transferred to Processing contract\. Fee value is specified in NeoFS network config with the key WithdrawFee\. +Withdraw initializes gas asset withdraw from NeoFS. It can be invoked only by the specified user. +This method produces Withdraw notification to lock assets in the sidechain and transfers withdraw fee from a user account to each Alphabet node. If notary is enabled in the mainchain, fee is transferred to Processing contract. Fee value is specified in NeoFS network config with the key WithdrawFee. diff --git a/06-blockchain/03-neofsid.md b/06-blockchain/03-neofsid.md index fb092e5..a7845e6 100644 --- a/06-blockchain/03-neofsid.md +++ b/06-blockchain/03-neofsid.md @@ -1,14 +1,16 @@ ### neofsid contract -NeoFSID contract is a contract deployed in NeoFS sidechain\. -NeoFSID contract is used to store connection between an OwnerID and its public keys\. OwnerID is a 25\-byte N3 wallet address that can be produced from a public key\. It is one\-way conversion\. In simple cases\, NeoFS verifies ownership by checking signature and relation between a public key and an OwnerID\. -In more complex cases\, a user can use public keys unrelated to the OwnerID to maintain secure access to the data\. NeoFSID contract stores relation between an OwnerID and arbitrary public keys\. Data owner can bind a public key with its account or unbind it by invoking Bind or Unbind methods of NeoFS contract in the mainchain\. After that\, Alphabet nodes produce multisigned AddKey and RemoveKey invocations of NeoFSID contract\. +Package neofsid contains implementation of NeoFSID contract deployed in NeoFS sidechain. + +NeoFSID contract is used to store connection between an OwnerID and its public keys. OwnerID is a 25\-byte N3 wallet address that can be produced from a public key. It is one\-way conversion. In simple cases, NeoFS verifies ownership by checking signature and relation between a public key and an OwnerID. + +In more complex cases, a user can use public keys unrelated to the OwnerID to maintain secure access to the data. NeoFSID contract stores relation between an OwnerID and arbitrary public keys. Data owner can bind a public key with its account or unbind it by invoking Bind or Unbind methods of NeoFS contract in the mainchain. After that, Alphabet nodes produce multisigned AddKey and RemoveKey invocations of NeoFSID contract. #### Contract notifications -NeoFSID contract does not produce notifications to process\. +NeoFSID contract does not produce notifications to process. #### Contract methods @@ -18,9 +20,9 @@ NeoFSID contract does not produce notifications to process\. func AddKey(owner []byte, keys []interop.PublicKey) ``` -AddKey binds a list of the provided public keys to the OwnerID\. It can be invoked only by Alphabet nodes\. +AddKey binds a list of the provided public keys to the OwnerID. It can be invoked only by Alphabet nodes. -This method panics if the OwnerID is not an ownerSize byte or the public key is not 33 byte long\. If the key is already bound\, the method ignores it\. +This method panics if the OwnerID is not an ownerSize byte or the public key is not 33 byte long. If the key is already bound, the method ignores it. ##### Key @@ -28,9 +30,9 @@ This method panics if the OwnerID is not an ownerSize byte or the public key is func Key(owner []byte) [][]byte ``` -Key method returns a list of 33\-byte public keys bound with the OwnerID\. +Key method returns a list of 33\-byte public keys bound with the OwnerID. -This method panics if the owner is not ownerSize byte long\. +This method panics if the owner is not ownerSize byte long. ##### RemoveKey @@ -38,17 +40,17 @@ This method panics if the owner is not ownerSize byte long\. func RemoveKey(owner []byte, keys []interop.PublicKey) ``` -RemoveKey unbinds the provided public keys from the OwnerID\. It can be invoked only by Alphabet nodes\. +RemoveKey unbinds the provided public keys from the OwnerID. It can be invoked only by Alphabet nodes. -This method panics if the OwnerID is not an ownerSize byte or the public key is not 33 byte long\. If the key is already unbound\, the method ignores it\. +This method panics if the OwnerID is not an ownerSize byte or the public key is not 33 byte long. If the key is already unbound, the method ignores it. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked only by committee\. +Update method updates contract source code and manifest. It can be invoked only by committee. ##### Version @@ -56,6 +58,5 @@ Update method updates contract source code and manifest\. It can be invoked only func Version() int ``` -Version returns the version of the contract\. - +Version returns the version of the contract. diff --git a/06-blockchain/03-netmap.md b/06-blockchain/03-netmap.md index 547dce0..e47df45 100644 --- a/06-blockchain/03-netmap.md +++ b/06-blockchain/03-netmap.md @@ -1,12 +1,14 @@ ### netmap contract -Netmap contract is a contract deployed in NeoFS sidechain\. -Netmap contract stores and manages NeoFS network map\, Storage node candidates and epoch number counter\. In notary disabled environment\, contract also stores a list of Inner Ring node keys\. + +Package netmap contains implementation of the Netmap contract for NeoFS systems. + +Netmap contract stores and manages NeoFS network map, Storage node candidates and epoch number counter. In notary disabled environment, contract also stores a list of Inner Ring node keys. #### Contract notifications -AddPeer notification\. This notification is produced when a Storage node sends a bootstrap request by invoking AddPeer method\. +AddPeer notification. This notification is produced when a Storage node sends a bootstrap request by invoking AddPeer method. ``` AddPeer @@ -14,7 +16,7 @@ AddPeer type: ByteArray ``` -UpdateState notification\. This notification is produced when a Storage node wants to change its state \(go offline\) by invoking UpdateState method\. Supported states: \(2\) \-\- offline\. +UpdateState notification. This notification is produced when a Storage node wants to change its state \(go offline\) by invoking UpdateState method. Supported states: \(2\) \-\- offline. ``` UpdateState @@ -24,7 +26,7 @@ UpdateState type: PublicKey ``` -NewEpoch notification\. This notification is produced when a new epoch is applied in the network by invoking NewEpoch method\. +NewEpoch notification. This notification is produced when a new epoch is applied in the network by invoking NewEpoch method. ``` NewEpoch @@ -40,9 +42,9 @@ NewEpoch func AddPeer(nodeInfo []byte) ``` -AddPeer method adds a new candidate to the next network map if it was invoked by Alphabet node\. If it was invoked by a node candidate\, it produces AddPeer notification\. Otherwise\, the method throws panic\. +AddPeer proposes a node for consideration as a candidate for the next\-epoch network map. Information about the node is accepted in NeoFS API binary format. Call transaction MUST be signed by the public key sewn into the parameter \(compressed 33\-byte array starting from 3rd byte\), i.e. by candidate itself. If the signature is correct, the Notary service will submit a request for signature by the NeoFS Alphabet. After collecting a sufficient number of signatures, the node will be added to the list of candidates for the next\-epoch network map \('AddPeerSuccess' notification is thrown after that\). -If the candidate already exists\, its info is updated\. NodeInfo argument contains a stable marshaled version of netmap\.NodeInfo structure\. +Note that if the Alphabet needs to complete information about the candidate, it will be added with AddPeerIR. ##### AddPeerIR @@ -50,15 +52,15 @@ If the candidate already exists\, its info is updated\. NodeInfo argument contai func AddPeerIR(nodeInfo []byte) ``` -AddPeerIR method tries to add a new candidate to the network map\. It should only be invoked in notary\-enabled environment by the alphabet\. +AddPeerIR is called by the NeoFS Alphabet instead of AddPeer when signature of the network candidate is inaccessible. For example, when information about the candidate proposed via AddPeer needs to be supplemented. In such cases, a new transaction will be required and therefore the candidate's signature is not verified by AddPeerIR. Besides this, the behavior is similar. ##### Config ```go -func Config(key []byte) interface{} +func Config(key []byte) any ``` -Config returns configuration value of NeoFS configuration\. If key does not exists\, returns nil\. +Config returns configuration value of NeoFS configuration. If key does not exist, returns nil. ##### Epoch @@ -66,7 +68,7 @@ Config returns configuration value of NeoFS configuration\. If key does not exis func Epoch() int ``` -Epoch method returns the current epoch number\. +Epoch method returns the current epoch number. ##### InnerRingList @@ -74,9 +76,11 @@ Epoch method returns the current epoch number\. func InnerRingList() []common.IRNode ``` -InnerRingList method returns a slice of structures that contains the public key of an Inner Ring node\. It should be used in notary disabled environment only\. +InnerRingList method returns a slice of structures that contains the public key of an Inner Ring node. It should be used in notary disabled environment only. + +If notary is enabled, look to NeoFSAlphabet role in native RoleManagement contract of the sidechain. -If notary is enabled\, look to NeoFSAlphabet role in native RoleManagement contract of the sidechain\. +Deprecated: since non\-notary settings are no longer supported, refer only to the RoleManagement contract only. The method will be removed in one of the future releases. ##### LastEpochBlock @@ -84,7 +88,7 @@ If notary is enabled\, look to NeoFSAlphabet role in native RoleManagement contr func LastEpochBlock() int ``` -LastEpochBlock method returns the block number when the current epoch was applied\. +LastEpochBlock method returns the block number when the current epoch was applied. ##### NewEpoch @@ -92,11 +96,11 @@ LastEpochBlock method returns the block number when the current epoch was applie func NewEpoch(epochNum int) ``` -NewEpoch method changes the epoch number up to the provided epochNum argument\. It can be invoked only by Alphabet nodes\. If provided epoch number is less than the current epoch number or equals it\, the method throws panic\. +NewEpoch method changes the epoch number up to the provided epochNum argument. It can be invoked only by Alphabet nodes. If provided epoch number is less than the current epoch number or equals it, the method throws panic. -When epoch number is updated\, the contract sets storage node candidates as the current network map\. The contract also invokes NewEpoch method on Balance and Container contracts\. +When epoch number is updated, the contract sets storage node candidates as the current network map. The contract also invokes NewEpoch method on Balance and Container contracts. -It produces NewEpoch notification\. +It produces NewEpoch notification. ##### SetConfig @@ -104,25 +108,23 @@ It produces NewEpoch notification\. func SetConfig(id, key, val []byte) ``` -SetConfig key\-value pair as a NeoFS runtime configuration value\. It can be invoked only by Alphabet nodes\. +SetConfig key\-value pair as a NeoFS runtime configuration value. It can be invoked only by Alphabet nodes. -##### Update +##### SubscribeForNewEpoch ```go -func Update(script []byte, manifest []byte, data interface{}) +func SubscribeForNewEpoch(contract interop.Hash160) ``` -Update method updates contract source code and manifest\. It can be invoked only by committee\. +SubscribeForNewEpoch registers passed contract as a NewEpoch event subscriber. Such a contract must have a \`NewEpoch\` method with a single numeric parameter. Transactions that call SubscribeForNewEpoch must be witnessed by the Alphabet. Produces \`NewEpochSubscription\` notification event with a just registered recipient in a success case. -##### UpdateInnerRing +##### Update ```go -func UpdateInnerRing(keys []interop.PublicKey) +func Update(script []byte, manifest []byte, data any) ``` -UpdateInnerRing method updates a list of Inner Ring node keys\. It should be used only in notary disabled environment\. It can be invoked only by Alphabet nodes\. - -If notary is enabled\, update NeoFSAlphabet role in native RoleManagement contract of the sidechain\. Use notary service to collect multisignature\. +Update method updates contract source code and manifest. It can be invoked only by committee. ##### UpdateSnapshotCount @@ -130,29 +132,29 @@ If notary is enabled\, update NeoFSAlphabet role in native RoleManagement contra func UpdateSnapshotCount(count int) ``` -UpdateSnapshotCount updates the number of the stored snapshots\. If a new number is less than the old one\, old snapshots are removed\. Otherwise\, history is extended with empty snapshots\, so \`Snapshot\` method can return invalid results for \`diff = new\-old\` epochs until \`diff\` epochs have passed\. +UpdateSnapshotCount updates the number of the stored snapshots. If a new number is less than the old one, old snapshots are removed. Otherwise, history is extended with empty snapshots, so \`Snapshot\` method can return invalid results for \`diff = new\-old\` epochs until \`diff\` epochs have passed. + +Count MUST NOT be negative. ##### UpdateState ```go -func UpdateState(state int, publicKey interop.PublicKey) +func UpdateState(state NodeState, publicKey interop.PublicKey) ``` -UpdateState method updates the state of a node from the network map candidate list\. For notary\-ENABLED environment\, tx must be signed by both storage node and alphabet\. To force update without storage node signature\, see \`UpdateStateIR\`\. +UpdateState proposes a new state of candidate for the next\-epoch network map. The candidate is identified by the given public key. Call transaction MUST be signed by the provided public key, i.e. by node itself. If the signature is correct, the Notary service will submit a request for signature by the NeoFS Alphabet. After collecting a sufficient number of signatures, the candidate's state will be switched to the given one \('UpdateStateSuccess' notification is thrown after that\). -For notary\-DISABLED environment\, the behaviour depends on who signed the transaction: 1\. If it was signed by alphabet\, go into voting\. 2\. If it was signed by a storage node\, emit \`UpdateState\` notification\. 2\. Fail in any other case\. +UpdateState panics if requested candidate is missing in the current candidate set. UpdateState drops candidate from the candidate set if it is switched to NodeStateOffline. -The behaviour can be summarized in the following table: | notary \\ Signer | Storage node | Alphabet | Both | | ENABLED | FAIL | FAIL | OK | | DISABLED | NOTIFICATION | OK | OK \(same as alphabet\) | State argument defines node state\. The only supported state now is \(2\) \-\- offline state\. Node is removed from the network map candidate list\. - -Method panics when invoked with unsupported states\. +State MUST be from the NodeState enum. Public key MUST be interop.PublicKeyCompressedLen bytes. ##### UpdateStateIR ```go -func UpdateStateIR(state nodeState, publicKey interop.PublicKey) +func UpdateStateIR(state NodeState, publicKey interop.PublicKey) ``` -UpdateStateIR method tries to change the node state in the network map\. Should only be invoked in notary\-enabled environment by alphabet\. +UpdateStateIR is called by the NeoFS Alphabet instead of UpdateState when signature of the network candidate is inaccessible. In such cases, a new transaction will be required and therefore the candidate's signature is not verified by UpdateStateIR. Besides this, the behavior is similar. ##### Version @@ -160,6 +162,5 @@ UpdateStateIR method tries to change the node state in the network map\. Should func Version() int ``` -Version returns the version of the contract\. - +Version returns the version of the contract. diff --git a/06-blockchain/03-processing.md b/06-blockchain/03-processing.md index 94ae2c8..d5b234d 100644 --- a/06-blockchain/03-processing.md +++ b/06-blockchain/03-processing.md @@ -1,32 +1,34 @@ ### processing contract -Processing contract is a contract deployed in NeoFS mainchain\. -Processing contract pays for all multisignature transaction executions when notary service is enabled in the mainchain\. Notary service prepares multisigned transactions\, however they should contain sidechain GAS to be executed\. It is inconvenient to ask Alphabet nodes to pay for these transactions: nodes can change over time\, some nodes will spend sidechain GAS faster\. It leads to economic instability\. -Processing contract exists to solve this issue\. At the Withdraw invocation of NeoFS contract\, a user pays fee directly to this contract\. This fee is used to pay for Cheque invocation of NeoFS contract that returns mainchain GAS back to the user\. The address of the Processing contract is used as the first signer in the multisignature transaction\. Therefore\, NeoVM executes Verify method of the contract and if invocation is verified\, Processing contract pays for the execution\. +Package processing contains implementation of Processing contract deployed in NeoFS mainchain. + +Processing contract pays for all multisignature transaction executions when notary service is enabled in the mainchain. Notary service prepares multisigned transactions, however they should contain sidechain GAS to be executed. It is inconvenient to ask Alphabet nodes to pay for these transactions: nodes can change over time, some nodes will spend sidechain GAS faster. It leads to economic instability. + +Processing contract exists to solve this issue. At the Withdraw invocation of NeoFS contract, a user pays fee directly to this contract. This fee is used to pay for Cheque invocation of NeoFS contract that returns mainchain GAS back to the user. The address of the Processing contract is used as the first signer in the multisignature transaction. Therefore, NeoVM executes Verify method of the contract and if invocation is verified, Processing contract pays for the execution. #### Contract notifications -Processing contract does not produce notifications to process\. +Processing contract does not produce notifications to process. #### Contract methods ##### OnNEP17Payment ```go -func OnNEP17Payment(from interop.Hash160, amount int, data interface{}) +func OnNEP17Payment(from interop.Hash160, amount int, data any) ``` -OnNEP17Payment is a callback for NEP\-17 compatible native GAS contract\. +OnNEP17Payment is a callback for NEP\-17 compatible native GAS contract. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked only by the sidechain committee\. +Update method updates contract source code and manifest. It can be invoked only by the sidechain committee. ##### Verify @@ -34,7 +36,7 @@ Update method updates contract source code and manifest\. It can be invoked only func Verify() bool ``` -Verify method returns true if transaction contains valid multisignature of Alphabet nodes of the Inner Ring\. +Verify method returns true if transaction contains valid multisignature of Alphabet nodes of the Inner Ring. ##### Version @@ -42,6 +44,5 @@ Verify method returns true if transaction contains valid multisignature of Alpha func Version() int ``` -Version returns the version of the contract\. - +Version returns the version of the contract. diff --git a/06-blockchain/03-proxy.md b/06-blockchain/03-proxy.md index 90c0865..91cd2dd 100644 --- a/06-blockchain/03-proxy.md +++ b/06-blockchain/03-proxy.md @@ -1,32 +1,34 @@ ### proxy contract -Proxy contract is a contract deployed in NeoFS sidechain\. -Proxy contract pays for all multisignature transaction executions when notary service is enabled in the sidechain\. Notary service prepares multisigned transactions\, however they should contain sidechain GAS to be executed\. It is inconvenient to ask Alphabet nodes to pay for these transactions: nodes can change over time\, some nodes will spend sidechain GAS faster\. It leads to economic instability\. -Proxy contract exists to solve this issue\. While Alphabet contracts hold all sidechain NEO\, proxy contract holds most of the sidechain GAS\. Alphabet contracts emit half of the available GAS to the proxy contract\. The address of the Proxy contract is used as the first signer in a multisignature transaction\. Therefore\, NeoVM executes Verify method of the contract; and if invocation is verified\, Proxy contract pays for the execution\. +Package proxy contains implementation of Proxy contract deployed in NeoFS sidechain. + +Proxy contract pays for all multisignature transaction executions when notary service is enabled in the sidechain. Notary service prepares multisigned transactions, however they should contain sidechain GAS to be executed. It is inconvenient to ask Alphabet nodes to pay for these transactions: nodes can change over time, some nodes will spend sidechain GAS faster. It leads to economic instability. + +Proxy contract exists to solve this issue. While Alphabet contracts hold all sidechain NEO, proxy contract holds most of the sidechain GAS. Alphabet contracts emit half of the available GAS to the proxy contract. The address of the Proxy contract is used as the first signer in a multisignature transaction. Therefore, NeoVM executes Verify method of the contract; and if invocation is verified, Proxy contract pays for the execution. #### Contract notifications -Proxy contract does not produce notifications to process\. +Proxy contract does not produce notifications to process. #### Contract methods ##### OnNEP17Payment ```go -func OnNEP17Payment(from interop.Hash160, amount int, data interface{}) +func OnNEP17Payment(from interop.Hash160, amount int, data any) ``` -OnNEP17Payment is a callback for NEP\-17 compatible native GAS contract\. +OnNEP17Payment is a callback for NEP\-17 compatible native GAS contract. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked only by committee\. +Update method updates contract source code and manifest. It can be invoked only by committee. ##### Verify @@ -34,7 +36,7 @@ Update method updates contract source code and manifest\. It can be invoked only func Verify() bool ``` -Verify method returns true if transaction contains valid multisignature of Alphabet nodes of the Inner Ring\. +Verify method returns true if transaction contains valid multisignature of Alphabet nodes of the Inner Ring. ##### Version @@ -42,6 +44,5 @@ Verify method returns true if transaction contains valid multisignature of Alpha func Version() int ``` -Version returns the version of the contract\. - +Version returns the version of the contract. diff --git a/06-blockchain/03-reputation.md b/06-blockchain/03-reputation.md index 4e0e208..6c23829 100644 --- a/06-blockchain/03-reputation.md +++ b/06-blockchain/03-reputation.md @@ -1,14 +1,14 @@ ### reputation contract -Reputation contract is a contract deployed in NeoFS sidechain\. -Inner Ring nodes produce data audit for each container during each epoch\. In the end\, nodes produce DataAuditResult structure that contains information about audit progress\. Reputation contract provides storage for such structures and simple interface to iterate over available DataAuditResults on specified epoch\. -During settlement process\, Alphabet nodes fetch all DataAuditResult structures from the epoch and execute balance transfers from data owners to Storage and Inner Ring nodes if data audit succeeds\. +Package reputation contains implementation of Reputation contract deployed in NeoFS sidechain. + +Storage nodes collect reputation data while communicating with other nodes. This data is exchanged and the end result \(global trust values\) is stored in the contract as opaque data. #### Contract notifications -Reputation contract does not produce notifications to process\. +Reputation contract does not produce notifications to process. #### Contract methods @@ -18,7 +18,7 @@ Reputation contract does not produce notifications to process\. func Get(epoch int, peerID []byte) [][]byte ``` -Get method returns a list of all stable marshaled DataAuditResult structures produced by the specified Inner Ring node during the specified epoch\. +Get method returns a list of all stable marshaled GlobalTrust structures known for the given peer during the specified epoch. ##### GetByID @@ -26,7 +26,7 @@ Get method returns a list of all stable marshaled DataAuditResult structures pro func GetByID(id []byte) [][]byte ``` -GetByID method returns a list of all stable marshaled DataAuditResult with the specified id\. Use ListByEpoch method to obtain the id\. +GetByID method returns a list of all stable marshaled GlobalTrust with the specified id. Use ListByEpoch method to obtain the id. ##### ListByEpoch @@ -34,7 +34,7 @@ GetByID method returns a list of all stable marshaled DataAuditResult with the s func ListByEpoch(epoch int) [][]byte ``` -ListByEpoch returns a list of IDs that may be used to get reputation data with GetByID method\. +ListByEpoch returns a list of IDs that may be used to get reputation data with GetByID method. ##### Put @@ -42,17 +42,17 @@ ListByEpoch returns a list of IDs that may be used to get reputation data with G func Put(epoch int, peerID []byte, value []byte) ``` -Put method saves DataAuditResult in contract storage\. It can be invoked only by Inner Ring nodes\. It does not require multisignature invocations\. +Put method saves global trust data in contract storage. It can be invoked only by storage nodes with Alphabet assistance \(multisignature witness\). -Epoch is the epoch number when DataAuditResult structure was generated\. PeerID contains public keys of the Inner Ring node that has produced DataAuditResult\. Value contains a stable marshaled structure of DataAuditResult\. +Epoch is the epoch number when GlobalTrust structure was generated. PeerID contains public key of the storage node that is the subject of the GlobalTrust. Value contains a stable marshaled structure of GlobalTrust. ##### Update ```go -func Update(script []byte, manifest []byte, data interface{}) +func Update(script []byte, manifest []byte, data any) ``` -Update method updates contract source code and manifest\. It can be invoked only by committee\. +Update method updates contract source code and manifest. It can be invoked only by committee. ##### Version @@ -60,6 +60,5 @@ Update method updates contract source code and manifest\. It can be invoked only func Version() int ``` -Version returns the version of the contract\. - +Version returns the version of the contract.