diff --git a/developers/authentication.md b/developers/authentication.md new file mode 100644 index 0000000..e242ba7 --- /dev/null +++ b/developers/authentication.md @@ -0,0 +1,43 @@ +# 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" | diff --git a/developers/turret.md b/developers/turret.md new file mode 100644 index 0000000..677a89d --- /dev/null +++ b/developers/turret.md @@ -0,0 +1,66 @@ +# Turret + +View information about a Turret + +## Get Turret Information + +Returns basic information about the turret + +### Request + +``` +GET / +``` + +### Responses + +
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)` | + +
+ +### 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 + +
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" +} +```