mirror of
https://github.com/Qortal/AT.git
synced 2025-01-30 19:02:14 +00:00
169 lines
11 KiB
HTML
169 lines
11 KiB
HTML
|
<!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>
|
||
|
|
|