From 972129a6f95a04ac6dada732509e7fee8045c1ce Mon Sep 17 00:00:00 2001 From: "Elliot J. Voris" Date: Wed, 17 Nov 2021 18:13:30 -0600 Subject: [PATCH 1/5] Beginning to copy API docs from existing documentation Signed-off-by: Elliot J. Voris --- developers/authentication.md | 41 ++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 developers/authentication.md diff --git a/developers/authentication.md b/developers/authentication.md new file mode 100644 index 0000000..55f2534 --- /dev/null +++ b/developers/authentication.md @@ -0,0 +1,41 @@ +# Authentication + +## XdrToken + +The Turret XDR Token is a signed transaction envelope XDR that is signed by the +account seeking authentication's public key. The signed XDR, or XDR Token, is +provided as a Authorization Bearer token to the Turret. + +### XdrToken Structure + +The Xdr Token Transaction is a Stellar transaction that authenticates public key +ownership against a Turret. It MUST have a Sequence Number of 0 to ensure the +transaction is not malicious and is unable to be submitted. The following +information will be pulled from the Xdr Token Transaction: + +* Sequence Number + * Verify the sequence number is 0 - if not, reject the token. +* Source account + * The account that is paying fees in to the turret through the claimable balance +* Timebounds + * The max time of the timebounds will be the absolute UNIX expiration time of the token. +* Operations + * ClaimClaimableBalance + * The Balance Id of the Claimable Fee Balance (of the structure show below) of the fee payment to the turret. + * ManageData + * Used to pass token parameters into the turret + * Valid parameters + * Entry name = "txFunction" (If no txFunctions parameters are passed in, the turret does not limit any txFunctions to run) + * Value = the hash of the txFunction that the user is allowing the turret to run +* Signature + * The Fee Transaction is signed by the account that is the source account of the transaction + +### Example + +This [RunKit Example](https://runkit.com/mootz12/60d1f69582e0580013bb591e) +showcases how to generate a XDR Token. It creates, signs, and generates a valid +Authorization token. + +| **Security Scheme Type** | HTTP | +| **HTTP Authorization Scheme** | bearer | +| **Bearer Format** | "XDR" | From 1756bbdc64791729d9e076856c1737cb6e11e219 Mon Sep 17 00:00:00 2001 From: "Elliot J. Voris" Date: Wed, 17 Nov 2021 19:50:37 -0600 Subject: [PATCH 2/5] Starting on the `/` endpoint. Trying to check the markdown syntax Signed-off-by: Elliot J. Voris --- developers/turret.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 developers/turret.md diff --git a/developers/turret.md b/developers/turret.md new file mode 100644 index 0000000..a49d0c1 --- /dev/null +++ b/developers/turret.md @@ -0,0 +1,22 @@ +# Turret + +View information about a Turret + +## Get Turret Information + +Returns basic information about the turret + +### Responses +
**200** Success + +RESPONSE SCHEMA: application/json + +`turret` | `string` The public key of the turret owner +`network` | `string` The Stellar Network the turret is on. `TESTNET` or `PUBLIC` +`horizon` | `string` The Horizon API the turret uses +`version` | `string` The repository version and last commit +`fee` | `object (schemas)` +`divisor` | `object (schemas)` + + +
From 685b4e6bcad1cdc5e2f03db2045144ece43b59a4 Mon Sep 17 00:00:00 2001 From: "Elliot J. Voris" Date: Wed, 17 Nov 2021 19:59:37 -0600 Subject: [PATCH 3/5] Figuring out the GFM table syntax. Don't know if that's ultimately the best way to go, though... Signed-off-by: Elliot J. Voris --- developers/authentication.md | 2 ++ developers/turret.md | 18 +++++++++--------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/developers/authentication.md b/developers/authentication.md index 55f2534..e242ba7 100644 --- a/developers/authentication.md +++ b/developers/authentication.md @@ -36,6 +36,8 @@ This [RunKit Example](https://runkit.com/mootz12/60d1f69582e0580013bb591e) showcases how to generate a XDR Token. It creates, signs, and generates a valid Authorization token. +| | | +| --- | --- | | **Security Scheme Type** | HTTP | | **HTTP Authorization Scheme** | bearer | | **Bearer Format** | "XDR" | diff --git a/developers/turret.md b/developers/turret.md index a49d0c1..b2486da 100644 --- a/developers/turret.md +++ b/developers/turret.md @@ -7,16 +7,16 @@ View information about a Turret Returns basic information about the turret ### Responses -
**200** Success -RESPONSE SCHEMA: application/json - -`turret` | `string` The public key of the turret owner -`network` | `string` The Stellar Network the turret is on. `TESTNET` or `PUBLIC` -`horizon` | `string` The Horizon API the turret uses -`version` | `string` The repository version and last commit -`fee` | `object (schemas)` -`divisor` | `object (schemas)` +
200 Success +| key | value | +| --- | --- | +| `turret` | `string` The public key of the turret owner | +| `network` | `string` The Stellar Network the turret is on. `TESTNET` or `PUBLIC` | +| `horizon` | `string` The Horizon API the turret uses | +| `version` | `string` The repository version and last commit | +| `fee` | `object (schemas)` | +| `divisor` | `object (schemas)` |
From 6a852f6f19611f2ff0ba7e19c0d1c6d505a81642 Mon Sep 17 00:00:00 2001 From: "Elliot J. Voris" Date: Wed, 17 Nov 2021 20:12:50 -0600 Subject: [PATCH 4/5] Fleshing out the first two api endpoints Signed-off-by: Elliot J. Voris --- developers/turret.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/developers/turret.md b/developers/turret.md index b2486da..677a89d 100644 --- a/developers/turret.md +++ b/developers/turret.md @@ -6,6 +6,12 @@ View information about a Turret Returns basic information about the turret +### Request + +``` +GET / +``` + ### Responses
200 Success @@ -20,3 +26,41 @@ Returns basic information about the turret | `divisor` | `object (schemas)` |
+ +### Response Sample + +```json +{ + "turret": "GB4OYM7TQTJSROWXHOJLKAX2IJ2QN4I6S6GCJH4MGWVTAO5Q5DPNADXX", + "network": "TESTNET", + "horizon": "https://horizon-testnet.stellar.org", + "version": "v0.0.0-ff9e9750369cc8aed29af9f08ae34634594cbe41", + "fee": { + "min": 1, + "max": 10, + "days": 180 + }, + "divisor": { + "upload": 1000, + "run": 100000 + } +} +``` + +## Get the Turret's TOML file + +Returns the `stellar.toml` file associated with the turret + +### Request + +``` +GET /.well-known/stellar.toml +``` + +### Responses + +
200 + +A [Stellar TOML](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md) file + +
From b763d6612b96b131eff54abb948a6ad7511c98db Mon Sep 17 00:00:00 2001 From: "Elliot J. Voris" Date: Wed, 17 Nov 2021 20:32:55 -0600 Subject: [PATCH 5/5] Starting on the `tx-functions` api endpoints Signed-off-by: Elliot J. Voris --- developers/tx-functions.md | 83 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 developers/tx-functions.md diff --git a/developers/tx-functions.md b/developers/tx-functions.md new file mode 100644 index 0000000..cad6e99 --- /dev/null +++ b/developers/tx-functions.md @@ -0,0 +1,83 @@ +# txFunctions + +Manage and run txFunctions on the Turret. A txFuntion is a JavaScript file that +outputs a valid Transaction Envelope XDR. The txFunction will be executed in a +node environment with the following default node_module packages: + +* bignumber.js +* node-fetch +* stellar-sdk + +## Upload a txFunction + +Uploads a txFunction to the turret + +### Request + +``` +POST /tx-functions +``` + +REQUEST BODY SCHEMA: multipart/form-data + +| key | value | +| --- | --- | +| `txFunction` | `string` The source code to be uploaded | +| `txFunctionFields` | `string` A Base64 encoded array of json object of the input fields for the contract | +| `txFunctionFee` | `string` A signed, non-submitted transaction envelope XDR for a fee payment to the `TURRET_ADDRESS` that is greater than or equal to the byte length of the contract divided by the `UPLOAD_DIVISOR` set by the turret | + +### Request Sample + +```json +{ + "txFunction": "/some/path/txFunction.js", + "txFunctionFields": "W3sibmFtZSI6ImRlc3RpbmF0aW9uIiwidHlwZSI6InN0cmluZyIsImRlc2NyaXB0aW9uIjoiU3RlbGxhciBwdWJsaWMga2V5IHlvdSdkIGxpa2UgdG8gcGF5IiwicnVsZSI6Ik11c3QgYmUgYSB2YWxpZCBhbmQgZnVuZGVkIFN0ZWxsYXIgcHVibGljIGtleSJ9XQ", + "txFunctionFee": "AAAAAgAAAABTqjFHz0quLSka8SOrkw7R07aqDNUHAe+Qm5PX0jMiGwAAAGQAHfBZAAAADgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAQAAAAB47DPzhNMoutc7krUC+kJ1BvEel4wkn4w1qzA7sOje0AAAAAAAAAAAAJiWgAAAAAAAAAAB0jMiGwAAAEAZjWTnxXY2lxVt0VSos6/Uvpoo3pXo6l+0Xk/P+sE5KDPwhAYkVQyXEBb8prEYprzp3aSlLF4TKcw3m/RM5IMK" +} +``` + +### Responses + +
200 txFunction uploaded + +RESPONSE SCHEMA: application/json + +| key | value | +| --- | --- | +| `hash` | `string` The SHA256 hash value of the contract | +| `signer` | `string` The public key of the signer the turret will use to sign the uploaded contract | + +
+ +
402 payment required + +RESPONSE SCHEMA: application/json + +| key | value | +| --- | --- | +| `message` | `string` Description of what failed | +| `turret` | `string` The public key of the turret requiring payment | +| `cost` | `string` The cost of the operation in lumens | + +
+ +### Response Samples + +#### 200 txFunction Uploaded + +``` +{ + "hash": "78565516a844fd4dfc5a7fc7da822028b04ee0aeaf981a4a914d4510906a7a32", + "signer": "GB6VNMGXKHS4UTIXW7U23ZQFWD7UJIWCJNQZR7ISNKBTYNULCFQKKPIK" +} +``` + +#### 402 payment required + +``` +{ + "message": "Failed to process txFunctionFee", + "turret": "GB4OYM7TQTJSROWXHOJLKAX2IJ2QN4I6S6GCJH4MGWVTAO5Q5DPNADXX", + "cost": "0.2740000" +} +```