01 前言" Q& ~' Q- j9 X" q( Z3 C
在之前的技术视点文章中，我们介绍了目前本体主网支持的智能合约体系以及相应的智能合约开发工具 SmartX。很多小伙伴都想上手练一练。在本期的本体技术视点中，我们将正式开始讲述智能合约语法部分。/ M1 D1 y5 B* O8 ?% _! v
本体的智能合约 API 分为7个模块，分别是 Blockchain & Block API、Runtime API、Storage API、Native API、Upgrade API、Execution Engine API 以及 Static & Dynamic Call API。本期我们将介绍 Blockchain & Block API，这是本体智能合约体系中最基础的部分。其中，Blockchain API 支持基本的区块链查询操作，如获取当前块高等；Block API 支持基本的区块查询操作，如查询指定区块交易数等。同时，文末将提供视频讲解。
5 c! c$ s  `/ e( {在这之前，小伙伴们可以在本体智能合约开发工具 SmartX 中新建一个合约，跟着我们进行操作。
1 q' u! [" q' S% M: S. X& ]02 Blockchain API 使用方法" h# a' n8 o) `+ ]2 H  k4 l
智能合约函数的引用与 Python 的引用如出一辙。开发者可以根据需要引入相应的函数。例如，下面语句引入了获取当前最新块高函数 GetHeight 和获取区块头函数 GetHeader。
  s+ C9 `! \% I9 V- |  f' mfrom ontology.interop.System.Blockchain import GetHeight, GetHeader6 B: D( M% I) E
2.1 GetHeight" i% p; g8 F$ C4 g6 w
开发者可以使用 GetHeight 来获取当前最新块高，具体例子如下。在后面的例子中，为了节省空间，我们将省略 Main 函数，小伙伴在练习的时候可以根据需要加入。
; |  @5 N  |2 D5 Vfrom ontology.interop.System.Runtime import Notify
5 Z# C* q2 {- b  h" T: B+ J: Ffrom ontology.interop.System.Blockchain import GetHeight
7 t6 V# H8 U3 g6 w5 A  ~( vdef Main(operation):8 D* x. }0 ~. t3 G% N8 Q
    if operation == 'demo':! r' j* t" h; b% [) }# D% V( U' j2 \
        return demo(); g8 A3 z) c6 B4 Q+ H+ F# ?
    return False2 U7 |/ |  Q& G+ |; c3 K7 H
def demo():3 j6 C# M# L8 f% J8 V3 }
    height=GetHeight()- c3 a' f1 g/ q9 |5 Z4 g
    Notify(height) # 打印height1 B9 f: [1 i+ \; R  K. q/ F
    return height #在函数运行结束后返回height, r1 D3 ^" E* T% Z8 w
2.2 GetHeader9 W8 [/ j* f7 @8 B, H- U. M" ~1 Z
开发者可以使用 GetHeader 来获取区块头，参数是某个块的块高。具体例子如下：
6 Y% [" J* H9 p( v& k5 C7 ]from ontology.interop.System.Runtime import Notify) ^/ R3 x9 x3 @" E
from ontology.interop.System.Blockchain import GetHeader2 ~6 Y& `  `; _7 {1 v
def demo():
  b& ^* q0 t: h& |! n) P4 u7 w) \    block_height=10
+ p! n1 _( i# N* t    header=GetHeader(block_height) , `, g7 N5 x1 e1 j
    Notify(header)
1 n# Z# G3 z9 {. Areturn header8 j' |% ?6 Y) D% x5 r  @# {
2.3 GetTransactionByHash
2 e' H" ?3 e$ y' v" w/ C- x/ p/ M$ e开发者可以使用 GetTransactionByHash 函数通过交易哈希获取交易。交易哈希以 bytearray 的格式，作为参数传入 GetTransactionByHash。这个函数的关键在于如何转换将十六进制格式的交易哈希转变为 bytearray 格式的交易哈希。
5 n5 V) k' g- w' I- Q$ p" M4 @% r我们以16进制格式的交易哈希为例，实现将十六进制格式的交易哈希转变为 bytearray 格式的交易哈希。示例哈希如下：1 j- U1 H) I9 A6 D
9f270aa3a4c13c46891ff0e1a2bdb3ea0525669d414994aadf2606734d0c89c1! t- r5 m& r# r5 d# H7 o6 S7 |
首先，将该交易哈希反序得到：
7 M$ v' X6 u$ H- @2 b; g/ l/ W) R+ ~# lc1890c4d730626dfaa9449419d662505eab3bda2e1f01f89463cc1a4a30a279/ W! \1 a/ S. x7 I0 D
开发者可以通过 SmartX 提供的转换工具 Hex Number(little endian)  Number 实现这一步。
4 j9 g- s5 T4 S然后，将其转成 bytearray 格式：7 ^" {; {( V4 v  {
{0xc1,0x89,0x0c,0x4d,0x73,0x06,0x26,0xdf,0xaa,0x94,0x49,0x41,0x9d,0x66,0x25,0x05,0xea,0xb3,0xbd,0xa2,0xe1,0xf0,0x1f,0x89,0x46,0x3c,0xc1,0xa4,0xa3,0x0a,0x27,0x9f}
# X) U1 m) Z7 z3 E, n开发者可以通过 SmartX 提供的转换工具 String  Byte Array 实现这一步。
( r3 i1 B4 P  w- d4 c. g最后，将得到的 bytearray 转换成相应的字符串：8 o" O) |# I' T, q" k  J+ \# L
\xc1\x89\x0c\x4d\x73\x06\x26\xdf\xaa\x94\x49\x41\x9d\x66\x25\x05\xea\xb3\xbd\xa2\xe1\xf0\x1f\x89\x46\x3c\xc1\xa4\xa3\x0a\x27\x9f
& j3 F/ J8 k, PGetTransactionByHash 函数通过交易哈希获取交易的例子如下：( q) O* k* ]& f7 P  }! r4 q
from ontology.interop.System.Blockchain import GetTransactionByHash
4 w5 W3 m& Q# @6 qdef demo():
  C& Q) c1 `7 f2 j; J% b    # tx_hash="9f270aa3a4c13c46891ff0e1a2bdb3ea0525669d414994aadf2606734d0c89c1"    ( m  U# C. |) k4 X
    tx_hash=bytearray(b"\xc1\x89\x0c\x4d\x73\x06\x26\xdf\xaa\x94\x49\x41\x9d\x66\x25\x05\xea\xb3\xbd\xa2\xe1\xf0\x1f\x89\x46\x3c\xc1\xa4\xa3\x0a\x27\x9f")
# A6 }2 o; f$ T( e% j    tx=GetTransactionByHash(tx_hash)% n2 \! X2 `8 h/ m  f9 P
    return tx/ g/ M% Q/ w% n
2.4 GetTransactionHeight! L) G6 o* [% _: }7 r# S2 h  N
开发者可以使用 GetTransactionHeight 函数通过交易哈希获取交易高度。我们还是以上个例子中的哈希为例：
* s$ p  p* O: V) q5 D* s2 e9 H! ifrom ontology.interop.System.Blockchain import  GetTransactionHeight
; V+ y" l0 ?. m9 ndef demo():, T9 W+ p% O2 @7 u3 Q' I
    # tx_hash="9f270aa3a4c13c46891ff0e1a2bdb3ea0525669d414994aadf2606734d0c89c1"    # x$ ?1 H9 h+ m& K' A
    tx_hash=bytearray(b"\xc1\x89\x0c\x4d\x73\x06\x26\xdf\xaa\x94\x49\x41\x9d\x66\x25\x05\xea\xb3\xbd\xa2\xe1\xf0\x1f\x89\x46\x3c\xc1\xa4\xa3\x0a\x27\x9f")
, @6 U' y, |  w6 ]- x    height=GetTransactionHeight(tx_hash)) r. b4 \# d: R% B+ t+ p) k, f
    return height
! B3 ~8 W* J' ~' j7 L& }4 A* }2.5 GetContract* q. A) f( U( Q5 P
开发者可以使用 GetContract 函数通过合约哈希获取合约。其中，合约哈希的转换过程与上面讲到的交易哈希转换过程一致。1 w1 \: C  M  x( j& M/ s) H
from ontology.interop.System.Blockchain import GetContract/ ?' \/ L2 }/ P' x, H$ R; ^
def demo():- P" z9 [$ G( V7 p: y
    # contract_hash="d81a75a5ff9b95effa91239ff0bb3232219698fa"   
: N3 W1 F: y* ^% h9 I% B1 V; }5 F% `    contract_hash=bytearray(b"\xfa\x98\x96\x21\x32\x32\xbb\xf0\x9f\x23\x91\xfa\xef\x95\x9b\xff\xa5\x75\x1a\xd8")( n: f" X/ I0 s& k
    contract=GetContract(contract_hash)
4 K7 e6 ^! [" V9 A    return contract
& P' n% @7 c7 w; {$ W" x# [2.6 GetBlock: h$ Q6 a8 C6 y9 @- r% ~# n
开发者可以使用 GetBlock 函数获取区块。有两种方法可以获取指定区块：
& [2 z# e; q4 g. S0 Z( g. O通过块高获取区块：
& j% b+ }2 k- h8 R9 D( F" U* E) v, Q, _8 x+ c& P; m5 X
from ontology.interop.System.Blockchain import GetBlock  I, ^- N, M. e6 ?  t* `2 W* p
def demo():
! t1 y5 g2 O0 N. |    block=GetBlock(1408)
. I; `) c/ ]. L- F! K9 [    return block
" o" q( o$ f3 a3 S2. 通过区块哈希获取区块：) @# O5 i  W! Y& o
from ontology.interop.System.Blockchain import GetBlock
6 B7 Q% _0 W4 o; y+ H0 u. ]def demo():    ) y9 v3 v2 Z1 i2 _: s
    block_hash=bytearray(b'\x16\xe0\xc5\x40\x82\x79\x77\x30\x44\xea\x66\xc8\xc4\x5d\x17\xf7\x17\x73\x92\x33\x6d\x54\xe3\x48\x46\x0b\xc3\x2f\xe2\x15\x03\xe4')
+ ~$ k! D3 p6 I0 i4 G. F! @    block=GetBlock(block_hash)
% B6 D- H: B, a1 W3 Q03 Block API 使用方法
" e: C: P" p9 S) ZBlock API 中可供引用的函数有三个，它们分别是 GetTransactions、GetTransactionCount 和 GetTransactionByIndex。我们依次介绍下这三个函数。( i, |- O5 d* }. ]6 R0 k
3.1 GetTransactionCount3 X. j9 k1 k$ ?: T
开发者可以使用 GetTransactionCount 函数获取指定区块的交易数量。
, O( [* i& m$ @from ontology.interop.System.Block import GetTransactionCount/ u- h. ~0 }6 g. q1 m$ i
def demo():& J. L0 s3 x4 X1 H) g0 x, x' N* H0 V6 N
    block=GetBlock(1408)
! d. e: ]& V) S4 d' M& ~: F- k/ {    count=GetTransactionCount(block); P- c" [. I0 p6 ~7 P- C
    return count+ |# r" J8 z. s) y$ @  Y3 d
**
8 z7 W* i) Q9 l3.2 GetTransactions**
8 W& D/ R4 J# e开发者可以使用 GetTransactions 函数获取获取指定区块的所有交易。
2 n- C' a+ @# K4 G; W0 M' a& efrom ontology.interop.System.Blockchain import GetBlock! X7 w& A2 j! e
from ontology.interop.System.Block import GetTransactions 9 @1 z. a) d" Z: B. o  H1 `% I
def demo():
& V6 B* I/ I. ^7 y& h% p  I3 U    block=GetBlock(1408)
5 ^6 |% n1 x  H0 R' t5 \    txs=GetTransactions(block)3 n( Y% v& }$ H/ J
    return txs/ s' u( j) M/ L
3.3 GetTransactionByIndex" r$ ^8 x7 t. J0 t- ^9 N6 o0 r
开发者可以使用 GetTransactionByIndex 函数获取指定区块的指定交易。) ~8 f. ~( ^0 |% R9 y
from ontology.interop.System.Blockchain import GetBlock$ z$ t2 I, s) |. X
from ontology.interop.System.Block import GetTransactionByIndex8 x) x6 m" v8 a, p
def demo():
3 X% Z9 o4 F* n2 u  x6 D# s& w    block=GetBlock(1408)* L7 c* O6 W1 @7 r$ X; u2 a4 H  Z
    tx=GetTransactionByIndex(block,0) # index starts from 0.: k  |/ l- a" L* f  e# e0 A  C
    return tx: P6 m( A2 o0 f- s4 x5 s' b
04 后记
) U  ^% I2 D) `2 s3 v9 jBlockchain & Block API 在智能合约中起到查询区块链数据和区块数据的作用，是智能合约最不可缺少的一部分。在后面的技术视点中，我们将讨论如何使用其它 API，探讨它们和本体区块链的交互。、