near / docs Goto Github PK

After clicking on the Near Studio quickstart link at the beginning of the Place game tutorial, I am brought to Near Studio. When I click "run" I get the following error:

[error]: Task build failed: Invalid code point 6695714

Describe the bug
browse any docs page on github and notice that the image links are broken

Expected behavior
would be better if images rendered properly on docs.nearprotocol.com as well as github

📝 Location
https://github.com/nearprotocol/docs/blob/757e3e0effd0aad85445385085358d6bfd400099/docs/local-setup/local-dev-testnet.md

See: https://www.dropbox.com/s/tbvpsy551ihn0v1/documents_copypast.mov?dl=0

Describe the bug
Contribution guideline ideally should be at the most prominent place.
Right now it's under "Community" > "Contribution Guidelines" > "Nearcore"
Specifically, we need the section about development in staging (and that it's the active branch) be very visible to everyone.
But also I always use Operations section for my copy&paste

Clicking any link not within docs.nearprotocol.com should automatically open in a new tab to avoid ejecting the user annoyingly from the docs.

Nothing big but after calling:

near new_project [YOUR_PROJECT_DIR]

Running cd ./[YOUR_PROJECT_DIR] && npm install is still required

EDIT: This is described in the README but would be good to add to docs too.

We should add to the documentation (or to the start_node script) comment by @ailisp from
near/nearcore#1551.

Is your feature request related to a problem? Please describe.
Currently nearlib doesn't have any textual description or examples how to use it

Describe the solution you'd like
We need to have brief details about nearlib and then few examples on how to use nearlb

Is your feature request related to a problem? Please describe.
The goal is to make it easy for people to integrate into wallets / backend applications.

Current nearlib README (https://github.com/nearprotocol/nearlib) doesn't contain any examples of usage or links to such examples.

Same true about docs: we have "FRONTEND API (NEARLIB)" with a huge list of API items, but nothing how to use it.

Describe the solution you'd like
For this, we need a page with details how to use nearlib to create key pairs, create transactions, sign a transaction and send it to the network.

Additional context
Examples:

• Intro README.md which describes high level ideas and shows how to sign & submit a tx https://github.com/EOSIO/eosjs#sending-a-transaction
• Step by step guide to do different things with js library - https://github.com/meet-one/eosjs-guide
• Usage section here https://github.com/cosmos/cosmos-sdk-js#usage

https://nearprotocol.com
Imo, best is edit that link when creating a new one so it never expires.

https://docs.nearprotocol.com/api-documentation/rpc

"sends transaction and returns right away with the hash of the transaction in base58."

should be

"sends transaction and returns right away with the hash of the transaction in base64."

Herd developers to write tutorials. Goal to have at least 3 meaningful tutorials with one clear super tutorial.

https://docs.nearprotocol.com/docs/local-setup/create-account#backup-private-key-manually describes how to backup keys manually from browser local storage.

However the recovery for such keys isn't supported. We should instead suggest to setup backup&recovery using seed phrase.

I'm following along with the "place" game tutorial. When I get to the second paragraph of step 3 I'm instructed to run the tests. Doing so results in the following errors:

[info]: Task build is running...
ERROR TS2304: Cannot find name 'globalStorage'.

   globalStorage.setItem(coords, value);
   ~~~~~~~~~~~~~
 in main.ts(4,2)


ERROR TS2304: Cannot find name 'globalStorage'.

   return globalStorage.getItem(coords);
          ~~~~~~~~~~~~~
 in main.ts(8,9)


WARNING AS102: User-defined: "Calling 'memory.allocate' requires a memory manager to be present."

     WARNING("Calling 'memory.allocate' requires a memory manager to be present.");
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 in ~lib/memory.ts(42,4)


WARNING AS102: User-defined: "Calling 'memory.allocate' requires a memory manager to be present."

     WARNING("Calling 'memory.allocate' requires a memory manager to be present.");
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 in ~lib/memory.ts(42,4)


ERROR TS2304: Cannot find name 'globalStorage'.

       let cellEntry = globalStorage.getItem(near.str(row) + "," + near.str(col));
                       ~~~~~~~~~~~~~
 in main.ts(19,22)


ERROR AS200: Conversion from type 'i32' to 'String' requires an explicit cast.

       arrResult[i] = cellEntry;
                      ~~~~~~~~~
 in main.ts(20,21)


WARNING AS102: User-defined: "Calling 'memory.free' requires a memory manager to be present."

     WARNING("Calling 'memory.free' requires a memory manager to be present.");
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 in ~lib/memory.ts(48,4)


[error]: Task build failed: Compile error

Is your feature request related to a problem? Please describe.
We don't seem to have anything that surfaces and contextualizes nearcore primitives like block and chunk.

Describe the solution you'd like
The nearcore source files are well commented but a primer would likely include a few links out to resources for understanding Merkle trees, Public Key Cryptography and other common knowledge among crypto enthusiasts.

Additional context
Here's an example of a clear, concise intro to Merkle Trees including basic mechanisms of use and justification for the technology

https://media.consensys.net/ever-wonder-how-merkle-trees-work-c2f8b7100ed3

Is your feature request related to a problem? Please describe.
People have older version of node and our tools don't work. Errors are also not clear.

Describe the solution you'd like
Have version of node required (at least 12) on all the pages that mention near-shell

Describe the bug
Currently it says "Send Transaction (In development)" https://docs.nearprotocol.com/docs/interaction/rpc#send-transaction-in-development which is not true as we actually using this RPC for most of nearlib.

Expected behavior
Title: Send Transaction (wait until done)

RPC:

http post http://127.0.0.1:3030/ jsonrpc=2.0 method=broadcast_tx_commit params:="[<base 58 of the SignedTransaction>]" id="dontcare"

Result:

{"jsonrpc":"2.0","result":{"status":"Completed","transactions":[{"hash":"GLTdMcUAVT5DB6YEWABcMgASFuPGFMCbQkC8TcvZdby3","result":{"logs":[],"receipts":["8YrftHfvmDA4EAwf6BZe3d5TQd51joJW3JHpoj4iAUBF"],"result":null,"status":"Completed"}},{"hash":"8YrftHfvmDA4EAwf6BZe3d5TQd51joJW3JHpoj4iAUBF","result":{"logs":[],"receipts":[],"result":"","status":"Completed"}}]},"id":133}

Describe the bug
Going to https://docs.nearprotocol.com/docs/overview/who-is-this-for.html
Title is "Who is this for? - undefined"

Expected behavior
No undefined. Or something meaningful

Screenshots

📝 Location
https://docs.nearprotocol.com/docs/overview/who-is-this-for.html

Pynear is broken and deprecated. We should remove it from the documentation + update it with Near Shell once it's been updated with full functionality

https://docs.nearprotocol.com/docs/validator/staking

Describe the bug & expected behaviour
Currently there when I click "Become a validator" I expect to have a full materials from how to start node locally, on Google or whatever cloud, how to create account and how to stake.

Instead there are few links to other docs which doesn't seem like people see and follow.

Finding "Running a node" under "Local Setup" is unexpected.
"Running a node on Windows" goes before "Running a node" in the list is also strange.

In "Running a node" the section for Google cloud is at the end. May be worth separating it into separate section which then links to the running node https://docs.nearprotocol.com/docs/local-setup/running-testnet#running-official-testnet-node-with-docker section for actually how to start.

Needs updating to actually function.

Describe the bug
docs/runtime-ts/classes/_contract_.contractpromise.md (is it auto-generated?) features .then() usage with a wrong number of arguments (the first argument must be contract name).

  let callbackPromise = promise.then(
     "_onItemAdded",
     requestArgs.encode(),
     2,  // Attaching 2 additional requests, in case we need to do another call
  );

The comment about the number 2 is completely misleading. It is a gas amount and it should be a much greater number, e.g. 100000.

Expected behavior
The example should work out of the box.

  let callbackPromise = promise.then(
     context.contractName,
     "_onItemAdded",
     requestArgs.encode().serialize(),
     100000
  );

📝 Location
https://docs.nearprotocol.com/docs/runtime-ts/classes/_contract_.contractpromise.html

BTW, the link from the navigation menu is broken (does not include .html)!

Currently documentation for collections is auto-generated and hard to read. We need better documentation and more examples explaining how they work.

https://docs.nearprotocol.com/docs/validator/staking

Start a local node with myaccount account as a validator.
Issue a transaction:

http post http://127.0.0.1:3030/ jsonrpc=2.0 method=query params:="[\"account/myaccount\",[]]" id="dontcare"

Observe error message:

HTTP/1.1 200 OK
content-length: 156
content-type: application/json
date: Fri, 26 Jul 2019 18:39:40 GMT

{
    "error": {
        "code": -32602,
        "data": "Failed parsing args: invalid type: sequence, expected a string",
        "message": "Invalid params"
    },
    "id": "dontcare",
    "jsonrpc": "2.0"
}

Is your feature request related to a problem? Please describe.
The most important and valuable document in all the docs is named "File Structure"

Describe the solution you'd like
It should be named Overview or something

Is your feature request related to a problem? Please describe.
There is a need for a simpler example of chained contract calls. The current one is enormous.

Describe the solution you'd like
Here is an example I came up with: https://gist.github.com/frol/bb8185948388335df27980db64eec301

NOTE: PROMISE_RESULT_* should be better integrated into near-runtime-ts.

Describe the bug
On pages under https://docs.nearprotocol.com/api-documentation/runtime-ts links are going to github, and some of the pages on github are missing.
For example on https://docs.nearprotocol.com/api-documentation/runtime-ts/modules/utility-module-near click random32

Describe how to use it + example snippets.

Is your feature request related to a problem? Please describe.
the current structure (the outline / table of contents) of our documentation isn't intuitive and doesn't seem to follow the typical flow

Describe the solution you'd like
by comparing several options we can pick / generate a better structure and reorganize the docs to match it

Additional context
here are a few examples of well structured docs

• https://codaprotocol.com/docs/
• https://wiki.polkadot.network/docs/en/
• https://docs.solana.com/book/

thoughts? @AnaisUrlichs and @potatodepaulo

I tried to run npm test in a freshly build new project (running locally), the test fails and throws the following error:

[unknown contract]: Runtime error: Account alice.near tries to create new account with 1000000000000, but only has 0

Describe the bug
Random API should be hidden from the docs since the implementation in near-runtime-ts is not available now.

Expected behavior
Should either work as described or removed from the docs.

📝 Location
https://docs.nearprotocol.com/docs/development/writing-smart-contracts#random-numbers

Generate API docs from NEARlib, PyNEAR and NEARCore and put them here.

Running a node docs has 'git checkout staging' as one of the instructions. Let's come up with a proper release process which includes branch names with helpful information e.g. version info.

Is your feature request related to a problem? Please describe.

Many people are asking the same questions on Discord over and over. This is a waste of valuable time, especially when we've answered this Q somewhere else.

Describe the solution you'd like

1. A FAQ section that clearly answers the most basic questions
   a) We need to compile these.
2. Links to S.O. in the docs and FAQ

To reproduce, open: https://docs.nearprotocol.com/quick_start/expert
Observe that web page opens, and there is a section:
"Expert: Run Alphanet deploy on GCP"
Then page reloads by itself, and the section changes to:
"Expert: Connect to NEAR Testnet"

Describe the bug

I clicked Developers to get here:
https://nearprotocol.com/developers/

Then clicked "Explore":
https://studio.nearprotocol.com/debugger

Expected behavior
Not broken link.

Screenshots

Here's a good tool to automate testing for broken links:

npm install -g linkinator
npx linkinator -r https://nearprotocol.com/

Or output links to CSV:
npx linkinator -r -f csv https://nearprotocol.com/

📝 Location
https://nearprotocol.com/developers/

https://docs.nearprotocol.com/running-a-node

This should go in this section You will also need Near Shell, which which will require nodejs/npm

Is your feature request related to a problem? Please describe.
The problem is that this document is out of date: https://docs.nearprotocol.com/docs/local-setup/local-dev-node

Describe the solution you'd like
This page should be titled "Local Development on Local Network" and needs a small re-write.

It should show peeps how to spin up a "local network", not a "local node". The difference in practice is simple as running "start_localnet" with an "acccounts.csv" inside of the ~/.near folder. The technical difference is that the "start_testnet" syncs with our public testnet and the former creates an entirely separate network. The separate network is more stable since it doesn't sync our breaking changes

Additional context
Important Definitions

• Public Testnet - The network that we maintain and run nodes for of the most up to date master branch of nearcore
• Local Testnet - The same thing as running a "Local Node"
• Local Node - Running the nearcore code on your system in a way that it syncs to the Public Testnet
• Local Network - Any branch pulled from nearcore (including staging, commit hash, or a feature branch) that starts without synching to the "Public Testnet." Two benefits are: 1) More stability because you can freeze a version 2) You can define genesis yourself for all sorts of shenanigans

Documenting RPC (probably should finalize it first based on feedback from libs)

Describe in high level NEARlib.js + examples how to use it.

Describe the bug
On Writing Contracts: State section, there is a link for "the storage docs", but the link is routed to Writing Contracts page, the same page I was on before navigating away, but from top.

Expected behavior
I expected to go to a doc page about Storages.

Screenshots

📝 Location
Writing Contracts: State

Add a basic layout of documentation for protocol details.

Is your feature request related to a problem? Please describe.
sometimes there are important statements we want to call out inline in our docs (ie. some aspect of our API is under heavy development or something is a recent addition to the API)

Describe the solution you'd like
a highlighted blockquote is always a good idea. it doesn't seem like Docusaurus supports this natively like MkDocs does with admonitions but we should be able to replicate this functionality with some custom markdown parsing if a simpler solution isn't found

Additional context
see this MkDocs explainer for more context about the desired feature

thoughts? @AnaisUrlichs and @potatodepaulo

Is your feature request related to a problem? Please describe.
I don't know how accounts work!

Describe the solution you'd like
I want a page where I can read about em

https://docs.nearprotocol.com/docs/tutorials/zero-to-hero#step-0-get-familiar-with-the-near-ide-the-basic-layout-of-a-near-project

e.g. it mentions assembly/near.ts, which isn't a thing for a while. Maybe something else is out of date, need to be tested.

Running a node doc page:
core dump instructions don't work on mac
(To enable coredump for docker, do echo '/tmp/core.%t.%e.%p' | sudo tee /proc/sys/kernel/core_pattern to modify system coredump location to /tmp.)

Write quick_start doc (possibly with embedded NEAR Studio) for people first interaction.