mirror of https://github.com/Qortal/AT
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
168 lines
11 KiB
168 lines
11 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|
|
|
<html> |
|
<head> |
|
<title>CIYAM AT - Automated Transactions API Specification</title> |
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> |
|
<meta name="copyright" content="Copyright 2015 CIYAM Developers"/> |
|
|
|
<link rel="stylesheet" href="document.css" type="text/css"/> |
|
</head> |
|
|
|
<div id="content"> |
|
<div id="header"> |
|
<div id="appname"><a href="//ciyam.org/at">AT</a></div> |
|
<h3 class="right-top">Automated Transactions API Specification</h3> |
|
</div> |
|
|
|
<div id="main"> |
|
<div id="text"> |
|
<pre> |
|
Automated Transactions API Specification |
|
---------------------------------------- |
|
|
|
This specification details the AT API which is what allows an AT to communicate with its host's blockchain to |
|
find out details about blocks and transactions relevant to the AT and to issue its own transactions. In order |
|
to write "portable" ATs (i.e. those that can run analtered across different kinds of blockchain platforms) it |
|
is required that only the functions in the range 0x0100 to 0x04ff be used. Experimental functions can be used |
|
when prototyping (and have no formal definition here) and platform specific functions can be defined in order |
|
for ATs to be able to work more efficiently on a specific platform (and also have no formal definition here). |
|
|
|
As the AT machine uses a 64 bit design some very useful API commands such as cryptographic hash functions are |
|
not able to be perfomed directly with machine addresses. To work around this problem without resorting to the |
|
API having to perform memory range testing to use the AT's data, a set of "pseudo registers" must be provided |
|
by the AT API (every AT instance needs its own set) that are initially set to zero. |
|
|
|
There are four 64 bit registers called A1..4 and another four called B1..4 for this purpose (also referred to |
|
as two 256 bit registers called A and B). It is important to note that the A and B pseudo registers will need |
|
to be stored along with the other "state" variables such as the program counter and stack counters. |
|
|
|
Note that "timestamp" does not mean a real timestamp but instead is an artificial timestamp that includes two |
|
parts. The first part is a block height (32 bits) with the second part being the number of the transaction if |
|
applicable (also 32 bits and zero if not applicable). |
|
|
|
Note also that functions can be identified as being "blocking" functions. They will cause the AT to sleep for |
|
X blocks when it is known that the function will then be ready to return (with the function being executed by |
|
the AT twice with the first call needing to rewind the AT's program counter before putting it to sleep). |
|
|
|
In order to keep the functions organised in groups function number ranges are as follows: |
|
|
|
Number Range Range Usage |
|
-------------- ---------------------------------------------- |
|
0x0000..0x000f Reserved for internal AT testing purposes |
|
0x0010..0x00ff Experimental API function calls (for prototyping) |
|
0x0100..0x01ff Get/Set functions for "pseudo registers" |
|
0x0200..0x02ff Functions that perform hash operations |
|
0x0300..0x03ff Generic functions that get block and tx info |
|
0x0400..0x04ff Generic functions that check balances and perform ops |
|
0x0500..0x05ff Platform specific functions that get block and tx info |
|
0x0600..0x06ff Platform specific functions that check balances and perform ops |
|
|
|
As cryptographic hash operations are *expensive* operations it is suggested that the "fee" for each of those |
|
function calls be higher than that of others (fees themselves are a platform specific implementation issue). |
|
|
|
Function Name Number AT op code Operation (and comments) |
|
------------------------- ------ ----------------- ---------------------------------------------------------- |
|
Get_A1 0x0100 EXT_FUN_RET sets @addr to A1 |
|
Get_A2 0x0101 EXT_FUN_RET sets @addr to A2 |
|
Get_A3 0x0102 EXT_FUN_RET sets @addr to A3 |
|
Get_A4 0x0103 EXT_FUN_RET sets @addr to A4 |
|
Get_B1 0x0104 EXT_FUN_RET sets @addr to B1 |
|
Get_B2 0x0105 EXT_FUN_RET sets @addr to B2 |
|
Get_B3 0x0106 EXT_FUN_RET sets @addr to B3 |
|
Get_B4 0x0107 EXT_FUN_RET sets @addr to B4 |
|
|
|
Set_A1 0x0110 EXT_FUN_DAT sets A1 from $addr |
|
Set_A2 0x0111 EXT_FUN_DAT sets A2 from $addr |
|
Set_A3 0x0112 EXT_FUN_DAT sets A3 from $addr |
|
Set_A4 0x0113 EXT_FUN_DAT sets A4 from $addr |
|
Set_A1_A2 0x0114 EXT_FUN_DAT_2 sets A1 from $addr1 and A2 from $addr2 |
|
Set_A3_A4 0x0115 EXT_FUN_DAT_2 sets A3 from $addr1 and A4 from $addr2 |
|
Set_B1 0x0116 EXT_FUN_DAT sets B1 from $addr |
|
Set_B2 0x0117 EXT_FUN_DAT sets B2 from $addr |
|
Set_B3 0x0118 EXT_FUN_DAT sets B3 from $addr |
|
Set_B4 0x0119 EXT_FUN_DAT sets B4 from $addr |
|
Set_B1_B2 0x011a EXT_FUN_DAT_2 sets B1 from $addr1 and B2 from $addr2 |
|
Set_B3_B4 0x011b EXT_FUN_DAT_2 sets B3 from $addr1 and B4 from $addr2 |
|
|
|
Clear_A 0x0120 EXT_FUN sets A to zero (A being A1..4) |
|
Clear_B 0x0121 EXT_FUN sets B to zero (B being B1..4) |
|
Clear_A_And_B 0x0122 EXT_FUN sets both A and B to zero |
|
Copy_A_From_B 0x0123 EXT_FUN copies B into A |
|
Copy_B_From_A 0x0124 EXT_FUN copies A into B |
|
Check_A_Is_Zero 0x0125 EXT_FUN_RET @addr to 1 if A is zero or 0 if it is not (i.e. bool) |
|
Check_B_Is_Zero 0x0126 EXT_FUN_RET @addr to 1 if B is zero of 0 if it is not (i.e. bool) |
|
Check_A_Equals_B 0x0127 EXT_FUN_RET @addr to bool if A is equal to B |
|
Swap_A_and_B 0x0128 EXT_FUN swap the values of A and B |
|
OR_A_with_B 0x0129 EXT_FUN sets A to A | B (bitwise OR) |
|
OR_B_with_A 0x012a EXT_FUN sets B to B | A (bitwise OR) |
|
AND_A_with_B 0x012b EXT_FUN sets A to A & B (bitwise AND) |
|
AND_B_with_A 0x012c EXT_FUN sets B to B & A (bitwise AND) |
|
XOR_A_with_B 0x012d EXT_FUN sets A to A ^ B (bitwise XOR) |
|
XOR_B_with_A 0x012e EXT_FUN sets B to B ^ A (bitwise XOR) |
|
--- NOTE: These 8 math ops are intended for a future implementation so no need to support them currently. |
|
Add_A_To_B 0x0140 EXT_FUN adds A to B (result in B) |
|
Add_B_To_A 0x0141 EXT_FUN adds B to A (result in A) |
|
Sub_A_From_B 0x0142 EXT_FUN subs A from B (result in B) |
|
Sub_B_From_A 0x0143 EXT_FUN subs B from A (result in A) |
|
Mul_A_By_B 0x0144 EXT_FUN multiplies A by B (result in B) |
|
Mul_B_By_A 0x0145 EXT_FUN multiplies B by A (result in A) |
|
Div_A_By_B 0x0146 EXT_FUN divides A by B (result in B)* |
|
Div_B_By_A 0x0147 EXT_FUN divides B by A (result in A)* |
|
|
|
* note that these functions could cause a divide by zero error which would put the machine in error |
|
|
|
MD5_A_To_B 0x0200 EXT_FUN take an MD5 hash of A1..2 and put this is B1..2 |
|
Check_MD5_A_With_B 0x0201 EXT_FUN_RET @addr to bool if MD5 hash of A1..2 matches B1..2 |
|
HASH160_A_To_B 0x0202 EXT_FUN take a RIPEMD160 hash of A1..3 and put this in B1..3 |
|
Check_HASH160_A_With_B 0x0203 EXT_FUN_RET @addr to bool if RIPEMD160 hash of A1..3 matches B1..3 |
|
SHA256_A_To_B 0x0204 EXT_FUN take a SHA256 hash of A and put this in B |
|
Check_SHA256_A_With_B 0x0205 EXT_FUN_RET @addr to bool if SHA256 hash of A matches B |
|
|
|
Get_Block_Timestamp 0x0300 EXT_FUN_RET sets @addr to the timestamp of the current block |
|
Get_Creation_Timestamp 0x0301 EXT_FUN_RET sets @addr to the timestamp of the AT creation block |
|
Get_Last_Block_Timestamp 0x0302 EXT_FUN_RET sets @addr to the timestamp of the previous block |
|
Put_Last_Block_Hash_In_A 0x0303 EXT_FUN puts the block hash of the previous block in A |
|
A_To_Tx_After_Timestamp 0x0304 EXT_FUN_DAT sets A to tx hash of the first tx after $addr timestamp |
|
Get_Type_For_Tx_In_A 0x0305 EXT_FUN_RET if A is a valid tx then @addr to tx type* |
|
Get_Amount_For_Tx_In_A 0x0306 EXT_FUN_RET if A is a valid tx then @addr to tx amount** |
|
Get_Timestamp_For_Tx_In_A 0x0307 EXT_FUN_RET if A is a valid tx then @addr to the tx timestamp |
|
Get_Random_Id_For_Tx_In_A 0x0308 EXT_FUN_RET if A is a valid tx then @addr to the tx random id*** |
|
Message_From_Tx_In_A_To_B 0x0309 EXT_FUN if A is a valid tx then B to the tx message**** |
|
B_To_Address_Of_Tx_In_A 0x030a EXT_FUN if A is a valid tx then B set to the tx address |
|
B_To_Address_Of_Creator 0x030b EXT_FUN sets B to the address of the AT's creator |
|
|
|
* tx type is 0 for a normal tx and 1 for a message tx |
|
** amount will always have the minimum fee subtracted from it |
|
*** a random id is a 64 bit signed value (that is always returned positive) and this is a blocking function |
|
**** if the tx does not include a message tx then this will zero out the B value |
|
|
|
NOTE: For all cases where A is not a valid tx @addr will be set to 0xffffffffffffffff |
|
|
|
Get_Current_Balance 0x0400 EXT_FUN_RET sets @addr to current balance of the AT |
|
Get_Previous_Balance 0x0401 EXT_FUN_RET sets @addr to the balance it had last had when running* |
|
Send_To_Address_In_B 0x0402 EXT_FUN_DAT if B is a valid address then send it $addr amount** |
|
Send_All_To_Address_In_B 0x0403 EXT_FUN if B is a valid address then send it the entire balance |
|
Send_Old_To_Address_In_B 0x0404 EXT_FUN if B is a valid address then send it the old balance** |
|
Send_A_To_Address_In_B 0x0405 EXT_FUN if B is a valid address then send it A as a message |
|
Add_Minutes_To_Timestamp 0x0406 EXT_FUN_RET_DAT_2 set @addr1 to timestamp $addr2 plus $addr3 minutes*** |
|
|
|
* this amount does not include any additional amounts sent to the AT between "execution events" |
|
** if this amount is greater than the AT's balance then it will only send the current balance amount |
|
*** the API is expected to base this timestamp according to the "average block time" for the blockchain |
|
|
|
</pre> |
|
</div> |
|
</div> |
|
|
|
<div style="visibility: visible;" id="footer"> |
|
<p> |
|
<div class="footer-icon"><a target="_blank" href="//ciyam.org/"><img src="logo-gryscl-128.png" /></a></div> |
|
© 2012-2015 CIYAM Developers |
|
</p> |
|
</div> |
|
</body> |
|
|
|
</html> |
|
|
|
|