From 508c54d3cd0d0ca45256177cdfea70f68ee28bda Mon Sep 17 00:00:00 2001
From: Aleksandr Bezobchuk <alex@tendermint.com>
Date: Wed, 1 Aug 2018 15:38:54 -0400
Subject: [PATCH] Update API section to be more spec-defined

---
 docs/ics/ics-xxx-signed-messages.md | 67 ++++++++++++++++++++---------
 1 file changed, 46 insertions(+), 21 deletions(-)

diff --git a/docs/ics/ics-xxx-signed-messages.md b/docs/ics/ics-xxx-signed-messages.md
index 89efeb74fb..7844cb615b 100644
--- a/docs/ics/ics-xxx-signed-messages.md
+++ b/docs/ics/ics-xxx-signed-messages.md
@@ -104,31 +104,56 @@ is as follows:
 
 ## API
 
-We now formalize a standard set of APIs that providers must implement:
+Application developers and designers should formalize a standard set of APIs that
+adhere to the following specification:
 
-```
-cosmosSignBytes(b : B, addr : B) {
-    return secp256k1Sign(sha256(encode(b)), addressPrivKey(addr))
-}
-```
+<hr>
 
-```
-cosmosSignBytesPass(b : B, pass : B) {
-    return secp256k1Sign(sha256(encode(b)), passPrivKey(addr))
-}
-```
+**cosmosSignBytes**
 
-```
-cosmosSignTyped(s : S, domainSeparator : B, addr : B) {
-     return secp256k1Sign(sha256(encode(s, domainSeparator)), addressPrivKey(addr))
-}
-```
+Params:
+* `data`: arbitrary byte length data to sign
+* `address`: 20 byte account address to sign data with
 
-```
-cosmosSignTypedPass(s : S, domainSeparator : B, pass : B) {
-     return secp256k1Sign(sha256(encode(s, domainSeparator)), passPrivKey(addr))
-}
-```
+Returns:
+* `signature`: the Cosmos signature derived using `S`
+
+<hr>
+
+**cosmosSignBytesPass**
+
+Params:
+* `data`: arbitrary byte length data to sign
+* `address`: 20 byte account address to sign data with
+* `password`: password of the account to sign data with
+
+Returns:
+* `signature`: the Cosmos signature derived using `S`
+
+<hr>
+
+**cosmosSignTyped**
+
+Params:
+* `domainSeparator`: the application domain separator to encode and sign
+* `typedData`: type data structure to encode and sign
+* `address`: 20 byte account address to sign data with
+
+Returns:
+* `signature`: the Cosmos signature derived using `S`
+
+<hr>
+
+**cosmosSignTypedPass**
+
+Params:
+* `domainSeparator`: the application domain separator to encode and sign
+* `typedData`: type data structure to encode and sign
+* `address`: 20 byte account address to sign data with
+* `password`: password of the account to sign data with
+
+Returns:
+* `signature`: the Cosmos signature derived using `S`
 
 ## References