casper-js-sdk
Version:
SDK to interact with the Casper blockchain
660 lines (659 loc) • 23.4 kB
TypeScript
import { BigNumber, BigNumberish } from '@ethersproject/bignumber';
import { InitiatorAddr } from './InitiatorAddr';
import { PricingMode } from './PricingMode';
import { TransactionTarget } from './TransactionTarget';
import { TransactionEntryPoint } from './TransactionEntryPoint';
import { TransactionScheduling } from './TransactionScheduling';
import { Args } from './Args';
import { PublicKey } from './keypair';
import { AccountHash } from './key';
import { Transaction } from './Transaction';
import { Duration, Timestamp } from './Time';
import { ExecutableDeployItem } from './ExecutableDeployItem';
import { DeployHeader } from './Deploy';
/**
* Abstract base class for building Transaction V1 instances.
* Provides common functionality for all transaction builders including
* initiator management, chain configuration, timing, and payment settings.
*
* @template T - The concrete builder type that extends this class
*/
declare abstract class TransactionBuilder<T extends TransactionBuilder<T>> {
protected _initiatorAddr: InitiatorAddr;
protected _chainName: string;
protected _timestamp: Timestamp;
protected _ttl: Duration;
protected _pricingMode: PricingMode;
protected _invocationTarget: TransactionTarget;
protected _entryPoint: TransactionEntryPoint;
protected _scheduling: TransactionScheduling;
protected _runtimeArgs: Args;
protected _contractHash: string;
/**
* Sets the initiator address using a public key.
*
* @param publicKey - The public key of the transaction initiator
* @returns The builder instance for method chaining
*/
from(publicKey: PublicKey): T;
/**
* Sets the initiator address using an account hash.
*
* @param accountHashKey - The account hash of the transaction initiator
* @returns The builder instance for method chaining
*/
fromAccountHash(accountHashKey: AccountHash): T;
/**
* Sets the chain name for the transaction.
*
* @param chainName - The name of the Casper network chain (e.g., 'casper-test', 'casper')
* @returns The builder instance for method chaining
*/
chainName(chainName: string): T;
/**
* Sets the contract hash for the transaction.
*
* @param contractHash - The contract hash in hexadecimal format
* @returns The builder instance for method chaining
*/
contractHash(contractHash: string): T;
/**
* Sets the timestamp for the transaction.
*
* @param timestamp - The transaction timestamp
* @returns The builder instance for method chaining
*/
timestamp(timestamp: Timestamp): T;
/**
* Sets the time-to-live for the transaction.
*
* @param ttl - Time-to-live in milliseconds (default: 1800000ms = 30 minutes)
* @returns The builder instance for method chaining
*/
ttl(ttl: number): T;
/**
* Sets the payment amount for the transaction using a limited payment mode.
*
* @param paymentAmount - The payment amount in motes
* @param gasPriceTolerance - Gas price tolerance multiplier (default: 1)
* @returns The builder instance for method chaining
*/
payment(paymentAmount: number, gasPriceTolerance?: number): T;
/**
* Creates a default deploy header with the configured transaction settings.
*
* @returns A deploy header with account, chain name, timestamp, TTL, and gas price
* @protected
*/
protected _getDefaultDeployHeader(): DeployHeader;
/**
* Creates a standard payment executable deploy item.
*
* @returns An executable deploy item configured for standard payment
* @throws {Error} If payment amount is not specified
* @protected
*/
protected _getStandardPayment(): ExecutableDeployItem;
/**
* Builds and returns the Transaction instance.
*
* @returns A complete Transaction object ready to be signed and submitted
*/
build(): Transaction;
}
/**
* Builder for creating Native Transfer transactions.
* Enables transferring CSPR tokens from one account to another on the Casper network.
*
* @example
* ```typescript
* const transaction = new NativeTransferBuilder()
* .from(senderPublicKey)
* .target(recipientPublicKey)
* .amount('2500000000') // 2.5 CSPR in motes
* .id(Date.now())
* .chainName('casper-test')
* .payment(100_000_000)
* .build();
* ```
*/
export declare class NativeTransferBuilder extends TransactionBuilder<NativeTransferBuilder> {
private _target;
private _publicKey;
private _amount;
private _amountRow;
private _idTransfer?;
constructor();
/**
* Sets the target public key for the transfer.
*
* @param publicKey - The recipient's public key
* @returns The builder instance for method chaining
*/
target(publicKey: PublicKey): NativeTransferBuilder;
/**
* Sets the target account hash for the transfer.
*
* @param accountHashKey - The recipient's account hash
* @returns The builder instance for method chaining
*/
targetAccountHash(accountHashKey: AccountHash): NativeTransferBuilder;
/**
* Sets the amount to transfer in motes.
*
* @param amount - The transfer amount (1 CSPR = 1,000,000,000 motes)
* @returns The builder instance for method chaining
*/
amount(amount: BigNumber | string): NativeTransferBuilder;
/**
* Sets the transfer ID for tracking purposes.
*
* @param id - A unique identifier for this transfer
* @returns The builder instance for method chaining
*/
id(id: number): NativeTransferBuilder;
/**
* Builds and returns the Native Transfer transaction for Casper 2.0+.
*
* @returns A complete Transaction object ready to be signed and submitted
*/
build(): Transaction;
/**
* Builds and returns the Native Transfer transaction for Casper 1.5.
* Uses the legacy deploy format for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
*/
buildFor1_5(): Transaction;
}
/**
* Builder for creating Native Add Bid transactions.
* Used by validators to submit or increase their bid in the Casper auction system.
*
* @example
* ```typescript
* const transaction = new NativeAddBidBuilder()
* .from(validatorPublicKey)
* .validator(validatorPublicKey)
* .amount('1000000000000') // 1000 CSPR
* .delegationRate(10) // 10% commission
* .chainName('casper')
* .payment(5_000_000_000)
* .build();
* ```
*/
export declare class NativeAddBidBuilder extends TransactionBuilder<NativeAddBidBuilder> {
private _validator;
private _amount;
private _delegationRate;
private _minimumDelegationAmount?;
private _maximumDelegationAmount?;
private _reservedSlots?;
constructor();
/**
* Sets the validator's public key for the bid.
*
* @param publicKey - The validator's public key
* @returns The builder instance for method chaining
*/
validator(publicKey: PublicKey): NativeAddBidBuilder;
/**
* Sets the bid amount in motes.
*
* @param amount - The bid amount (minimum varies by network)
* @returns The builder instance for method chaining
*/
amount(amount: BigNumber | string): NativeAddBidBuilder;
/**
* Sets the delegation rate (commission percentage).
*
* @param delegationRate - Commission rate as a percentage (0-100)
* @returns The builder instance for method chaining
*/
delegationRate(delegationRate: number): NativeAddBidBuilder;
/**
* Sets the minimum delegation amount for delegators.
*
* @param minimumDelegationAmount - Minimum amount delegators can stake
* @returns The builder instance for method chaining
*/
minimumDelegationAmount(minimumDelegationAmount: BigNumberish): NativeAddBidBuilder;
/**
* Sets the maximum delegation amount for delegators.
*
* @param maximumDelegationAmount - Maximum amount delegators can stake
* @returns The builder instance for method chaining
*/
maximumDelegationAmount(maximumDelegationAmount: BigNumberish): NativeAddBidBuilder;
/**
* Sets the number of reserved delegation slots.
*
* @param reservedSlots - Number of slots reserved for specific delegators
* @returns The builder instance for method chaining
*/
reservedSlots(reservedSlots: BigNumber): NativeAddBidBuilder;
/**
* Builds and returns the Add Bid transaction for Casper 2.0+.
*
* @returns A complete Transaction object ready to be signed and submitted
*/
build(): Transaction;
/**
* Builds and returns the Add Bid transaction for Casper 1.5.
* Uses the auction manager contract for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
* @throws {Error} If initiator address or contract hash is not specified
*/
buildFor1_5(): Transaction;
}
/**
* Builder for creating Native Withdraw Bid transactions.
* Used by validators to withdraw or reduce their bid in the Casper auction system.
*
* @example
* ```typescript
* const transaction = new NativeWithdrawBidBuilder()
* .from(validatorPublicKey)
* .validator(validatorPublicKey)
* .amount('500000000000') // 500 CSPR
* .chainName('casper')
* .payment(2_500_000_000)
* .build();
* ```
*/
export declare class NativeWithdrawBidBuilder extends TransactionBuilder<NativeWithdrawBidBuilder> {
private _validator;
private _amount;
constructor();
/**
* Sets the validator's public key for the withdrawal.
*
* @param publicKey - The validator's public key
* @returns The builder instance for method chaining
*/
validator(publicKey: PublicKey): NativeWithdrawBidBuilder;
/**
* Sets the amount to withdraw in motes.
*
* @param amount - The withdrawal amount
* @returns The builder instance for method chaining
*/
amount(amount: BigNumber | string): NativeWithdrawBidBuilder;
/**
* Builds and returns the Withdraw Bid transaction for Casper 2.0+.
*
* @returns A complete Transaction object ready to be signed and submitted
*/
build(): Transaction;
/**
* Builds and returns the Withdraw Bid transaction for Casper 1.5.
* Uses the auction manager contract for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
* @throws {Error} If contract hash cannot be determined
*/
buildFor1_5(): Transaction;
}
/**
* Builder for creating Native Delegate transactions.
* Allows accounts to delegate their CSPR tokens to a validator for staking.
*
* @example
* ```typescript
* const transaction = new NativeDelegateBuilder()
* .from(delegatorPublicKey)
* .validator(validatorPublicKey)
* .amount('500000000000') // 500 CSPR
* .chainName('casper')
* .payment(2_500_000_000)
* .build();
* ```
*/
export declare class NativeDelegateBuilder extends TransactionBuilder<NativeDelegateBuilder> {
private _validator;
private _amount;
constructor();
/**
* Sets the validator's public key to delegate to.
*
* @param publicKey - The validator's public key
* @returns The builder instance for method chaining
*/
validator(publicKey: PublicKey): NativeDelegateBuilder;
/**
* Sets the amount to delegate in motes.
*
* @param amount - The delegation amount (minimum varies by network)
* @returns The builder instance for method chaining
*/
amount(amount: BigNumber | string): NativeDelegateBuilder;
/**
* Builds and returns the Delegate transaction for Casper 2.0+.
*
* @returns A complete Transaction object ready to be signed and submitted
* @throws {Error} If initiator address is not specified
*/
build(): Transaction;
/**
* Builds and returns the Delegate transaction for Casper 1.5.
* Uses the auction manager contract for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
* @throws {Error} If initiator address or contract hash is not specified
*/
buildFor1_5(): Transaction;
}
/**
* Builder for creating Native Undelegate transactions.
* Allows accounts to undelegate their staked CSPR tokens from a validator.
*
* @example
* ```typescript
* const transaction = new NativeUndelegateBuilder()
* .from(delegatorPublicKey)
* .validator(validatorPublicKey)
* .amount('250000000000') // 250 CSPR
* .chainName('casper')
* .payment(2_500_000_000)
* .build();
* ```
*/
export declare class NativeUndelegateBuilder extends TransactionBuilder<NativeUndelegateBuilder> {
private _validator;
private _amount;
constructor();
/**
* Sets the validator's public key to undelegate from.
*
* @param publicKey - The validator's public key
* @returns The builder instance for method chaining
*/
validator(publicKey: PublicKey): NativeUndelegateBuilder;
/**
* Sets the amount to undelegate in motes.
*
* @param amount - The undelegation amount
* @returns The builder instance for method chaining
*/
amount(amount: BigNumber | string): NativeUndelegateBuilder;
/**
* Builds and returns the Undelegate transaction for Casper 2.0+.
*
* @returns A complete Transaction object ready to be signed and submitted
* @throws {Error} If initiator address is not specified
*/
build(): Transaction;
/**
* Builds and returns the Undelegate transaction for Casper 1.5.
* Uses the auction manager contract for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
* @throws {Error} If initiator address or contract hash is not specified
*/
buildFor1_5(): Transaction;
}
/**
* Builder for creating Native Redelegate transactions.
* Allows accounts to move their delegated stake from one validator to another
* without waiting for the undelegation period.
*
* @example
* ```typescript
* const transaction = new NativeRedelegateBuilder()
* .from(delegatorPublicKey)
* .validator(oldValidatorPublicKey)
* .newValidator(newValidatorPublicKey)
* .amount('500000000000') // 500 CSPR
* .chainName('casper')
* .payment(2_500_000_000)
* .build();
* ```
*/
export declare class NativeRedelegateBuilder extends TransactionBuilder<NativeRedelegateBuilder> {
private _validator;
private _newValidator;
private _amount;
constructor();
/**
* Sets the current validator's public key (the validator to redelegate from).
*
* @param publicKey - The current validator's public key
* @returns The builder instance for method chaining
*/
validator(publicKey: PublicKey): NativeRedelegateBuilder;
/**
* Sets the new validator's public key (the validator to redelegate to).
*
* @param publicKey - The new validator's public key
* @returns The builder instance for method chaining
*/
newValidator(publicKey: PublicKey): NativeRedelegateBuilder;
/**
* Sets the amount to redelegate in motes.
*
* @param amount - The redelegation amount
* @returns The builder instance for method chaining
*/
amount(amount: BigNumber | string): NativeRedelegateBuilder;
/**
* Builds and returns the Redelegate transaction for Casper 2.0+.
*
* @returns A complete Transaction object ready to be signed and submitted
* @throws {Error} If initiator address is not specified
*/
build(): Transaction;
/**
* Builds and returns the Redelegate transaction for Casper 1.5.
* Uses the auction manager contract for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
* @throws {Error} If initiator address or contract hash is not specified
*/
buildFor1_5(): Transaction;
}
/**
* Builder for creating Native Activate Bid transactions.
* Used by validators to activate their bid after it has been deactivated.
*
* @example
* ```typescript
* const transaction = new NativeActivateBidBuilder()
* .from(validatorPublicKey)
* .validator(validatorPublicKey)
* .chainName('casper')
* .payment(2_500_000_000)
* .build();
* ```
*/
export declare class NativeActivateBidBuilder extends TransactionBuilder<NativeActivateBidBuilder> {
private _validator;
constructor();
/**
* Sets the validator's public key to activate.
*
* @param publicKey - The validator's public key
* @returns The builder instance for method chaining
*/
validator(publicKey: PublicKey): NativeActivateBidBuilder;
/**
* Builds and returns the Activate Bid transaction for Casper 2.0+.
*
* @returns A complete Transaction object ready to be signed and submitted
*/
build(): Transaction;
/**
* Builds and returns the Activate Bid transaction for Casper 1.5.
* Uses the auction manager contract for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
* @throws {Error} If contract hash cannot be determined
*/
buildFor1_5(): Transaction;
}
/**
* Builder for creating Native Change Bid Public Key transactions.
* Allows validators to change their public key while maintaining their bid.
*
* @example
* ```typescript
* const transaction = new NativeChangeBidPublicKeyBuilder()
* .from(validatorPublicKey)
* .previousPublicKey(oldPublicKey)
* .newPublicKey(newPublicKey)
* .chainName('casper')
* .payment(2_500_000_000)
* .build();
* ```
*/
export declare class NativeChangeBidPublicKeyBuilder extends TransactionBuilder<NativeChangeBidPublicKeyBuilder> {
private _public_key;
private _new_public_key;
constructor();
/**
* Sets the previous (current) public key of the validator.
*
* @param publicKey - The validator's current public key
* @returns The builder instance for method chaining
*/
previousPublicKey(publicKey: PublicKey): NativeChangeBidPublicKeyBuilder;
/**
* Sets the new public key for the validator.
*
* @param publicKey - The validator's new public key
* @returns The builder instance for method chaining
*/
newPublicKey(publicKey: PublicKey): NativeChangeBidPublicKeyBuilder;
/**
* Builds and returns the Change Bid Public Key transaction for Casper 2.0+.
*
* @returns A complete Transaction object ready to be signed and submitted
*/
build(): Transaction;
}
/**
* Builder for creating Contract Call transactions.
* Enables calling entry points on deployed smart contracts.
* Supports multiple addressing modes: by hash, by name, by package hash, and by package name.
*
* @example
* ```typescript
* const transaction = new ContractCallBuilder()
* .from(callerPublicKey)
* .byHash(contractHash)
* .entryPoint('transfer')
* .runtimeArgs(args)
* .chainName('casper')
* .payment(3_000_000_000)
* .build();
* ```
*/
export declare class ContractCallBuilder extends TransactionBuilder<ContractCallBuilder> {
constructor();
private _transactionInvocationTarget;
/**
* Sets the contract to call using its hash.
*
* @param contractHash - The contract hash in hexadecimal format
* @returns The builder instance for method chaining
*/
byHash(contractHash: string): ContractCallBuilder;
/**
* Sets the contract to call using its name.
*
* @param name - The named key under which the contract is stored
* @returns The builder instance for method chaining
*/
byName(name: string): ContractCallBuilder;
/**
* Sets the contract to call using its package hash and optional version.
*
* @param contractHash - The contract package hash in hexadecimal format
* @param version - Optional specific version of the contract to call
* @param protocolVersionMajor - Optional protocol version major number
* @returns The builder instance for method chaining
*/
byPackageHash(contractHash: string, version?: number, protocolVersionMajor?: number | null): ContractCallBuilder;
/**
* Sets the contract to call using its package name and optional version.
*
* @param name - The package name under which the contract is stored
* @param version - Optional specific version of the contract to call
* @param protocolVersionMajor - Optional protocol version major number
* @returns The builder instance for method chaining
*/
byPackageName(name: string, version?: number, protocolVersionMajor?: number | null): ContractCallBuilder;
/**
* Sets the entry point name to call on the contract.
*
* @param name - The name of the contract entry point
* @returns The builder instance for method chaining
*/
entryPoint(name: string): ContractCallBuilder;
/**
* Sets the runtime arguments to pass to the contract entry point.
*
* @param args - The arguments to pass to the contract
* @returns The builder instance for method chaining
*/
runtimeArgs(args: Args): ContractCallBuilder;
/**
* Builds and returns the Contract Call transaction for Casper 1.5.
* Uses the legacy deploy format for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
* @throws {Error} If entry point is not specified
*/
buildFor1_5(): Transaction;
}
/**
* Builder for creating Session transactions.
* Used to deploy new smart contracts or upgrade existing ones from WebAssembly bytecode.
*
* @example
* ```typescript
* const wasmBytes = await fs.readFile('contract.wasm');
* const transaction = new SessionBuilder()
* .from(deployerPublicKey)
* .wasm(wasmBytes)
* .installOrUpgrade()
* .runtimeArgs(args)
* .chainName('casper')
* .payment(100_000_000_000)
* .build();
* ```
*/
export declare class SessionBuilder extends TransactionBuilder<SessionBuilder> {
private _isInstallOrUpgrade;
constructor();
/**
* Sets the WebAssembly bytecode for the session.
*
* @param wasmBytes - The compiled WebAssembly contract bytecode
* @returns The builder instance for method chaining
*/
wasm(wasmBytes: Uint8Array): SessionBuilder;
/**
* Marks this session as an install or upgrade operation.
* Should be called when deploying a new contract or upgrading an existing one.
*
* @returns The builder instance for method chaining
*/
installOrUpgrade(): SessionBuilder;
/**
* Sets the runtime arguments to pass to the session.
*
* @param args - The arguments to pass to the contract installer
* @returns The builder instance for method chaining
*/
runtimeArgs(args: Args): SessionBuilder;
/**
* Builds and returns the Session transaction for Casper 1.5.
* Uses the legacy deploy format for backward compatibility.
*
* @returns A Transaction object compatible with Casper 1.5
* @throws {Error} If WASM bytecode is not specified
*/
buildFor1_5(): Transaction;
}
export {};