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
