Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update typedoc commments #104

Merged
merged 1 commit into from Aug 9, 2018
Merged

Update typedoc commments #104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
28 changes: 27 additions & 1 deletion src/core/Invoice.ts
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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 @@ -91,6 +114,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 @@ -106,14 +132,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 @@ -130,6 +167,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 @@ -145,6 +186,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 @@ -157,6 +203,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
Open in desktop
Expand Up @@ -24,6 +24,14 @@ export class AssetOutPoint {
readonly lockScriptHash?: H256;
readonly parameters?: Buffer[];

/**
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ScarletBlue

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A transaction hash that Asset is created at. -> The transaction hash where the Asset is created.
An index in the outputs of a transaction. -> The index in the output of the transaction.
An asset type of an asset that it points. -> The asset type of the asset that it points to.
Asset amount of an asset that it points. -> The Asset amount of the asset that it points to.
A lock script hash of an asset. -> The lock script hash of the asset.
Parameters of an asset. -> The parameters of the asset.

* @param data.transactionHash A transaction hash where the Asset is created.
* @param data.index The index in the output of the transaction.
* @param data.assetType The asset type of the asset that it points to.
* @param data.amount The asset amount of the asset that it points to.
* @param data.lockScriptHash The lock script hash of the asset.
* @param data.parameters The parameters of the 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