WIP: "Become an Anchor" guide redux #160

Mr0grog · 2016-08-27T01:13:40Z

This isn’t even sort of done yet, but I want to get it in public so @jedmccaleb / @bartekn / @nullstyle can take a basic look at whether I'm doing things right with the various prebuilt servers and @mozzadrella can start to gut-check me on direction.

Unlike the old guide, this:

Covers topics of federation and compliance
Uses the pre-built federation server, compliance server, and bridge server
Has diagrams :)

Covers topics of federation and compliance, uses the pre-built federation server, compliance server, and bridge server to do so.

jedmccaleb · 2016-08-29T21:52:55Z

For these diagrams, can we change it to "Your FI" instead of "Your Bank" or "Your Financial Institution" or maybe just "Your Infrastructure"

Mr0grog · 2016-08-31T17:58:51Z

@jedmccaleb, yeah, definitely. The diagrams may need some general revision anyway; I was trying to get a) a condensed version of the bigger diagram so you could actually see it all at once and b) show how it works with/without various addons like federation and compliance.

Probably not "FI" (I think that abbreviation is problematic; it seemed to be when I asked people about the old doc, which also used it). Will have to think about whether "financial institution" or "infrastructure" is better.

Mr0grog · 2016-08-31T18:20:30Z

Also, organizationally: do we want/need a better structure for where images go, filesystem-wise?

jedmccaleb · 2016-08-31T18:47:56Z

you mean like docs/images or something?
I think I like "infrastructure" best. If they are considering doing this then they know they are a financial institution.

bartekn · 2016-08-31T19:08:37Z

When it comes to diagrams I'd add a background layer for Your/Other FI. Right now, it's not clear where each part of the system belongs.

Mr0grog · 2016-08-31T19:22:43Z

you mean like docs/images or something?

Yeah. Is it ok that the images are just free-floating in the guides directory right now, or should they be grouped into a directory? (probably with the same name as the guide)

Relatedly, I can put the sketch files in dropbox, but should they also live in the repo? Seems like that would make sense.

I think I like "infrastructure" best.

What about “your systems?” (“infrastructure” is good, too, just slightly more jargon-y.)

When it comes to diagrams I'd add a background layer for Your/Other FI.

Yeah, that's probably a good idea.

jedmccaleb · 2016-08-31T20:09:20Z

Seems better to have the images in a separate dir but I don't feel strongly about it. Also don't feel strongly about sketch in the repo or not. Probably better to have it be here.
"your systems" is ok seems less clear than "infrastructure" though.

Get rid of nice indentations (bad for copy/paste), add `source` (it's required for now), add `apiKey`). May want to consider removing all the API key bits since not really recommended anyway.

This completes a first full draft of the new anchor guide. Lots of clean up (and splitting up) needed.

Mr0grog · 2016-09-15T02:49:00Z

Ok, basic first draft of all the parts, fully working. Needs cleanup:

This is way too long. Needs to be split up into
1. Architecture/overview
2. Bridge
3. Federation
4. Compliance
5. Next steps.
Intro should be beefed up with a full diagram and overview of how the parts fit together. I originally wanted to introduce things step-by-step, but in hindsight, I think I need to give a better big picture overview first, especially now that it has gotten so long.
Diagram cleanup (maybe w/ help from Romina)
Need some explanation around domains, SSL, and how to get it running locally-ish. @nullstyle do you think your non-SSL mode support will land soon-ish? Should I just write the guide pretending they can do that in a test situation?
Need to clean up language/details around database stuff. In the current release, only MySQL (or MariaDB) works, but I know you’re fixing Postgres, @nullstyle. Should I assume that will ship before this guide and just write it as if that works?
Need Java examples (and some JS ones are missing, too)
Integration testing:
- I had been trying to avoid telling people to just send a payment to themselves (e.g. from amy*your-org.com to bob*your-org.com), but I guess that actually works and does exercise the full flow. Should I just do that? Otherwise…
- It might be useful or helpful to ship a dummy server that does federation & compliance for any address, so you can send a payment through your bridge + compliance setup to it. Otherwise, it seems a little rough to say “just duplicate your whole infrastructure so you have something to transact against” :\
- UPDATE: I went with suggesting that people send a payment to themselves so this didn’t seem obscenely complicated to a reader. (4da981b)
Next steps: what else should be there besides the security doc and running core? Channels? /@jedmccaleb @bartekn @nullstyle

jedmccaleb · 2016-09-15T18:43:29Z

Looks great. are things like "[^friendly_names]" placeholders?
nm I see they are foot notes. Do these work in the dev portal?

Mr0grog · 2016-09-15T19:27:49Z

guides/anchor.md

@@ -354,7 +354,7 @@ You should get a response like:

 ## Compliance

-The final piece of the puzzle is handling regulatory compliance, like <abbr title="Know Your Customer">KYC</abbr>. The [Stellar compliance protocol](compliance-protocol.md) is a standard way to exchange compliance information and pre-approve a transaction with another financial institution.
+The final piece of the puzzle is handling regulatory compliance, like <abbr title="Anti-Money Laundering">AML</abbr>. The [Stellar compliance protocol](compliance-protocol.md) is a standard way to exchange compliance information and pre-approve a transaction with another financial institution.


@jedmccaleb what exactly is the right context for AML vs. KYC?

KYC is a more thorough process that a bank will go through when someone is creating a bank account with them. When they are sending a payment they just need enough info on the recipient to do the AML check to make sure the recipient isn't on some sanction list. Since people already have accounts in these scenarios, we are just dealing with AML.

Ah, gotcha. I had thought KYC referred to exchanging the information as well, not just initially gathering it. Will keep that in mind!

Mr0grog · 2016-09-15T19:31:54Z

are things like "[^friendly_names]" placeholders?

Those are named footnote links. So you can footnotes like [^1] or like [^topic_here]. I like the latter more since you don’t have to re-number everything if you insert a new one higher up in the document (they also provide a little clue about the subject of the note).

Mr0grog · 2016-09-15T22:28:17Z

The above splits the anchor guide into a 5 page group, kind of like the get started guide. I also added support in the build scripts for metadata named section in the frontmatter as seen here: f2cc40d#diff-d90ab5683bfaab7c60803d1fd7dcd389R3 that automatically builds the previous/next links like the ones on the get started guide.

Not sure if that’s desirable (it kind of obscures the links when reading straight markdown or in github). Any thoughts on it?

@bartekn

@bartekn if you have a nicer way to write out the Java stuff, that'd be awesome. I'm not really sure what helper libraries are most used for HTTP stuff these days.

bartekn · 2016-09-16T13:45:36Z

Rewrote Java examples as requested in 0689e88.

- Hooks -> Callbacks - Stop discussing error callback since it never gets used - Don't discuss api_key since we've decided its use shouldn't be encouraged - Minor formatting and language tweaks

This helps clarify to the reader exactly which file is being shown, since they can see the name in the heading of the code snippet.

This also makes some technical corrections to the diagrams (and adds one for federation). Diagrams still need final cleanup from Romina.

Mr0grog · 2016-09-30T00:18:36Z

Ok, I think this is mostly done save for:

A last pass of work on improving the diagrams
- Have talked with Romina about getting some input on improving the appearance and clarifying the arrangement and ordering of things.
- Make sure they are appropriately sized, compressed, maybe multiple versions (SVG and PNG)
~~Need sidebar support in developers repo~~
~~Need next/back links (going to see about autogenerating these in developers repo)~~

But otherwise, I think this is pretty much there, excepting any further feedback anyone’s got. Please let me and Romina both know if you think there are technical inaccuracies in the diagrams, too. /cc @jedmccaleb @nullstyle @bartekn

Mr0grog · 2016-09-30T00:21:19Z

~~Side note about autogenerating back/next links: just realized this might not actually be desirable given that we want these to be reasonably browsable on Github. Thoughts?~~ (Update: have added the links to the docs instead of autogenerating)

Also! This references the security guide (#149) in the next steps section. That PR isn’t ready to land yet, so we either need to finish it (it’s waiting for feedback from other people) or pull it from next steps here. (Update: security guide has since landed.)

Headings that used to be H3 should have become H2 when we broke this guide into 5 pages (what used to be level 2 headings are now level 1 page headings).

Don't merge into master until stellar-deprecated/docs#160 is shipping.

bartekn

Looks great! 👍

bartekn · 2016-10-03T15:42:42Z

guides/anchor/4-compliance-server.md

+`AUTH_SERVER` is the address for the *external* port of your compliance server. Like your federation server, this can be any URL you like, but **it must support HTTPS and use a valid SSL certificate.**[^ssl]
+
+`SIGNING_KEY` is the public key that matches the secret seed specified for `signing_seed` in your compliance server’s configuration. Other organizations will use it to safely encrypt sensitive compliance data (like customer names, birthdates, and addresses) so that only you can read it and to verify that messages were actually sent by you.
+


SIGNING_KEY is used to sign Auth Request (sig param) so receiving organization can check whether it was really sent by the sender organization.
There will be also ENCRYPTION_KEY in stellar.toml file but we haven't decided on the format yet.

@bartekn Ah! I admit to not having inspected data on the wire to see if this was additionally used for encryption. D’oh! How about:

SIGNING_KEY is the public key that matches the secret seed specified for signing_seed in your compliance server’s configuration. Other organizations will use it to verify that messages were actually sent by you.

Sounds good!

This ensures we have working back and next links when browsing the docs on Github (I had previously been planning on autogenerating these links when the developers site builds).

Mr0grog · 2016-10-06T21:31:32Z

Added the back/next links to the docs. Needs stellar-deprecated/developers#84 for nicer styling.

That just leaves improved diagrams from Romina, I think.

jedmccaleb · 2016-10-07T23:34:40Z

Nice work Rob!

First third of new "become an anchor" doc.

42a3824

Covers topics of federation and compliance, uses the pre-built federation server, compliance server, and bridge server to do so.

Mr0grog added 2 commits August 31, 2016 12:37

Move running core to next steps [anchor guide]

9c6c08b

Add comments to config file example [anchor guide]

de0352b

Mr0grog added 3 commits September 1, 2016 11:47

Add migrate/start bridge instrux [anchor guide]

790aba6

Fix up POST /payment instructions [anchor]

e3fd30b

Get rid of nice indentations (bad for copy/paste), add `source` (it's required for now), add `apiKey`). May want to consider removing all the API key bits since not really recommended anyway.

WIP adding federation instructions [anchor guide]

c2fc2d9

Mr0grog force-pushed the new-anchor-guide branch from 54b160d to c2fc2d9 Compare September 9, 2016 18:48

Mr0grog added 3 commits September 9, 2016 12:29

Fix example domains to all be the same [anchor]

7b46f4a

Finish federation section draft [anchor guide]

ea55eec

Add compliance server section [anchor guide]

0b9ee27

This completes a first full draft of the new anchor guide. Lots of clean up (and splitting up) needed.

Update anchor.md

cdf7077

Mr0grog commented Sep 15, 2016

View reviewed changes

Split up anchor guide into 5 pages

f2cc40d

Mr0grog and others added 3 commits September 15, 2016 16:55

Send a payment to yourself to test compliance

4da981b

Add JS & Java sending payments examples [anchor]

0689e88

@bartekn if you have a nicer way to write out the Java stuff, that'd be awesome. I'm not really sure what helper libraries are most used for HTTP stuff these days.

Use org.apache.http in Java examples

7524752

Mr0grog added 2 commits September 16, 2016 16:49

Java examples for bridge server section [anchor]

2ad32bf

JS and Java examples for federation [anchor]

6333b8f

Mr0grog added 11 commits September 16, 2016 18:05

Complete compliance code examples [anchor]

2d774c5

Expand anchor intro to describe overall flow

caaf316

Cleanup bridge server section of anchor guide

d979dae

- Hooks -> Callbacks - Stop discussing error callback since it never gets used - Don't discuss api_key since we've decided its use shouldn't be encouraged - Minor formatting and language tweaks

Use <code-example> for files [anchor]

e1a6244

This helps clarify to the reader exactly which file is being shown, since they can see the name in the heading of the code snippet.

Clean up wording around SSL and databases [anchor]

d6148bd

Detail needs_auth flag, fetch_info fields [anchor]

f924a58

Clarify that ask_user can also return 203 [anchor]

7b0fdb3

Language cleanup, notes about extra_memo [anchor]

382032b

Complete "next steps" section [anchor]

62d456c

Add footnotes about getting SSL certs [anchor]

f72420c

Add light explanation for diagrams [anchor]

570d934

This also makes some technical corrections to the diagrams (and adds one for federation). Diagrams still need final cleanup from Romina.

Mr0grog mentioned this pull request Sep 30, 2016

The Anchor guide should be revamped #151

Closed

Fix heading levels [anchor]

e9f806d

Headings that used to be H3 should have become H2 when we broke this guide into 5 pages (what used to be level 2 headings are now level 1 page headings).

Mr0grog added a commit to stellar-deprecated/developers that referenced this pull request Sep 30, 2016

Sidebar updates for new anchor guide

723ce10

Don't merge into master until stellar-deprecated/docs#160 is shipping.

Mr0grog mentioned this pull request Sep 30, 2016

WIP: Sidebar updates for new anchor guide stellar-deprecated/developers#82

Merged

Re-do account keys as <dl> [anchor]

79fad30

bartekn approved these changes Oct 3, 2016

View reviewed changes

Mr0grog added 2 commits October 5, 2016 14:09

SIGNING_KEY is not used for encryption [anchor]

3091230

Merge branch 'master' into new-anchor-guide

ed377b4

Mr0grog mentioned this pull request Oct 6, 2016

Sequential navigation support stellar-deprecated/developers#84

Merged

Add back/next links to document source [anchor]

5e3d673

This ensures we have working back and next links when browsing the docs on Github (I had previously been planning on autogenerating these links when the developers site builds).

Fix anchor guide link from get started [anchor]

3e85748

jedmccaleb merged commit 8e27aae into master Oct 7, 2016

jedmccaleb deleted the new-anchor-guide branch October 6, 2017 16:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: "Become an Anchor" guide redux #160

WIP: "Become an Anchor" guide redux #160

Mr0grog commented Aug 27, 2016

jedmccaleb commented Aug 29, 2016

Mr0grog commented Aug 31, 2016

Mr0grog commented Aug 31, 2016

jedmccaleb commented Aug 31, 2016

bartekn commented Aug 31, 2016

Mr0grog commented Aug 31, 2016

jedmccaleb commented Aug 31, 2016

Mr0grog commented Sep 15, 2016 •

edited

Loading

jedmccaleb commented Sep 15, 2016 •

edited

Loading

Mr0grog Sep 15, 2016

jedmccaleb Sep 15, 2016

Mr0grog Sep 15, 2016

Mr0grog commented Sep 15, 2016

Mr0grog commented Sep 15, 2016

bartekn commented Sep 16, 2016 •

edited

Loading

Mr0grog commented Sep 30, 2016 •

edited

Loading

Mr0grog commented Sep 30, 2016 •

edited

Loading

bartekn left a comment

bartekn Oct 3, 2016

Mr0grog Oct 5, 2016

bartekn Oct 5, 2016

Mr0grog Oct 5, 2016

Mr0grog commented Oct 6, 2016

jedmccaleb commented Oct 7, 2016

		`AUTH_SERVER` is the address for the external port of your compliance server. Like your federation server, this can be any URL you like, but it must support HTTPS and use a valid SSL certificate.[^ssl]

		`SIGNING_KEY` is the public key that matches the secret seed specified for `signing_seed` in your compliance server’s configuration. Other organizations will use it to safely encrypt sensitive compliance data (like customer names, birthdates, and addresses) so that only you can read it and to verify that messages were actually sent by you.

WIP: "Become an Anchor" guide redux #160

WIP: "Become an Anchor" guide redux #160

Conversation

Mr0grog commented Aug 27, 2016

jedmccaleb commented Aug 29, 2016

Mr0grog commented Aug 31, 2016

Mr0grog commented Aug 31, 2016

jedmccaleb commented Aug 31, 2016

bartekn commented Aug 31, 2016

Mr0grog commented Aug 31, 2016

jedmccaleb commented Aug 31, 2016

Mr0grog commented Sep 15, 2016 • edited Loading

jedmccaleb commented Sep 15, 2016 • edited Loading

Mr0grog Sep 15, 2016

Choose a reason for hiding this comment

jedmccaleb Sep 15, 2016

Choose a reason for hiding this comment

Mr0grog Sep 15, 2016

Choose a reason for hiding this comment

Mr0grog commented Sep 15, 2016

Mr0grog commented Sep 15, 2016

bartekn commented Sep 16, 2016 • edited Loading

Mr0grog commented Sep 30, 2016 • edited Loading

Mr0grog commented Sep 30, 2016 • edited Loading

bartekn left a comment

Choose a reason for hiding this comment

bartekn Oct 3, 2016

Choose a reason for hiding this comment

Mr0grog Oct 5, 2016

Choose a reason for hiding this comment

bartekn Oct 5, 2016

Choose a reason for hiding this comment

Mr0grog Oct 5, 2016

Choose a reason for hiding this comment

Mr0grog commented Oct 6, 2016

jedmccaleb commented Oct 7, 2016

Mr0grog commented Sep 15, 2016 •

edited

Loading

jedmccaleb commented Sep 15, 2016 •

edited

Loading

bartekn commented Sep 16, 2016 •

edited

Loading

Mr0grog commented Sep 30, 2016 •

edited

Loading

Mr0grog commented Sep 30, 2016 •

edited

Loading