From dea61ddb4b29a7ff42a64d0378e28227bf38f985 Mon Sep 17 00:00:00 2001 From: Howard Yeh Date: Tue, 9 Jan 2018 15:19:13 +0800 Subject: [PATCH] tweak type names --- src/Contract.ts | 102 ++++++++++++++++++++++++++++++++++-------------- src/QtumRPC.ts | 3 ++ src/abi.ts | 11 +++++- 3 files changed, 85 insertions(+), 31 deletions(-) diff --git a/src/Contract.ts b/src/Contract.ts index d27dadc..3ddc347 100644 --- a/src/Contract.ts +++ b/src/Contract.ts @@ -35,40 +35,59 @@ export interface IContractSendTx { txid: string } -export type IContractSendTxConfirmationHandler = ( +/** + * The callback function invoked for each additional confirmation + */ +export type IContractSendConfirmationHandler = ( tx: IRPCGetTransactionResult, - receipt: IContractSendTxReceipt, + receipt: IContractSendReceipt, ) => any -export type IContractSendTxConfirmFunction = (n?: number, handler?: IContractSendTxConfirmationHandler) => any +/** + * @param n Number of confirmations to wait for + * @param handler The callback function invoked for each additional confirmation + */ +export type IContractSendConfirmFunction = (n?: number, handler?: IContractSendConfirmationHandler) => any -export interface IContractSendTxConfirmable extends IRPCGetTransactionResult { +/** + * Result of contract send. + */ +export interface IContractSendResult extends IRPCGetTransactionResult { + /** + * Name of contract method invoked. + */ method: string - confirm: IContractSendTxConfirmFunction, + + /** + * Wait for transaction confirmations. + */ + confirm: IContractSendConfirmFunction, } +/** + * The minimal deployment information necessary to interact with a + * deployed contract. + */ export interface IContractInfo { /** - * Contract ABI methods + * Contract's ABI definitions */ abi: IABIMethod[] + /** - * Address of contract + * Contract's address */ address: string - // name: string - // deployName: string - // txid: string - // bin: string - // binhash: string - // createdAt: string // date string - // confirmed: boolean - + /** + * The owner address of the contract + */ sender?: string } -// IDeployedContractInfo has extra deployment information stored by solar +/** + * Deployment information stored by solar + */ export interface IDeployedContractInfo extends IContractInfo { name: string deployName: string @@ -79,11 +98,16 @@ export interface IDeployedContractInfo extends IContractInfo { confirmed: boolean } -export interface IContractCallDecodedResult extends IRPCCallContractResult { +/** + * The result of calling a contract method, with decoded outputs. + */ +export interface IContractCallResult extends IRPCCallContractResult { outputs: any[] - // [key: number]: any } +/** + * Options for `send` to a contract method. + */ export interface IContractSendRequestOptions { /** * The amount in QTUM to send. eg 0.1, default: 0 @@ -106,6 +130,9 @@ export interface IContractSendRequestOptions { senderAddress?: string } +/** + * Options for `call` to a contract method. + */ export interface IContractCallRequestOptions { /** * The quantum address that will be used as sender. @@ -113,7 +140,10 @@ export interface IContractCallRequestOptions { senderAddress?: string } -export interface IContractSendTxReceipt extends IRPCGetTransactionReceiptBase { +/** + * The transaction receipt for a `send` to a contract method, with the event logs decoded. + */ +export interface IContractSendReceipt extends IRPCGetTransactionReceiptBase { /** * logs decoded using ABI */ @@ -139,14 +169,28 @@ export interface IContractLogs { nextblock: number, } +/** + * Contract represents a Smart Contract deployed on the blockchain. + */ export class Contract { - // private abi: IABI[] + /** + * The contract's address as hex160 + */ public address: string + private callMethodsMap: { [key: string]: IABIMethod } = {} private sendMethodsMap: { [key: string]: IABIMethod } = {} private _logDecoder: ContractLogDecoder + /** + * Create a Contract + * + * @param rpc - The RPC object used to access the blockchain. + * @param info - The deployment information about this contract generated by + * [solar](https://github.com/qtumproject/solar). It includes the contract + * address, owner address, and ABI definition for methods and types. + */ constructor(private rpc: QtumRPC, public info: IContractInfo) { for (const methodABI of info.abi) { const name = methodABI.name @@ -201,7 +245,7 @@ export class Contract { method: string, args: any[] = [], opts: IContractCallRequestOptions = {}): - Promise { + Promise { // TODO support the named return values mechanism for decodeParams const r = await this.rawCall(method, args, opts) @@ -255,8 +299,8 @@ export class Contract { public async confirm( tx: IContractSendTx, confirm?: number, - onConfirm?: IContractSendTxConfirmationHandler, - ): Promise { + onConfirm?: IContractSendConfirmationHandler, + ): Promise { const txrp = new TxReceiptPromise(this.rpc, tx.txid) if (onConfirm) { @@ -275,7 +319,7 @@ export class Contract { method: string, args: any[], opts: IContractSendRequestOptions = {}, - ): Promise { + ): Promise { const methodABI = this.sendMethodsMap[method] if (methodABI == null) { @@ -293,12 +337,12 @@ export class Contract { const txid = sent.txid - const txinfo = await this.rpc.getTransaction({txid}) + const txinfo = await this.rpc.getTransaction({ txid }) const sendTx = { ...txinfo, method, - confirm: (n?: number, handler?: IContractSendTxConfirmationHandler) => { + confirm: (n?: number, handler?: IContractSendConfirmationHandler) => { return this.confirm(sendTx, n, handler) }, } @@ -322,7 +366,7 @@ export class Contract { return { ...entry, event: parsedLog, - } + } }) return { @@ -390,10 +434,10 @@ export class Contract { return this._logDecoder } - private _makeSendTxReceipt(receipt: IRPCGetTransactionReceiptResult): IContractSendTxReceipt { + private _makeSendTxReceipt(receipt: IRPCGetTransactionReceiptResult): IContractSendReceipt { // https://stackoverflow.com/a/34710102 // ...receiptNoLog will be a copy of receipt, without the `log` property - const {log: rawlogs, ...receiptNoLog} = receipt + const { log: rawlogs, ...receiptNoLog } = receipt const logs = decodeLogs(this.info.abi, rawlogs) return { diff --git a/src/QtumRPC.ts b/src/QtumRPC.ts index a8e8fb3..ac862d6 100644 --- a/src/QtumRPC.ts +++ b/src/QtumRPC.ts @@ -133,6 +133,9 @@ export interface IRPCGetTransactionRequest { waitconf?: number } +/** + * Basic information about a transaction submitted to the network. + */ export interface IRPCGetTransactionResult { amount: number, fee: number, diff --git a/src/abi.ts b/src/abi.ts index 7bfb649..90d3863 100644 --- a/src/abi.ts +++ b/src/abi.ts @@ -56,11 +56,18 @@ export function decodeOutputs(method: IABIMethod, outputData: string): any[] { return values } +/** + * A decoded Solidity event log + */ export interface IDecodedLog { - // type is a reserved keyword in Solidity, so we can expect it - // to be unused as an event parameter name + /** + * The event log's name + */ type: string + /** + * Arguments to event log as key-value map + */ [key: string]: any }