Websocket接口

Websocket接口与JSON-RPC接口的主要区别在于， 使用WebSocket API，客户端和节点只需要完成一次握手， 两者之间就可以直接创建持久性的连接，并进行双向数据传输。 并且节点可以主动向已连接的客户端推送数据，实现订阅/发布。

websocket请求由 command 域指定调用的方法， 与 command 同一级别写调用的参数。

格式示例：

{
    "command": "method_name",
    "id": 123,
    "param1Name":"...",
    "param2Name":"..."
}

接口类型与JSON-RPC一样，可以分为交易类和查询类接口。本文只列举部分接口，其它接口请参考JSON-RPC接口。

接口返回值

交易类接口

Websocket交易类接口返回的JSON包含的各个域如下：

域	类型	描述
id	整数或者字符串	与请求的id一致。
type	字符串	标识数据类型，response表示对命令的响应，异步通知使用不同的值（例如：table、transaction）。
status	字符串	标识交易是否已被服务节点成功接收并且解析成功
result	对象	包含返回状态和具体结果，内容因命令而异。
result.engine_result	字符串	表明交易请求解析成功，并且能够被处理，现阶段的处理结果。
result.engine_result_code	整形	与engine_result关联的整形值。
result.engine_result_message	字符串	交易状态结果的描述。
reqeust	对象	请求处理出错时，展示原始请求的格式。
error	字符串	如果交易请求解析或者处理出错，返回错误类型码。
error_code	字符串	与error关联的整形值。
error_message	字符串	错误原因的描述。

成功示例

{
    "id": 2,
    "result": {
        "engine_result": "tesSUCCESS",
        "engine_result_code": 0,
        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
        "tx_blob": "12000022800000002400000003201B00001F40614000000005F5E10068400000000000000A73210330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD02074473045022100C57C4430FDC9F43CD0EC5BFACFCF09582399D0414F7484DEA8D5AEA1D315605502200A9C569863A4654D073EDC273E7321652887B6610CE0C20DB3E35A38639F62DD8114B5F762798A53D543A014CAF8B297CFF8F2F937E88314934CD4FACC490E3DC5152F7C1BAD57EEEE3F9C77",
        "tx_json": {
            "Account": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
            "Amount": "100000000",
            "Destination": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
            "Fee": "10",
            "Flags": 2147483648,
            "LastLedgerSequence": 8000,
            "Sequence": 3,
            "SigningPubKey": "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020",
            "TransactionType": "Payment",
            "TxnSignature": "3045022100C57C4430FDC9F43CD0EC5BFACFCF09582399D0414F7484DEA8D5AEA1D315605502200A9C569863A4654D073EDC273E7321652887B6610CE0C20DB3E35A38639F62DD",
            "hash": "8D1CC127661FD004B6700AB60CEC8C0EB0A733CF894A074C635914FAE49C928F"
        }
    },
    "status": "success",
    "type": "response"
}

出错示例

{
    "error": "badSecret",
    "error_code": 42,
    "error_message": "Secret does not match account.",
    "id": 2,
    "request": {
        "command": "submit",
        "id": 2,
        "secret": "xnoPBzXtMeMyMHUVTgbuqAfg1SUTb",
        "tx_json": {
            "Account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
            "Amount": "100000000",
            "Destination": "zcPMx2Zp4p9UnYaMtPLDwpSR5YFaa4E2SR",
            "TransactionType": "Payment"
        }
    },
    "status": "error",
    "type": "response"
}

查询类接口

Websocket查询类接口返回的JSON包含的各个域如下：

域	类型	描述
id	整数或者字符串	与请求的id一致。
type	字符串	标识数据类型，response表示对命令的响应，异步通知使用不同的值（例如：table、transaction）。
status	字符串	标识请求是否已被服务节点成功接收并且解析成功。
result	对象	包含返回状态和具体结果，内容因命令而异。
reqeust	对象	请求处理出错时，展示原始请求的格式。
error	字符串	如果请求解析或者处理出错，返回错误类型码。
error_code	字符串	与error关联的整形值。
error_message	字符串	错误原因的描述。

成功示例

{
    "id": 5,
    "result": {
        "lines": [
        ]
    },
    "status": "success",
    "type": "response"
}

出错示例

{
    "error":"actNotFound",
    "error_code":19,
    "error_message":"Account not found.",
    "request":{
        "account":"zcPMx2Zp4p9UnYaMtPLDwpSR5YFaa4E2SR",
        "command":"account_lines",
        "ledger_index":"validated"
    },
    "status":"error",
    "type":"response"
}

交易类接口

交易类接口包含基本的ChainSQL交易类接口、chainsqld新增的数据库表交易接口、 智能合约交易类接口。交易的通用格式如下：

域	类型	描述
id	整形	请求ID，异步模型，用来配对请求和应答。
command	字符串	必填，接口（命令）名。
tx_blob	字符串	可选，具体交易jSON格式增加签名后的16进制格式。如果提供这个域，则下面的域都可以省略。
tx_json	对象	具体交易的json格式。
TransactionType	字符串	指定具体的交易类型。
secret	字符串	账户私钥，发送给服务节点，节点代替用户对交易进行签名。

警告

交易类接口都需要将交易JSON进行签名或者向服务节点提供账户的私钥， 本文中展示的示例主要是通过向服务节点提供账户私钥的方式。 如果服务节点不可信任，或者请求通过公共网络发送，则存在风险。

ChainSQL 交易

ChainSQL Websocket交易类接口有很多，下面展示一个示例。

转账

请求格式：

{
    "id": 2,
    "command": "submit",
    "tx_json" : {
        "TransactionType" : "Payment",
        "Account": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
        "Amount": "100000000",
        "Destination": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx"
    },
    "secret" : "xnoPBzXtMeMyMHUVTgbuqAfg1SUTb"
}

应答格式：

{
    "id": 2,
    "result": {
        "engine_result": "tesSUCCESS",
        "engine_result_code": 0,
        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
        "tx_blob": "12000022800000002400000003201B00001F40614000000005F5E10068400000000000000A73210330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD02074473045022100C57C4430FDC9F43CD0EC5BFACFCF09582399D0414F7484DEA8D5AEA1D315605502200A9C569863A4654D073EDC273E7321652887B6610CE0C20DB3E35A38639F62DD8114B5F762798A53D543A014CAF8B297CFF8F2F937E88314934CD4FACC490E3DC5152F7C1BAD57EEEE3F9C77",
        "tx_json": {
            "Account": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
            "Amount": "100000000",
            "Destination": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
            "Fee": "10",
            "Flags": 2147483648,
            "LastLedgerSequence": 8000,
            "Sequence": 3,
            "SigningPubKey": "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020",
            "TransactionType": "Payment",
            "TxnSignature": "3045022100C57C4430FDC9F43CD0EC5BFACFCF09582399D0414F7484DEA8D5AEA1D315605502200A9C569863A4654D073EDC273E7321652887B6610CE0C20DB3E35A38639F62DD",
            "hash": "8D1CC127661FD004B6700AB60CEC8C0EB0A733CF894A074C635914FAE49C928F"
        }
    },
    "status": "success",
    "type": "response"
}

应答域说明请参考JSON-RPC接口下的转账示例。

另外一种使用签名后的交易16进制序列的格式如下：

{
    "id": 2,
    "command": "submit",
    "tx_blob": "12000022800000002400000003201B00001F40614000000005F5E10068400000000000000A73210330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD02074473045022100C57C4430FDC9F43CD0EC5BFACFCF09582399D0414F7484DEA8D5AEA1D315605502200A9C569863A4654D073EDC273E7321652887B6610CE0C20DB3E35A38639F62DD8114B5F762798A53D543A014CAF8B297CFF8F2F937E88314934CD4FACC490E3DC5152F7C1BAD57EEEE3F9C77"
}

参数说明：

域	类型	描述
id	整形	请求ID，异步模型，用来配对请求和应答。
command	字符串	指定websocket接口（命令）名。 交易请求的主要命令是submit，还有一些非交易类的辅助命令，比如签名交易，查询交易等。
tx_blob	字符串	带签名字段的具体交易的16进制序列。

应答格式：

{
    "id": 2,
    "result": {
        "engine_result": "tesSUCCESS",
        "engine_result_code": 0,
        "engine_result_message": "The transaction was applied. Only final in a validated ledger.",
        "tx_blob": "12000022800000002400000003201B00001F40614000000005F5E10068400000000000000A73210330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD02074473045022100C57C4430FDC9F43CD0EC5BFACFCF09582399D0414F7484DEA8D5AEA1D315605502200A9C569863A4654D073EDC273E7321652887B6610CE0C20DB3E35A38639F62DD8114B5F762798A53D543A014CAF8B297CFF8F2F937E88314934CD4FACC490E3DC5152F7C1BAD57EEEE3F9C77",
        "tx_json": {
            "Account": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
            "Amount": "100000000",
            "Destination": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
            "Fee": "10",
            "Flags": 2147483648,
            "LastLedgerSequence":8000,
            "Sequence": 3,
            "SigningPubKey": "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020",
            "TransactionType": "Payment",
            "TxnSignature": "3045022100C57C4430FDC9F43CD0EC5BFACFCF09582399D0414F7484DEA8D5AEA1D315605502200A9C569863A4654D073EDC273E7321652887B6610CE0C20DB3E35A38639F62DD",
            "hash": "8D1CC127661FD004B6700AB60CEC8C0EB0A733CF894A074C635914FAE49C928F"
        }
    },
    "status": "success",
    "type": "response"
}

签名

ChainSQL提供了为交易签名接口，可以用来辅助做功能测试。 用户将具体交易的JSON格式和私钥传递个服务节点，节点帮助用户进行交易的签名后，返回交易的tx_blob， 之后用户可以调用submit命令提交交易。

警告

与submit命令一样，同样需要提供账户私钥给节点，如果服务节点不可信任，或者请求通过公共网络发送， 账户私钥存在被窃取的风险，工程项目中应使用本地签名的方式，或使用本档中的Java和Node.js接口。

下面示例签名一个转账交易。

请求格式：

{
    "id": 2,
    "command": "sign",
    "tx_json" : {
        "TransactionType" : "Payment",
        "Account": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
        "Amount": "100000000",
        "Destination": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
        "LastLedgerSequence": 8000
    },
    "secret" : "xnoPBzXtMeMyMHUVTgbuqAfg1SUTb",
    "offline": false,
    "fee_mult_max": 1000
}

参数说明：

域	类型	描述
tx_json	对象	具体交易的JSON格式，这里为转账交易。
tx_json.LastLedgerSequence	整数	可选，允许交易进入的最大区块号。如不提供，节点会默认在当前区块号的基础上加上一个值，手动测试，建议使用一个较大的值。
secret	字符串	必填，账户私钥。

应答格式：

{
    "id": 2,
    "result": {
        "tx_blob": "12000022800000002400000003201B00000FFC614000000005F5E10068400000000000000A73210330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD02074473045022100EF12099B281DCD9EB7D23B020CCEA8817E598C4A0EB0DD7365A52B318B2778CB02205AAAAD30B2C3BE33E20334BEBCAB30B4217A21BBD7A7B0C80F13F93D257BB0408114B5F762798A53D543A014CAF8B297CFF8F2F937E88314934CD4FACC490E3DC5152F7C1BAD57EEEE3F9C77",
        "tx_json": {
            "Account": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
            "Amount": "100000000",
            "Destination": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
            "Fee": "10",
            "Flags": 2147483648,
            "LastLedgerSequence": 4092,
            "Sequence": 3,
            "SigningPubKey": "0330E7FC9D56BB25D6893BA3F317AE5BCF33B3291BD63DB32654A313222F7FD020",
            "TransactionType": "Payment",
            "TxnSignature": "3045022100EF12099B281DCD9EB7D23B020CCEA8817E598C4A0EB0DD7365A52B318B2778CB02205AAAAD30B2C3BE33E20334BEBCAB30B4217A21BBD7A7B0C80F13F93D257BB040",
            "hash": "138436054D740225C562D194AC8DF045E440C8F93FE0A8027956B8FD4FD6D0CF"
        }
    },
    "status": "success",
    "type": "response"
}

应答域说明：

域	类型	描述
tx_json	对象	加工后的完整交易的json格式。
tx_blob	字符串	签名后的交易的16进制格式，用于提交交易。查看第二种转账方法。

数据库表交易

数据库表交易类型接口可以分为三种，TableListSet接口、SQLStatement接口、SQLTranscation接口。每种类型的接口对应不同的数据库操作语句。

TableListSet

TableListSet交易接口主要对应SQL的数据定义语句（DDL）和数据控制语句（DCL）。 具体包含的操作有创建表、删除表、表重命名、表授权、表重建等操作，只有表的创建者可以进行删除及授权等其它操作。

TableListSet类型的交易的json格式（tx_json对象）各个域的描述如下：

域	json类型	内部类型	描述
TransactionType	字符串	String	必填，交易类型为”TableListSet”。
Account	字符串	AccountID	必填，发起交易的账户地址，用于操作鉴权。
Tables	数组	Array	必填，指定本次操作所涉及的表。
Table	对象	Object	必填，描述一张表。
TableName	字符串	Blob	必填，指定用户层的表名。
OpType	整型	UInt32	必填，具体操作类型有：1：创建表，2：删除表，3：改重命名，10：验证断言，11：表授权，12：表重建，13：多链整合。
Raw	数组	Array	可选，用来指定列的属性，或是查询条件。也可以是SQL语句。
NameInDB	字符串	Hash160	可选，数据库中对应的实际表名。
TableNewName	字符串	Blob	可选，表重命名操作需要指定。
User	字符串	AccountID	可选，表授权操作中，被授权的账户地址。
Flags	整型	UInt32	可选，表授权操作中，表示被授予的权限。
TxCheckHash	字符串	Hash256	可选，strict模式时设置的校验。
Token	字符串	Blob	可选，创建表、授权表操作中用户公钥加密的密文。
OperationRule	对象	Blob	可选，行级控制规则。

示例：

创建表

注解

以下交易的示例均只展示具体交易的JSON格式（tx_json对象）部分。都可通过本地签名后（或者使用secret域携带账户私钥） 调用submit接口将交易发往全网共识。

请求格式：

{
    "TransactionType": "TableListSet",
    "Account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "Tables": [
        {
            "Table": { "TableName": "Table1" }
        }
    ],
    "OpType": 1,
    "Raw": [
        {
            "field": "id",
            "type": "int",
            "length": 11,
            "PK": 1,
            "NN": 1,
            "UQ": 1,
            "index": 1
        },
        {
            "field": "age",
            "type": "int"
        },
        {
            "field": "first_name",
            "type": "varchar",
            "length": 64
        },
        {
            "field": "full_name",
            "type": "varchar",
            "length": 64
        }
    ],
    "Confidential": false
}

应答格式：

{
    "resultCode": "tesSUCCESS",
    "resultMessage": "The transaction was applied. Only final in a validated ledger."
}

删除表

请求格式：

{
    "TransactionType": "TableListSet",
    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Tables": [
        {
            "Table": {
                "TableName": "ExampleName",
                "NameInDB": "48C80D2CF136054DB6F0116D4833D4DAD1D4CED5"
            }
        }
    ],
    "OpType": 2
}

应答格式同上。

重命名表

{
    "TransactionType": "TableListSet",
    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Tables": [
        {
            "Table": {
               "TableName": "ExampleName",
                "TableNewName": "ExampleNameNew"
            }
        }
    ],
    "OpType": 3
}

应答格式同上。

重建表

{
    "OpType": 12,
    "Tables": [
        {
            "Table": {
                "TableName": "ExampleName",
                "NameInDB": "48C80D2CF136054DB6F0116D4833D4DAD1D4CED5"
            }
        }
    ],
    "Fee": 12,
    "Sequence": 6
}

应答格式同上。

表授权

{
    "TransactionType": "TableListSet",
    "Account ": "zf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Tables": [
        {
            "Table": { "TableName": "ExampleName" }
        }
    ],
    "OpType": 11,
    "User": "zBGagHrWQ44SX3YE7eYehiDA8iNPdBssFY",
    "Raw": [
        {
            "select": true,
            "insert": true,
            "update": true,
            "delete": true
        }
    ]
}

应答格式同上。

SQLStatement

SQLStatement交易接口主要对应SQL的数据操纵语句（DML）。 具体包含的操作有增、删、改操作，只有表的创建者和被授权的账户具有操作权限。

SQLStatement类型的交易的json格式（tx_json对象）各个域的描述如下：

域	json类型	内部类型	描述
TransactionType	字符串	String	必填，交易类型为”SQLStatement”。
Account	字符串	AccountID	必填，发起交易的账户地址，用于操作鉴权。
Owner	字符串	AccountID	必填，用来指定表的创建者。
Tables	数组	Array	必填，指定本次操作所涉及的表。
Table	对象	Object	必填，描述一张表。
TableName	字符串	Blob	必填，指定用户层的表名。
OpType	整型	UInt32	必填，具体操作类型有：6:插入记录, 8:更新记录,9:删除记录。
Raw	数组	Array	可选，用来指定列的属性，或是查询的列和条件。也可以是SQL语句。
NameInDB	字符串	Hash160	可选，数据库中对应的实际表名。
TxCheckHash	字符串	Hash256	可选，strict模式时设置的校验。
AutoFillField	字符串	String	可选，用于插入操作，指定将此次交易的哈希插入到指定的列。
OperationRule	对象	Object	可选，行级控制规则。

示例：

插入记录

{
    "TransactionType": "SQLStatement",
    "Account": "zf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Owner": "zf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Tables": [
        {
            "Table": {
                "TableName": "ExampleName",
                "NameInDB": "48C80D2CF136054DB6F0116D4833D4DAD1D4CED5"
            }
        }
    ],
    "Raw": [
        {
            "id": 1,
            "name": "test"
        },
        {
            "id": 2,
            "name": "hello"
        }
    ],
    "OpType": 6,
    "AutofillField": "txHash"
}

应答格式同上。

更新记录

{
    "TransactionType": "SQLStatement",
    "Account": "zf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Owner": "zf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Tables": [
        {
            "Table": {
                "TableName": "ExampleName",
                "NameInDB": "48C80D2CF136054DB6F0116D4833D4DAD1D4CED5"
            }
        }
    ],
    "Raw": [
        { "age": "11", "name": "abc" },
        { "id": 1 }
    ],
    "OpType": 8
}

应答格式同上。

删除记录

{
    "TransactionType": "SQLStatement",
    "Account": "zf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Owner": "zf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Tables": [
        {
            "Table": {
                "TableName": "ExampleName",
                "NameInDB": "48C80D2CF136054DB6F0116D4833D4DAD1D4CED5"
            }
        }
    ],
    "Raw": [
        { "id": 1 }
    ],
    "OpType": 9
}

应答格式同上。

SQLTranscation

事务处理可以用来维护数据库的完整性，保证成批的SQL语句要么全部执行，要么全部不执行。

SQLTranscation websocket交易接口的json格式（tx_json对象）各个域的描述如下：

域	json类型	内部类型	描述
TransactionType	字符串	String	必填，交易类型为”SQLTranscation”。
Account	字符串	AccountID	必填，发起交易的账户地址，用于操作鉴权。
Statements	数组	Array	必填，数组中每一个对象表示事务中每一个具体的操作。
Tables	数组	Array	必填，指定本次操作所涉及的表。
Table	对象	Object	必填，描述一张表。
TableName	字符串	Blob	必填，指定用户层的表名。
OpType	整型	UInt32	必填，支持的操作类型有：6:插入记录，8:更新记录，9:删除记录，10：验证断言，11:表授权。
Raw	数组	Array	可选，用来指定列的属性，或是查询条件。也可以是SQL语句。
NameInDB	字符串	Hash160	可选，数据库中对应的实际表名。
TableNewName	字符串	Blob	可选，表重命名操作需要指定。
User	字符串	AccountID	可选，表授权操作中，被授权的账户地址。
Flags	整型	UInt32	可选，表授权操作中，表示被授予的权限。
TxCheckHash	字符串	Hash256	可选，strict模式时设置的校验。

请求示例：

{
    "TransactionType": "SQLTransaction",
    "Account": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
    "Statements": [
        {
            "Owner": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
            "Tables": [
                {
                    "Table": {
                        "TableName": "EName"
                    }
                }
            ],
            "OpType": 10,
            "Raw": [
                {
                    "$IsExisted": 1
                }
            ]
        },
        {
            "Owner": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
            "Tables": [
                {
                    "Table": {
                        "TableName": "EName"
                    }
                }
            ],
            "Raw": [
                {
                    "id": 1,
                    "name": "PingGuo",
                    "age": 20
                }
            ],
            "OpType": 6
        },
        {
            "Owner": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
            "Tables": [
                {
                    "Table": {
                        "TableName": "Salarys"
                    }
                }
            ],
            "Raw": [
                {
                    "id": 1,
                    "salary": 20
                }
            ],
            "OpType": 6
        },
        {
            "Owner": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
            "Tables": [
                {
                    "Table": {
                        "TableName": "Salarys"
                    }
                }
            ],
            "Flags": 65536,
            "OpType": 10,
            "Raw": [
                {
                    "$RowCount": 1
                },
                {
                    "id": 1,
                    "salary": 20
                }
            ]
        }
    ]
}

上例中，Statements数组中一共4个对象，每个对象分别对应一条语句，4个语句组成一个事务。下面分别说明：

第一条为断言操作，Raw字段为 “$IsExisted”: 1 判断EName表是否存在。

第二条为插入操作，在表EName中增加一行。

第三条也时插入操作，插入另一个表，在表Salary中插入一行。

第四条为断言操作，Raw字段有 “$RowCount”: 1 判断Salary表的总行数是否为1，或者存在id为1并且salary为20的一行。

以上四条语句中只要某条语句执行失败，或者断言错误。整个事务就不会执行，并且回退到初始状态。

应答格式同上。

智能合约交易

智能合约交易类型websocket接口包含部署合约接口和调用合约接口。 接口名使用submit，交易json格式（tx_json对象）各个域的描述如下：

域	json类型	内部类型	描述
TransactionType	字符串	String	必填，交易类型为”Contract”。
ContractOpType	整形	UInt32	必填，表示智能合约的操作类型，1：部署合约，2：调用合约。
Account	字符串	AccountID	必填，发起交易的账户地址，部署合约时也即是合约的所有者。
ContractData	字符串	String	必填，部署合约时用来表示合约的二进制代码(ABI)，这里用16进制表示；调用合约时表示合约参数。
ContractAddress	字符串	ContractID	调用合约时必填，表示合约账户的地址。
ContractValue	整形	UInt32	可选，部署合约时，由部署者账户转账给合约账户的金额。
Gas	整形	UInt32	必填，合约交易（部署和调用）消耗的Gas。

注解

关于智能合约的编写和编译，参考solidity官方文档introduction-smart-contracts。

部署合约

请求格式：

{
    "TransactionType": "Contract",
    "ContractOpType": 1,
    "Account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "ContractData": "60806040526103af806100136000396000f3006080604052600436106100565763ffffffff7c010000000000000000000000000000000000000000000000000000000060003504166306fdde03811461005b57806317d7de7c146100e5578063c47f0027146100fa575b600080fd5b34801561006757600080fd5b506100706101af565b6040805160208082528351818301528351919283929083019185019080838360005b838110156100aa578181015183820152602001610092565b50505050905090810190601f1680156100d75780820380516001836020036101000a031916815260200191505b509250505060405180910390f35b3480156100f157600080fd5b5061007061023d565b34801561010657600080fd5b506101ad6004803603602081101561011d57600080fd5b81019060208101813564010000000081111561013857600080fd5b82018360208201111561014a57600080fd5b8035906020019184600183028401116401000000008311171561016c57600080fd5b91908080601f0160208091040260200160405190810160405280939291908181526020018383808284376000920191909152509295506102d4945050505050565b005b6000805460408051602060026001851615610100026000190190941693909304601f810184900484028201840190925281815292918301828280156102355780601f1061020a57610100808354040283529160200191610235565b820191906000526020600020905b81548152906001019060200180831161021857829003601f168201915b505050505081565b60008054604080516020601f60026000196101006001881615020190951694909404938401819004810282018101909252828152606093909290918301828280156102c95780601f1061029e576101008083540402835291602001916102c9565b820191906000526020600020905b8154815290600101906020018083116102ac57829003601f168201915b505050505090505b90565b80516102e79060009060208401906102eb565b5050565b828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f1061032c57805160ff1916838001178555610359565b82800160010185558215610359579182015b8281111561035957825182559160200191906001019061033e565b50610365929150610369565b5090565b6102d191905b80821115610365576000815560010161036f5600a165627a7a72305820f14ef6e7c6d9774a8d3cf6744bc9569884132a7abce3011ff2de4c69a4e7adba0029",
    "ContractValue": 1,
    "Gas": 3000000
}

应答与RPC部署合约一致，具体参考RPC部署合约。

调用合约

请求格式：

{
    "TransactionType": "Contract",
    "Account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "ContractOpType": 2,
    "ContractData": "0xc47f0027000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000047761776100000000000000000000000000000000000000000000000000000000",
    "Gas": 30000000,
    "ContractAddress": "zpzebvchnEafz5DDYzovuUsJeqy6mEoC5Q"
}

具体参考RPC调用合约。

查询类接口

查询类接口包含ChainSQL的查询类接口、chainsqld新增的数据库记录和信息查询接口、 智能合约查询接口。

ChainSQL查询接口

ChainSQL Websocket查询类接口有很多，下面展示一个示例。

查询账户信息

请求格式：

{
    "id": 2,
    "command": "account_info",
    "account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "strict": true,
    "ledger_index": "current",
    "queue": true
}

参数说明：

域	类型	描述
Account	字符串	必填，一个账户的唯一标识。
strict	布尔	可选，如果设置为True，Account这个域只能填写账户的公钥或者账户地址。
ledger_index	字符串或整形	可选，指定具体的账本进行查询。

应答格式：

{
    "id": 2,
    "result": {
        "account_data": {
            "Account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
            "Balance": "100000000",
            "Flags": 0,
            "LedgerEntryType": "AccountRoot",
            "OwnerCount": 0,
            "PreviousTxnID": "2A5573C42CA73036A57AD823ACC4F0359D335FF067D6232EAB919AC2C130866E",
            "PreviousTxnLgrSeq": 266,
            "Sequence": 1,
            "index": "68D7B391587F7FD814AE718F6BE298AACDB6662DFABF21A13FD163CF9E0C9C14"
        },
        "ledger_current_index": 614,
        "queue_data": {
            "txn_count": 0
        },
        "validated": false
    },
    "status": "success",
    "type": "response"
}

应答域说明：

域	类型	描述
account_data	对象	指定账本中的账户信息。
ledger_current_index	整形	接收到请求时的账本序列号。
status	字符串	指示查询请求查询成功或者失败。
validated	布尔	如果是True，表示返回的信息来自于已共识的账本，如果没有这个域或者值为False，则表示查询结果不是最终的结果。

数据库查询

数据库查询包含SQL数据操纵语句（DML）中的查操作和查询数据库表跟账户相关联的一些信息。

查询指定表中的数据记录，直接从本节点查询。

SQL语句查询

通过SQL语句直接查询的接口支持复杂查询，多表联合查询等。

为了区分权限，分为两个接口：

管理员接口：需要在节点配置文件中配置ip为admin，才可调用，不检查调用者身份。

普通用户接口：不需要配置admin，通过签名验证调用者身份。

请求格式：

admin接口：

{
    "command": "r_get_sql_admin",
    "sql": "select * from t_43ACD1FF143986210A44AB8B609371B392F45A86"
}

注解

SQL语句中的表名为数据库中的实际表名，需要先获取实际表名。

应答格式：

{
    "result": {
        "diff": 0,
        "lines": [
            {
                "age": 11,
                "first_name": "Peer",
                "full_name": "null",
                "id": 1
            },
            {
                "age": "null",
                "first_name": "Peer",
                "full_name": "Peer safe",
                "id": 2
            }
        ],
        "status": "success",
        "type":"response"
    }
}

应答域说明：

域	json类型	内部类型	描述
diff	整形	UInt32	当前区块序号与被查询表数据库同步到的区块序号的差值，如果有多个表，取最大差值。
lines	数组	Vector	查询的结果行。

普通接口请参看Java和Node.js接口说明。

查询实际表名

请求格式：

{
    "command": "g_dbname",
    "account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "tablename": "Table2"
}

参数说明：

域	json类型	内部类型	描述
account	字符串	AccountID	必填，表的创建者账户地址。
tablename	字符串	String	必填，创建表时，用户指定的表名。

应答格式：

{
    "result": {
        "nameInDB": "43ACD1FF143986210A44AB8B609371B392F45A86"
    },
    "status": "success",
    "type": "response"
}

应答域说明：

域	json类型	内部类型	描述
nameInDB	字符串	String	t_<nameInDB>组成数据库中的实际表名。
status	字符串	String	表示请求执行是否成功。

查询表的Token

获取账户对应表的Token。

请求格式：

{
    "command": "g_userToken",
    "tx_json": {
        "Owner": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
        "User": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
        "TableName": "Table2"
    }
}

参数说明：

域	json类型	内部类型	描述
Owner	字符串	String	必填，表的创建者账户地址。
User	字符串	String	必填，请求发起者账户地址。
TableName	字符串	String	必填，创建表时，用户指定的表名。

应答格式：

{
    "result": {
        "token": ""
    },
    "status": "success",
    "type": "response"
}

应答域说明：

域	json类型	内部类型	描述
token	字符串	String	16进制的密码的密文。
status	字符串	String	请求处理成功或者失败。成功可以返回空的Token，表示表未加密，或者返回非空的Token。 失败表示表加密了，但未对当前账户授权。
error_message	字符串	String	错误信息。如果处理成功了，则被省略。

查询操作权限

请求格式：

{
    "command": "table_auth",
    "owner": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "tablename": "Table2"
}

参数说明：

域	json类型	内部类型	描述
owner	字符串	String	必填，表的创建者账户地址。
tablename	字符串	String	必填，创建表时，用户指定的表名。

应答格式：

{
    "result": {
        "owner": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
        "tablename": "Table1",
        "users": [
            {
                "account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
                "authority": {
                    "delete": true,
                    "insert": true,
                    "select": true,
                    "update": true
                }
            }
        ]
    }
    "status": "success",
    "type":"response"
}

应答域说明：

域	json类型	内部类型	描述
status	字符串	String	表示请求执行是否成功。
authority	对象	Object	包含曾删改查等权限，true表示拥有权限，省略或false表示没有对应的操作权限。

智能合约查询

查询示例

请求格式：

{
    "command": "contract_call",
    "account": "zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh",
    "contract_data": "17d7de7c",
    "contract_address": "zpzebvchnEafz5DDYzovuUsJeqy6mEoC5Q"
}

具体参考RPC查询合约。

订阅类接口

订阅需要客户端与Chainsqld服务节点之间维持一个长连接，客户端与服务器建立连接后， 可以订阅表，也可以订阅交易。

订阅表

每当有修改已订阅表数据的交易，节点就会通过连接通道将交易发送给客户端。

请求格式：

{
    "id": "Example Subscribe a table",
    "command": "subscribe",
    "owner": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "tablename": "Table2"
}

参数说明：

域	类型	描述
id	字符串	对订阅的简要描述。
command	字符串	订阅请求（命令）名为 subscribe。
owner	字符串	必填，订阅表的所有者账户地址。
tablename	字符串	必填，建表时，用户指定的表名。

应答格式：

{
    "id": "Example Subscribe a table",
    "result": {},
    "status": "success",
    "type": "response"
}

订阅成功后每当有修改表数据的交易，节点就会通过通道将交易和交易状态的变化发送过来。

例如在已订阅的表中发送删除行请求，删除某一个行数据后，将收到如下消息：

{
    "owner": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "status": "validate_success",
    "tablename": "Table2",
    "transaction": {
        "Account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
        "Fee": "29330",
        "Flags": 2147483648,
        "LastLedgerSequence": 19579,
        "OpType": 9,
        "Owner": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
        "Raw": "5B0A2020207B0A20202020202022696422203A20330A2020207D0A5D0A",
        "Sequence": 3,
        "SigningPubKey": "027F92009A387B539099B0953DA21979CB002A9F142AA656E9AE5E263000040A43",
        "Tables": [
            {
                "Table": {
                    "NameInDB": "43ACD1FF143986210A44AB8B609371B392F45A86",
                    "TableName": "5461626C6532"
                }
            }
        ],
        "TransactionType": "SQLStatement",
        "TxnSignature": "3045022100DC1B1EB950A8EFC319296E2C6ABBF3D5E0D59369ADA05AAB176B8997E0939994022026850D33A21E64FD576108B33935B55348A153482210FA8E2157409CEBBB5FE8",
        "hash":"48DC88FE2A5293BB50286FB888BB84D7785E44557A37554292DE7B8F50E3F77C"
    },
    "type": "table"
}

{
    "owner": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
    "status": "db_success",
    "tablename": "Table2",
    "transaction": {
        "Account": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
        "Fee": "29330",
        "Flags": 2147483648,
        "LastLedgerSequence": 19579,
        "OpType": 9,
        "Owner": "zNRi42SAPegzJYzXYZfRFqPqUfGqKCaSbx",
        "Raw": "5B0A2020207B0A20202020202022696422203A20330A2020207D0A5D0A",
        "Sequence": 3,
        "SigningPubKey": "027F92009A387B539099B0953DA21979CB002A9F142AA656E9AE5E263000040A43",
        "Tables": [
            {
                "Table": {
                    "NameInDB": "43ACD1FF143986210A44AB8B609371B392F45A86",
                    "TableName": "5461626C6532"
                }
            }
        ],
        "TransactionType": "SQLStatement",
        "TxnSignature": "3045022100DC1B1EB950A8EFC319296E2C6ABBF3D5E0D59369ADA05AAB176B8997E0939994022026850D33A21E64FD576108B33935B55348A153482210FA8E2157409CEBBB5FE8",
        "hash": "48DC88FE2A5293BB50286FB888BB84D7785E44557A37554292DE7B8F50E3F77C"
    },
    "type": "table"
}

状态validate_success标识交易已共识成功， db_success标志数据库操作已成功。

订阅交易

订阅一个具体的交易，当交易的状态发生改变时，节点就会通过通道将交易的状态发送给客户端。

请求格式：

{
    "id": "Example Subscribe a Transaction",
    "command": "subscribe",
    "transaction": "C317EF68120210BC9035D4B7DEBC885F0210C12955621F700BB3C40C2EC5B651"
}

参数说明：

域	类型	描述
id	字符串	对订阅的简要描述。
command	字符串	订阅请求（命令）名为 subscribe。
transaction	字符串	交易的哈希，256位。

一般是在发送交易之前，先订阅这个即将要发送的交易。 这样能够监控到交易从提交到进入已验证账本过程中状态的变化。 需要事先计算交易的哈希，普通websocket客户端无法演示。 可以具体参考本文档中Java和Node.js接口部分。

应答格式同上。