onesec-bridge
Version:
A library for interacting with the onesec.to bridge
185 lines (184 loc) • 6.16 kB
TypeScript
import { Deployment, OneSecForwarding, Step, StepStatus } from './types';
export { EvmToIcpBridgeBuilder, IcpToEvmBridgeBuilder } from './bridge';
export { DEFAULT_CONFIG } from './config';
export type { Config, IcpConfig, TokenConfig } from './config';
export type { About, Amount, OneSecForwarding, Step, StepStatus as StepStatus, } from './types';
/**
* Constructs an instance of `OneSecForwarding` for bridging tokens from EVM
* chains to ICP using forwarding addresses.
*
* A forwarding address is an EVM address that is derived from an ICP address.
* Tokens transferred to the forwarding address on EVM are bridged to the
* corresponding ICP address on ICP.
*
* @deprecated Use `EvmToIcpBridgeBuilder.forward()` instead for better step-by-step
* execution, progress tracking, and error handling.
*
* @example
* ```typescript
* // Instead of:
* // const forwarding = oneSecForwarding();
* // const address = await forwarding.addressFor(receiver);
*
* // Use:
* const plan = await new EvmToIcpBridgeBuilder("Base", "USDC")
* .receiver(icpPrincipal)
* .amountInUnits(1_500_000n)
* .forward();
*
* // Print plan overview
* console.log("Plan steps:");
* plan.steps().forEach((step, index) => {
* console.log(` ${index + 1}. ${step.about().verbose}`);
* });
*
* // Execute step by step with progress tracking
* let nextStep;
* while (nextStep = plan.nextStepToRun()) {
* const status = nextStep.status();
* if (status.state === "planned") {
* console.log(nextStep.about().verbose);
* }
* try {
* const result = await nextStep.run();
* console.log(` - ${result.verbose}`);
* if (result.forwardingAddress) {
* console.log(`Please send USDC to ${result.forwardingAddress}`);
* }
* } catch (error) {
* console.error("Step execution failed:", error);
* break;
* }
* }
*
* // Get final results after completion
* const finalStep = plan.latestStep();
* if (finalStep) {
* const status = finalStep.status();
* if (status.state === "succeeded") {
* console.log("Forwarding completed successfully!");
* if (status.amount) {
* console.log(`Received: ${status.amount.inTokens} USDC`);
* }
* if (status.transaction) {
* console.log(`ICP Transaction: ${JSON.stringify(status.transaction)}`);
* }
* }
* }
* ```
*
* @param setup - the deployment environment (defaults to Mainnet)
* @param addresses - optional canister IDs for custom deployments
*/
export declare function oneSecForwarding(setup?: Deployment): OneSecForwarding;
/**
* Orchestrates the execution of a multi-step token bridging process.
*
* A BridgingPlan contains an ordered sequence of steps that must be executed
* to complete a token bridge operation. Steps can be run individually with
* `nextStepToRun().run()` or all at once with `runAllSteps()`.
*
* The plan tracks execution state and handles step dependencies, ensuring
* steps are executed in the correct order and failed steps halt progression.
*
* @example
* ```typescript
* const plan = await new EvmToIcpBridgeBuilder("Base", "USDC")
* .receiver(icpPrincipal)
* .amountInUnits(1_500_000n)
* .build(evmSigner);
*
* // Print plan overview
* console.log("Plan steps:");
* plan.steps().forEach((step, index) => {
* console.log(` ${index + 1}. ${step.about().verbose}`);
* });
*
* // Execute step-by-step with progress tracking
* let nextStep;
* while (nextStep = plan.nextStepToRun()) {
* const status = nextStep.status();
* if (status.state === "planned") {
* console.log(nextStep.about().verbose);
* }
* try {
* const result = await nextStep.run();
* console.log(` - ${result.verbose}`);
* } catch (error) {
* console.error("Step execution failed:", error);
* break;
* }
* }
*
* // Get final results after completion
* const finalStep = plan.latestStep();
* if (finalStep) {
* const status = finalStep.status();
* if (status.state === "succeeded") {
* console.log("Bridging completed successfully!");
* if (status.amount) {
* console.log(`Received: ${status.amount.inTokens} USDC`);
* }
* if (status.transaction) {
* console.log(`Transaction: ${JSON.stringify(status.transaction)}`);
* }
* }
* }
*
* // Or execute all steps at once
* try {
* const finalResult = await plan.runAllSteps();
* console.log("Bridging completed:", finalResult.state);
* if (finalResult.state === "succeeded") {
* if (finalResult.amount) {
* console.log(`Received: ${finalResult.amount.inTokens} USDC`);
* }
* if (finalResult.transaction) {
* console.log(`Transaction: ${JSON.stringify(finalResult.transaction)}`);
* }
* }
* } catch (error) {
* console.error("Bridging failed:", error);
* }
* ```
*/
export declare class BridgingPlan {
private _steps;
private currentStepIndex;
constructor(_steps: Step[]);
/**
* Get all steps in this bridging plan.
* @returns Array of steps in execution order
*/
steps(): Step[];
/**
* Get the most recently executed step.
* @returns The latest executed step, or undefined if no steps have been executed
*/
latestStep(): Step | undefined;
/**
* Get the next step to execute.
*
* Automatically skips completed steps and stops at failed steps.
* Returns undefined when all steps are complete or a step has failed.
*
* @returns Next step to execute, or undefined if plan is complete/failed
*/
nextStepToRun(): Step | undefined;
/**
* Execute all remaining steps in sequence.
*
* Runs each step until completion or failure. If a step fails,
* execution stops and the error status is returned.
*
* @returns Final step status (success or failure)
* @throws Error if a step encounters an unexpected error during execution
*/
runAllSteps(): Promise<StepStatus>;
/**
* Calculate the total expected duration for all steps.
* @returns Total expected duration in milliseconds
*/
expectedDurationMs(): number;
private skipDone;
}