Skip to content
This repository was archived by the owner on Jun 22, 2021. It is now read-only.

WIP: Rewriting the get started flow #136

Closed
wants to merge 17 commits into from
+501 −262
Closed

WIP: Rewriting the get started flow #136

Changes from 1 commit
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
25a5831
First draft of step 2 - create an account.
Mr0grog Jun 1, 2016
1661784
Switch to explicit imports in Java examples
Mr0grog Jun 2, 2016
19d5500
Add link to coinmarketcap's list of exchanges for places to buy lumens.
Mr0grog Jun 2, 2016
b0fb037
Remove footnote about changing public keys since it was totally wrong!
Mr0grog Jun 3, 2016
7f0676d
create-account.md: go examples
bartekn Jun 3, 2016
74e8823
Made edits and added TODOs
Jun 18, 2016
a2592a1
fix typos
Jun 20, 2016
5cf9d6d
Add first draft of get started step 3.
Mr0grog Jun 22, 2016
445b7ac
Fix footnote and code sample syntax.
Mr0grog Jun 24, 2016
179d956
Change <example> to <code-example> to be a proper custom element, fix…
Mr0grog Jun 25, 2016
58b3013
Remove old documents from get started flow.
Mr0grog Jun 25, 2016
e5a5038
Clean up discussion about getting an account ID from a KeyPair instea…
Mr0grog Jun 28, 2016
4a2ccdf
Rework private key/secret seed language in get started flow.
Mr0grog Jun 28, 2016
20480cf
Remove title headings from get started docs.
Mr0grog Jun 29, 2016
50306c7
Make titles active, add back/next buttons everywhere.
Mr0grog Jun 29, 2016
5be16d9
Remove bash examples from get started
Mr0grog Jun 29, 2016
2e1d6ec
Fix typo in footer
Mr0grog Jun 29, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions learn/get-started/create-account.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Create an Account

The first thing you’ll need to do anything on Stellar is an account. Accounts hold all your money inside Stellar and allow you to send and receive payments—in fact, pretty much everything in Stellar is in some way tied to an account.

Every Stellar account has a pair of public and private keys. Stellar uses public key cryptography to ensure that every transaction is secure. The private key is a secret piece of information that proves you own the account. You should never share your private key with anyone. It’s kind of like the combination to a lock—anyone who knows the combination can open the lock. In the same way, anyone who knows your account’s secret key can control your account. The public key how other people identify your account and verify that you authorized a transaction.
Every Stellar account has a pair of public and private keys. Stellar uses public key cryptography to ensure that every transaction is secure. The private key is a secret piece of information that proves you own the account. You should never share your private key with anyone. It’s kind of like the combination to a lock—anyone who knows the combination can open the lock. In the same way, anyone who knows your account’s secret key can control your account. The public key is how other people identify your account and verify that you authorized a transaction.
[TODO: decide on whether we're using public/private or public/secret for keypairs. This doc currently uses both private and secret.]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The correct terminology used by Stellar everrywhere is:

Public Key and Secret Key.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So… this came about because the JS and Java SDKs both don't really expose private keys, only secret seeds:
https://stellar.github.io/js-stellar-sdk/Keypair.html
https://stellar.github.io/java-stellar-sdk/

Some docs talk exclusively about secret seeds (e.g. https://www.stellar.org/developers/learn/get-started/get-started.html) and some talk about both without really clarifying the difference (e.g. https://www.stellar.org/developers/learn/integration-guides/building-blocks/account-management.html). The quick start widget calls the secret seed a private key, which might set someone up for confusion later.

I don't think I've seen a doc that uses "secret key," but maybe I missed it?

Anyway, I think it's important that the secret seed is a different thing from the private key—this actually caused me some personal confusion for a couple days and several wrong steps when trying to use the API and write the original docs. I'm not sure we can just say "secret key" without talking about "secret seed," since seed is the terminology used in most of the SDK APIs.

It might be that I just need to stop and explain both here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's because seed is a deprecated term and we haven't taken the time to fix those.

We aspire to use "public key" and "secret key" (we had a big conversation about this a while back).

In practice though, we haven't updated a lot of our code and some stuff even refers to "address".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better to move forward with the right terms than try to accommodate for the old terms that we are trying to abandon.


Because the private key must be kept secret, the first step in creating an account is creating your own keys (when you create the account, you’ll send only the public key to a Stellar server). You can do so with the following command:
Expand Down Expand Up @@ -66,7 +66,7 @@ func main() {
</example>

[TODO: should this only show if viewing the SDK examples?]
You might notice that, in the SDK, you ask for the *account ID* instead of the public key. That’s because an account’s ID *is* its public key.
You might notice that, in the SDK, you are asked for the *account ID* instead of the public key. That’s because an account’s ID *is* its public key.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm, I think this definitely should have been “ask” instead of “are asked”—at least, I was trying to refer to the fact that you call pair.accountId() or pair.getAccountId() rather than what one might expect from a key pair, e.g. pair.publicKey().

Would if be clearer if it was:

You might notice that, in the SDK, you call pair.accountId() instead of something like pair.publicKey(). That’s because an account’s ID is its public key.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, yeah that works also

[TODO: Explain why this is the case—the distinction here just sounds like a mistake.]

Now that you have a pair of keys, you can make an account. In order to prevent people from making a huge number of unnecessary accounts, each account must have a minimum balance of 20 lumens (lumens are the built-in currency of the Stellar network).[1] Since you don’t yet have any lumens, though, you can’t pay for an account! In the real world, you’ll usually pay an exchange that sells lumens in order to create a new account.[2] On Stellar’s test network, however, you can ask Friendbot, our friendly robot with a very fat wallet, to create an account for you.
Expand Down