[DOC] enhance integrator docs

[amgando]

Add the following to integrator section

• [x] What contracts should we be aware of right now?

• "Lockup / vesting" contract & "staking / delegation" contract https://github.com/near/initial-contracts

• [x] Can we have a look at the Ledger App implementation?

• https://github.com/near/near-ledger-app

• [x] Does a validator control funds that have been delegated to them?

• Delegation is custodial (you are transferring funds to a different account, the smart contract that implements staking pool)

• We provide a reference impl. being sec reviewed now. being tested by 100 validators now

• We allow validators to write and deploy new contracts. up to users to decide if they want to delegate

• Validators can impl diff logic and conditions around tax optimization, etc.

• Currently no slashing but will be added as we add shards into the system. at that point validators can add an option to shield delegators from slashing (similar to tezos model)

• [x] How do we get the balance of an account after it has delegated funds?

• Need to query staking pool to get balance

• [x] How old can the referenced block hash be before it's invalid?

• About 1 epoch

• There is a genesis param. to discover genesis params use:

http post https://rpc.testnet.near.org jsonrpc=2.0 id=dontcare method=EXPERIMENTAL_genesis_config

In the response we find "epoch_length":43200 (seconds, ~ 12 hrs)

• [x] Where can I learn more about transactions and epochs?

• Life of a transaction https://docs.near.org/docs/concepts/transaction

• What is an epoch? https://docs.near.org/docs/validator/validator-faq#what-is-an-epoch

• [x] What are the hardware requirements for running node?

• https://docs.near.org/docs/roles/validator/hardware

• [x] How do we serialize transactions?

• Simple binary serialization format that's deterministic https://borsh.io

• We have a simplified version implemented in C# here: https://github.com/nearprotocol/near-client-unity/blob/master/Src/NearClientUnity/Transaction.cs#L34

• [x] How do we follow Tx status?

• https://docs.near.org/docs/interaction/rpc#transaction-status

• [x] How do we know how much gas to put?

• Reference documentation https://nomicon.io/Economics/README.html

• API documentation https://docs.near.org/docs/interaction/rpc#gas-price

• Issuer of a transaction should attach some amount of gas by taking a guess at budget which will get the transaction processed

• Contract knows how much to fund different cross contract calls

• Gas price is per block, it's fixed, changes from block to block depending on how full the block is. if blocks become more than half full then it increases.

• We're considering adding a max gas price limit

• [x] Is phase 1 expecting any breaking changes to serialization or transaction handling?

• Everything we're currently planning is backwards compatible

[amgando]

cc @ilblackdragon @eriktrautman in case we want to share updates to the docs or if i missed something here from my notes

[amgando]

add notes from email thread with @bowenwang1996 's reply

• [x] Which hash function/algorithm is used in the signing process?

We support both secp256k1 and ed25519 for account keys.

• [x] How are addresses generated

Please check out the spec here on accounts https://nomicon.io/DataStructures/Account.html.

• [x] What is signed? How is the hash preimage generated? Which fields does the raw transaction consist of?

For a transaction, we sign the hash of the transaction. More specifically, what is signed is the sha256 of the transaction object serialized in borsh (https://github.com/near/borsh). For more details on the transaction object, please check out https://docs.near.org/docs/concepts/transaction.

• [x] Can we see code examples? – preferably in C#, C++, JS, PHYTON or… (in preferred order)

We don't have an implementation in C# or C++. For JS implementation, checkout https://github.com/near/near-api-js/blob/d7f0cb87ec320b723734045a4ee9d17d94574a19/src/transaction.ts#L212. For python implementation, checkout https://github.com/nearprotocol/nearcore/blob/bbd3b9458f46f4b4b0c00f2577b4d8b7b3652920/pytest/lib/transaction.py#L130. Please note that the python implementation is used purely for testing purposes so might not be as polished.

• [x] How many keys are used?

An account can have arbitrarily many keys, as long as it has enough tokens for their storage.

• [x] Which balance look-ups exists? What is required?

We have a RPC for viewing account state https://docs.near.org/docs/interaction/rpc#view_account. JS implementation https://github.com/near/near-api-js/blob/d7f0cb87ec320b723734045a4ee9d17d94574a19/src/providers/json-rpc-provider.ts#L73. Note that in this rpc you can specify the finality requirement (whether to query the latest state or finalized state). For custody purposes, it is recommended not to rely on latest state but only what is finalized.

• [ ] How are the transactions published to the Blockchain?

This is a very broad question and can take an hour or more to answer in full detail. In short transactions are included in chunks. You can think of a chunk as a shard block. Chunk headers are included in blocks. If you want to learn more, https://docs.near.org/docs/roles/integrator/errors/introduction#the-life-of-a-transaction provides a good start.

• [ ] Any development plans for the crypto? – planned changes in handling/signing etc.

For account keys I don't think we plan to change anything. We may support additional curves in the future (I am not aware of any that we are actively considering). For validator keys we are considering switching to bls, but I think that is not important for custody purposes.

• [ ] Is it possible to get access to developers, who know the crypto?

We mostly use standard libraries and for signing transactions, there is no crypto that we write on our own.

[bowenwang1996]

The question about How old can the referenced block hash be before it's invalid? is confusing. It should specify that this is the reference block hash for transactions. Also we currently set it to 86400.

Also note that in the following answer I was talking about crypto related to transactions specifically.

We mostly use standard libraries and for signing transactions, there is no crypto that we write on our own.

We do have crypto that we developed on our own but not for anything related to transactions.

[amgando]

nice, thanks @bowenwang1996

adding @ilblackdragon's clarification from the email thread as well:

To clarify for question of transaction validity, it's 86400 blocks or ~24 hours: https://github.com/nearprotocol/nearcore/blob/master/neard/res/mainnet_genesis.json#L212