From 18cc26f8c434c447cbd1461c11c4c3fb06858701 Mon Sep 17 00:00:00 2001
From: Alex Vanin <alexey@nspcc.ru>
Date: Wed, 7 Jul 2021 18:34:03 +0300
Subject: [PATCH] [#105] proxy: Add docs

Signed-off-by: Alex Vanin <alexey@nspcc.ru>
---
 proxy/doc.go            | 21 ++++++++++++++++++++-
 proxy/proxy_contract.go |  6 ++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/proxy/doc.go b/proxy/doc.go
index 3fd83a9..6758b57 100644
--- a/proxy/doc.go
+++ b/proxy/doc.go
@@ -1,2 +1,21 @@
-// Proxy contract description.
+/*
+Proxy contract is a contract deployed in NeoFS side chain.
+
+Proxy contract pays for all multi signature transaction executions when notary
+service enabled in side chain. Notary service prepares multi signed transaction,
+however they should contain side chain 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 side chain GAS faster, it creates economic instability.
+
+Proxy contract exists to solve this issue. While Alphabet contracts hold all
+side chain NEO, proxy contract holds most of the side chain GAS. Alphabet
+contracts emits half of the available GAS to the proxy contract. Address of the
+Proxy contract is used as the first signer in the multi signature transaction.
+Therefore NeoVM executes Verify method of the contract and if invocation is
+verified, then Proxy contract pays for the execution.
+
+Contract notifications
+
+Proxy contract does not produce notifications to process.
+*/
 package proxy
diff --git a/proxy/proxy_contract.go b/proxy/proxy_contract.go
index 832fc85..44ad859 100644
--- a/proxy/proxy_contract.go
+++ b/proxy/proxy_contract.go
@@ -17,6 +17,7 @@ const (
 	netmapContractKey = "netmapScriptHash"
 )
 
+// OnNEP17Payment is a callback for NEP-17 compatible native GAS contract.
 func OnNEP17Payment(from interop.Hash160, amount int, data interface{}) {
 	caller := runtime.GetCallingScriptHash()
 	if !common.BytesEqual(caller, []byte(gas.Hash)) {
@@ -49,6 +50,8 @@ func _deploy(data interface{}, isUpdate bool) {
 	runtime.Log("proxy contract initialized")
 }
 
+// Migrate method updates contract source code and manifest. Can be invoked
+// only by contract owner.
 func Migrate(script []byte, manifest []byte, data interface{}) bool {
 	ctx := storage.GetReadOnlyContext()
 
@@ -63,6 +66,8 @@ func Migrate(script []byte, manifest []byte, data interface{}) bool {
 	return true
 }
 
+// Verify method returns true if transaction contains valid multi signature of
+// Alphabet nodes of the Inner Ring.
 func Verify() bool {
 	alphabet := neo.GetCommittee()
 	sig := common.Multiaddress(alphabet, false)
@@ -75,6 +80,7 @@ func Verify() bool {
 	return true
 }
 
+// Version returns version of the contract.
 func Version() int {
 	return version
 }