Skip to content

Commit

Permalink
Update typedoc commments
Browse files Browse the repository at this point in the history
  • Loading branch information
@joojis
joojis committed Aug 1, 2018
1 parent f2427d8 commit 539028e
Show file tree
Hide file tree
Showing 8 changed files with 318 additions and 38 deletions.
28 changes: 27 additions & 1 deletion src/core/Invoice.ts
View file
Expand Up @@ -3,23 +3,42 @@ import { Buffer } from "buffer";
const RLP = require("rlp");

/**
* Used to know whether a transaction succeeded or failed.
* An Invoice is used to know whether a transaction or a parcel succeeded or
* failed.
*/
export class Invoice {
readonly success: boolean;

/**
* @param success Whether a transaction or a parcel succeeded or failed.
*/
constructor(success: boolean) {
this.success = !!success;
}

// FIXME: any
/**
* Create an Invoice from an Invoice JSON object.
* @param data An Invoice JSON object.
* @returns An Invoice.
*/
static fromJSON(data: any) {
return new this(data === "Success");
}

/**
* Convert to an Invoice JSON object.
* @returns An Invoice JSON object.
*/
toJSON() {
return this.success ? "Success" : "Failed";
}

/**
* Decode RLP bytes to an Invoice.
* @param buffer RLP bytes.
* @returns An Invoice.
*/
static fromBytes(buffer: Buffer): Invoice {
const bytes = Array.from(buffer.values());
if (bytes.length !== 1 || bytes[0] > 0x01) {
Expand All @@ -28,10 +47,17 @@ export class Invoice {
return new Invoice(RLP.decode(buffer)[0]);
}

/**
* Convert to an object for RLP encoding.
*/
toEncodeObject(): boolean {
return this.success;
}

/**
* Convert to RLP bytes
* @returns RLP bytes
*/
rlpBytes(): Buffer {
return Buffer.from([this.toEncodeObject() ? 0x01 : 0x00]);
}
Expand Down
61 changes: 49 additions & 12 deletions src/core/SignedParcel.ts
View file
Expand Up @@ -12,25 +12,17 @@ const RLP = require("rlp");

/**
* A [Parcel](parcel.html) signed by a private key. It is possible to request
* processing on the CodeChain network with the
* the CodeChain network to process this parcel with the
* [sendSignedParcel](chainrpc.html#sendsignedparcel) function.
*
* Parcels signed with a regular key has the same effect as those signed with
* the original key. The original key is the key of the account that registered
* the regular key.
*
* If any of the following is true, the Parcel will not be processed:
* the Parcel's processing fee is less than 10, network ID is not identical, or
* the nonce is not identical.
*
* - When including a Payment transaction, the payment's sender and the parcel's
* signer must be identical.
* - When including a SetRegularKey transaction, the transaction's address and
* the parcel's signer must be identical.
* - If the asset type that is being transferred from AssetTransferTransaction
* has a registrar, the registrar must be identical to the parcel's signer.
* If any of the transactions above have an invalid signer for any of the
* conditions, then individual transactions will fail.
* - The Parcel's processing fee is less than 10.
* - A network ID is not identical.
* - A nonce is not identical to the signer's nonce.
*/
export class SignedParcel {
unsigned: Parcel;
Expand All @@ -41,6 +33,13 @@ export class SignedParcel {
blockHash: H256 | null;
parcelIndex: number | null;

/**
* @param unsigned A Parcel.
* @param sig An ECDSA signature which is a 65 byte hexadecimal string.
* @param blockNumber The block number of the block that contains the parcel.
* @param blockHash The hash of the block that contains the parcel.
* @param parcelIndex The index(location) of the parcel within the block.
*/
constructor(unsigned: Parcel, sig: string, blockNumber?: number, blockHash?: H256, parcelIndex?: number) {
this.unsigned = unsigned;
const { r, s, v } = SignedParcel.convertSignatureStringToRsv(sig);
Expand All @@ -52,11 +51,17 @@ export class SignedParcel {
this.parcelIndex = parcelIndex === undefined ? null : parcelIndex;
}

/**
* Get the signature of a parcel.
*/
signature() {
const { v, r, s } = this;
return { v, r, s };
}

/**
* Convert to an object for RLP encoding.
*/
toEncodeObject(): Array<any> {
const { unsigned: { nonce, fee, action, networkId }, v, r, s } = this;
const sig = `0x${_.padStart(r.value.toString(16), 64, "0")}${_.padStart(s.value.toString(16), 64, "0")}${_.padStart(v.toString(16), 2, "0")}`;
Expand All @@ -72,14 +77,25 @@ export class SignedParcel {
];
}

/**
* Convert to RLP bytes.
*/
rlpBytes(): Buffer {
return RLP.encode(this.toEncodeObject());
}

/**
* Get the hash of a parcel.
* @returns A parcel hash.
*/
hash(): H256 {
return new H256(blake256(this.rlpBytes()));
}

/**
* Get the account ID of a parcel's signer.
* @returns An account ID.
*/
getSignerAccountId(): H160 {
const { r, s, v, unsigned } = this;
const publicKey = recoverEcdsa(unsigned.hash().value, {
Expand All @@ -90,10 +106,20 @@ export class SignedParcel {
return new H160(ripemd160(blake256(publicKey)));
}

/**
* Get the platform address of a parcel's signer.
* @returns A PlatformAddress.
*/
getSignerAddress(): PlatformAddress {
return PlatformAddress.fromAccountId(this.getSignerAccountId());
}

// FIXME: any
/**
* Create a SignedParcel from a SignedParcel JSON object.
* @param data A SignedParcel JSON object.
* @returns A SignedParcel.
*/
static fromJSON(data: any) {
const { sig, blockNumber, blockHash, parcelIndex } = data;
if (typeof sig !== "string") {
Expand All @@ -106,6 +132,10 @@ export class SignedParcel {
}
}

/**
* Convert to a SignedParcel JSON object.
* @returns A SignedParcel JSON object.
*/
toJSON() {
const { blockNumber, blockHash, parcelIndex,
unsigned: { nonce, fee, networkId, action }, v, r, s } = this;
Expand Down Expand Up @@ -137,6 +167,13 @@ export class SignedParcel {
return { r, s, v };
}

/**
* Convert r, s, v values of an ECDSA signature to a string.
* @param params.r The r value of an ECDSA signature, which is up to 32 bytes of hexadecimal string.
* @param params.s The s value of an ECDSA signature, which is up to 32 bytes of hexadecimal string.
* @param params.v The recovery parameter of an ECDSA signature.
* @returns A 65 byte hexadecimal string.
*/
static convertRsvToSignatureString(params: { r: string, s: string, v: number }) {
const { r, s, v } = params;
return `0x${_.padStart(r, 64, "0")}${_.padStart(s, 64, "0")}${_.padStart(v.toString(16), 2, "0")}`;
Expand Down
66 changes: 58 additions & 8 deletions src/core/transaction/AssetMintTransaction.ts
View file
Expand Up @@ -26,12 +26,16 @@ export type AssetMintTransactionData = {
/**
* Creates a new asset type and that asset itself.
*
* The owner of the new asset created can be assigned by lockScriptHash and parameters.
* - metadata is a string that explains the asset's type.
* - amount defines the quantity of asset to be created. If set as null, it will be set as the maximum value of a 64-bit unsigned integer by default.
* - If registrar exists, the registrar must be the Signer of the Parcel when sending the created asset through AssetTransferTransaction.
* - Transaction hash can be changed by changing nonce.
* - If an identical transaction hash already exists, then the change fails. In this situation, a transaction can be created again by arbitrarily changing the nonce.
* The owner of the new asset created can be assigned by a lock script hash and parameters.
* - A metadata is a string that explains the asset's type.
* - Amount defines the quantity of asset to be created. If set as null, it
* will be set as the maximum value of a 64-bit unsigned integer by default.
* - If registrar exists, the registrar must be the Signer of the Parcel when
* sending the created asset through AssetTransferTransaction.
* - A transaction hash can be changed by changing nonce.
* - If an identical transaction hash already exists, then the change fails. In
* this situation, a transaction can be created again by arbitrarily changing
* the nonce.
*/
export class AssetMintTransaction {
readonly networkId: number;
Expand All @@ -46,6 +50,16 @@ export class AssetMintTransaction {
readonly nonce: number;
readonly type = "assetMint";

/**
* @param data.networkId A network ID of the transaction.
* @param data.shardId A shard ID of the transaction.
* @param data.metadata A metadata of the asset.
* @param data.output.lockScriptHash A lock script hash of the output.
* @param data.output.parameters Parameters of the output.
* @param data.output.amount Asset amount of the output.
* @param data.registrar A registrar of the asset.
* @param data.nonce A nonce of the transaction.
*/
constructor(data: AssetMintTransactionData) {
const { networkId, shardId, metadata, output, registrar, nonce } = data;
this.networkId = networkId;
Expand All @@ -56,8 +70,13 @@ export class AssetMintTransaction {
this.nonce = nonce;
}

static fromJSON(obj: any) {
const { data: { networkId, shardId, metadata, output: { lockScriptHash, parameters, amount }, registrar, nonce } } = obj;
/**
* Create an AssetMintTransaction from an AssetMintTransaction JSON object.
* @param data An AssetMintTransaction JSON object.
* @returns An AssetMintTransaction.
*/
static fromJSON(data: any) {
const { data: { networkId, shardId, metadata, output: { lockScriptHash, parameters, amount }, registrar, nonce } } = data;
return new this({
networkId,
shardId,
Expand All @@ -72,6 +91,10 @@ export class AssetMintTransaction {
});
}

/**
* Convert to an AssetMintTransaction JSON object.
* @returns An AssetMintTransaction JSON object.
*/
toJSON() {
const { networkId, shardId, metadata, output: { lockScriptHash, parameters, amount }, registrar, nonce } = this;
return {
Expand All @@ -92,6 +115,9 @@ export class AssetMintTransaction {
};
}

/**
* Convert to an object for RLP encoding.
*/
toEncodeObject() {
const { networkId, shardId, metadata, output: { lockScriptHash, parameters, amount }, registrar, nonce } = this;
return [
Expand All @@ -107,14 +133,25 @@ export class AssetMintTransaction {
];
}

/**
* Convert to RLP bytes.
*/
rlpBytes(): Buffer {
return RLP.encode(this.toEncodeObject());
}

/**
* Get the hash of an AssetMintTransaction.
* @returns A transaction hash.
*/
hash(): H256 {
return new H256(blake256(this.rlpBytes()));
}

/**
* Get the output of this transaction.
* @returns An Asset.
*/
getMintedAsset(): Asset {
const { lockScriptHash, parameters, amount } = this.output;
// FIXME: need U64 to be implemented or use U256
Expand All @@ -131,6 +168,10 @@ export class AssetMintTransaction {
});
}

/**
* Get the asset scheme of this transaction.
* @return An AssetScheme.
*/
getAssetScheme(): AssetScheme {
const { networkId, shardId, metadata, output: { amount }, registrar } = this;
// FIXME: need U64 to be implemented or use U256
Expand All @@ -146,6 +187,11 @@ export class AssetMintTransaction {
});
}

/**
* Get the address of the asset scheme. An asset scheme address equals to an
* asset type value.
* @returns An asset scheme address which is H256.
*/
getAssetSchemeAddress(): H256 {
const { shardId } = this;
const blake = blake256WithKey(this.hash().value, new Uint8Array([
Expand All @@ -158,6 +204,10 @@ export class AssetMintTransaction {
return new H256(blake.replace(new RegExp(`^.{${prefix.length}}`), prefix));
}

/**
* Get the asset address of the output.
* @returns An asset address which is H256.
*/
getAssetAddress(): H256 {
const { shardId } = this;
const blake = blake256WithKey(this.hash().value, new Uint8Array([
Expand Down
20 changes: 20 additions & 0 deletions src/core/transaction/AssetOutPoint.ts
View file
Expand Up @@ -24,6 +24,14 @@ export class AssetOutPoint {
readonly lockScriptHash?: H256;
readonly parameters?: Buffer[];

/**
* @param data.transactionHash A transaction hash that Asset is created at.
* @param data.index An index in the outputs of a transaction.
* @param data.assetType An asset type of an asset that it points.
* @param data.amount Asset amount of an asset that it points.
* @param data.lockScriptHash A lock script hash of an asset.
* @param data.parameters Parameters of an asset.
*/
constructor(data: AssetOutPointData) {
const { transactionHash, index, assetType, amount, lockScriptHash, parameters } = data;
this.transactionHash = transactionHash;
Expand All @@ -34,11 +42,19 @@ export class AssetOutPoint {
this.parameters = parameters;
}

/**
* Convert to an object for RLP encoding.
*/
toEncodeObject() {
const { transactionHash, index, assetType, amount } = this;
return [transactionHash.toEncodeObject(), index, assetType.toEncodeObject(), amount];
}

/**
* Create an AssetOutPoint from an AssetOutPoint JSON object.
* @param data An AssetOutPoint JSON object.
* @returns An AssetOutPoint.
*/
static fromJSON(data: any) {
const { transactionHash, index, assetType, amount } = data;
return new this({
Expand All @@ -49,6 +65,10 @@ export class AssetOutPoint {
});
}

/**
* Convert to an AssetOutPoint JSON object.
* @returns An AssetOutPoint JSON object.
*/
toJSON() {
const { transactionHash, index, assetType, amount } = this;
return {
Expand Down

0 comments on commit 539028e

Please sign in to comment.