Merge pull request #3692 from nspcc-dev/basicchain-doc

*: extend basic testing chain documentation

pkg/core/basic_chain_test.go

@@ -29,11 +29,13 @@ var (
 	pathToInternalContracts = filepath.Join("..", "..", "internal", "contracts")
 )
 
-// TestCreateBasicChain generates "../rpc/testdata/testblocks.acc" file which
+// TestCreateBasicChain generates "pkg/services/rpcsrv/testdata/testblocks.acc" file which
 // contains data for RPC unit tests. It also is a nice integration test.
-// To generate new "../rpc/testdata/testblocks.acc", follow the steps:
+// To generate new "pkg/services/rpcsrv/testdata/testblocks.acc", follow the steps:
 //  1. Set saveChain down below to true
 //  2. Run tests with `$ make test`
+//  3. Update relevant constants and variables used by RPC server unit tests
+//     in "pkg/services/rpcsrv/server_test.go".
 func TestCreateBasicChain(t *testing.T) {
 	const saveChain = false
 

pkg/services/rpcsrv/server_helper_test.go

@@ -89,12 +89,10 @@ func getUnitTestChainWithCustomConfig(t testing.TB, enableOracle bool, enableNot
 }
 
 func getTestBlocks(t *testing.T) []*block.Block {
-	// File "./testdata/testblocks.acc" was generated by function core.TestCreateBasicChain
+	// File "./testdata/testblocks.acc" was generated by unit-test
-	// ("neo-go/pkg/core/helper_test.go").
+	// [core.TestCreateBasicChain] ("neo-go/pkg/core/basic_chain_test.go"). To
-	// To generate new "./testdata/testblocks.acc", follow the steps:
+	// generate new "./testdata/testblocks.acc", follow the steps provided in the
-	// 		1. Rename the function
+	// unit-test documentation.
-	// 		2. Add specific test-case into "neo-go/pkg/core/blockchain_test.go"
-	// 		3. Run tests with `$ make test`
 	f, err := os.Open("testdata/testblocks.acc")
 	require.Nil(t, err)
 	br := io.NewBinReaderFromIO(f)

pkg/services/rpcsrv/server_test.go

@@ -73,30 +73,70 @@ type rpcTestCase struct {
 	check   func(t *testing.T, e *executor, result any)
 }
 
-const genesisBlockHash = "0f8fb4e17d2ab9f3097af75ca7fd16064160fb8043db94909e00dd4e257b9dc4"
+// Constants and variables below are taken from the logs generated by
-const testContractHash = "449fe8fbd4523072f5e3a4dfa17a494c119d4c08"
+// [core.TestCreateBasicChain]. These constants and variables should be updated manually
-const deploymentTxHash = "bbb8ec059dd320dc9de5a8fb8c75351d8e369fca0256f7a6bdb623dcf71861ed"
+// on basic chain regeneration. Please, refer to TestCreateBasicChain documentation
-
+// to learn about basic testing chain generation.
 const (
-	verifyContractHash                = "06ed5314c2e4cb103029a60b86d46afa2fb8f67c"
+	// genesisBlockHash is an LE hash of genesis block in basic testing chain.
-	verifyContractAVM                 = "VwIAQS1RCDBwDBTunqIsJ+NL0BSPxBCOCPdOj1BIskrZMCQE2zBxaBPOStkoJATbKGlK2SgkBNsol0A="
+	genesisBlockHash = "0f8fb4e17d2ab9f3097af75ca7fd16064160fb8043db94909e00dd4e257b9dc4"
-	verifyWithArgsContractHash        = "6261b3bf753bdc3d24c1327a23fd891e1c8a7ccd"
+	// testContractHash is an LE hash of NEP-17 "Rubl" contract deployed at block #2
-	nnsContractHash                   = "450d1918a72fef97b48096bfec8d749961deef55"
+	// of basic testing chain.
-	nnsToken1ID                       = "6e656f2e636f6d"
+	testContractHash = "449fe8fbd4523072f5e3a4dfa17a494c119d4c08"
-	nfsoContractHash                  = "914246ab7888ba4eb3ddebc9cb5433c2edcc1671"
+	// deploymentTxHash is an LE hash of transaction that deploys NEP-17 "Rubl"
-	nfsoToken1ID                      = "7e244ffd6aa85fb1579d2ed22e9b761ab62e3486"
+	// contract at block #2 of basic testing chain.
-	storageContractHash               = "ebc0c16a76c808cd4dde6bcc063f09e45e331ec7"
+	deploymentTxHash = "bbb8ec059dd320dc9de5a8fb8c75351d8e369fca0256f7a6bdb623dcf71861ed"
-	faultedTxHashLE                   = "82279bfe9bada282ca0f8cb8e0bb124b921af36f00c69a518320322c6f4fef60"
+	// verifyContractHash is an LE hash of "Verify" contract deployed at block #7 of
-	faultedTxBlock             uint32 = 23
+	// basic testing chain.
-	invokescriptContractAVM           = "VwIADBQBDAMOBQYMDQIODw0DDgcJAAAAAErZMCQE2zBwaEH4J+yMqiYEEUAMFA0PAwIJAAIBAwcDBAUCAQAOBgwJStkwJATbMHFpQfgn7IyqJgQSQBNA"
+	verifyContractHash = "06ed5314c2e4cb103029a60b86d46afa2fb8f67c"
-	block20StateRootLE                = "394e20adf99a6ba160df7351770dfb193ee8af174b7b3ed45f4e2ae8c43694e8"
+	// verifyContractAVM is a base64-encoded AVM of "Verify" contract deployed at block #7 of
+	// basic testing chain.
+	verifyContractAVM = "VwIAQS1RCDBwDBTunqIsJ+NL0BSPxBCOCPdOj1BIskrZMCQE2zBxaBPOStkoJATbKGlK2SgkBNsol0A="
+	// verifyWithArgsContractHash is an LE hash of "VerifyWithArgs" contract deployed
+	// at block #10 of basic testing chain.
+	verifyWithArgsContractHash = "6261b3bf753bdc3d24c1327a23fd891e1c8a7ccd"
+	// nnsContractHash is an LE hash of NEP-11 non-divisible "examples/nft-nd-nns"
+	// contract deployed at block #11 of basic testing chain.
+	nnsContractHash = "450d1918a72fef97b48096bfec8d749961deef55"
+	// nnsToken1ID is a hex-encoded ID of the first NEP-11 NNS token minted at block
+	// #14 of basic testing chain.
+	nnsToken1ID = "6e656f2e636f6d"
+	// nfsoContractHash is an LE hash of NEP-11 divisible "examples/nft-d" ("NeoFS
+	// Object") contract deployed at block #17 of basic testing chain.
+	nfsoContractHash = "914246ab7888ba4eb3ddebc9cb5433c2edcc1671"
+	// nfsoToken1ID is a hex-encoded ID of the first NEP-11 NFSO token minted at
+	// block #18 of basic testing chain.
+	nfsoToken1ID = "7e244ffd6aa85fb1579d2ed22e9b761ab62e3486"
+	// storageContractHash is an LE hash of "Storage" contract deployed at block #22
+	// of basic testing chain.
+	storageContractHash = "ebc0c16a76c808cd4dde6bcc063f09e45e331ec7"
+	// faultedTxHashLE is an LE hash of FAULTed transaction accepted at block #23 of
+	// basic testing chain.
+	faultedTxHashLE = "82279bfe9bada282ca0f8cb8e0bb124b921af36f00c69a518320322c6f4fef60"
+	// faultedTxBlock is the number of block of basic testing chain that contains
+	// FAULTed transaction.
+	faultedTxBlock uint32 = 23
+	// invokescriptContractAVM is a base64-encoded AVM of
+	// "pkg/internal/basicchain/testdata/invokescript_contract.go" contract that is
+	// not yet deployed to the testing basic chain.
+	invokescriptContractAVM = "VwIADBQBDAMOBQYMDQIODw0DDgcJAAAAAErZMCQE2zBwaEH4J+yMqiYEEUAMFA0PAwIJAAIBAwcDBAUCAQAOBgwJStkwJATbMHFpQfgn7IyqJgQSQBNA"
+	// block20StateRootLE is an LE stateroot of block #20 of basic testing chain.
+	block20StateRootLE = "394e20adf99a6ba160df7351770dfb193ee8af174b7b3ed45f4e2ae8c43694e8"
 )
 
 var (
-	nnsHash, _            = util.Uint160DecodeStringLE(nnsContractHash)
+	// nnsHash is a hash of NEP-11 non-divisible "examples/nft-nd-nns" contract
-	nfsoHash, _           = util.Uint160DecodeStringLE(nfsoContractHash)
+	// deployed at block #11 of basic testing chain.
+	nnsHash, _ = util.Uint160DecodeStringLE(nnsContractHash)
+	// nfsoHash is a hash of NEP-11 divisible "examples/nft-d" ("NeoFS
+	// Object") contract deployed at block #17 of basic testing chain.
+	nfsoHash, _ = util.Uint160DecodeStringLE(nfsoContractHash)
+	// nfsoToken1ContainerID contains data used to mint the first NFSO token in the
+	// basic testing chain (see [nfsoToken1ID] documentation).
 	nfsoToken1ContainerID = util.Uint256{1, 2, 3}
-	nfsoToken1ObjectID    = util.Uint256{4, 5, 6}
+	// nfsoToken1ContainerID contains data used to mint the first NFSO token in the
+	// basic testing chain (see [nfsoToken1ID] documentation).
+	nfsoToken1ObjectID = util.Uint256{4, 5, 6}
 )
 
 var rpcFunctionsWithUnsupportedStatesTestCases = map[string][]rpcTestCase{