SuiAdapter

Sui Adapter for Upshift SDK

Sui Adapter for Upshift SDK.

Holds the Sui configuration passed to new UpshiftSDK({ sui }), the Sui chain-identity helpers, and the vault deposit / instant-redeem builders. Transactions run on the configured network.

Example

const sdk = new UpshiftSDK({ appName: 'my-app', sui: { network: 'testnet' } });
sdk.sui.network; // 'testnet'
sdk.sui.isSuiAddress(vault.address);

Constructors

Constructor

new SuiAdapter(config?): SuiAdapter

Parameters

Returns

SuiAdapter

Accessors

chainId

Get Signature

get chainId(): number

The SDK's Sui chain ID, -2 (same as the backend's chain for Sui vaults).

Returns

number

network

Get Signature

get network(): ISuiNetwork

Configured Sui network; 'mainnet' unless the SDK was built with another.

Returns

ISuiNetwork

rpcUrl

Get Signature

get rpcUrl(): string

Configured RPC endpoint override, or undefined when none was given.

Returns

string

Methods

claimWithdrawal()

claimWithdrawal(params): Promise<ISuiClaimWithdrawalTransaction>

Build an unsigned claim of a withdrawal request on the configured network: burns the escrowed shares and pays their current value, with no instant fee, to the request's payout.

The payout lands in the payout address's address balance, not as a coin object. A request can be claimed from eligibleAtMs until expiresAtMs by its owner or finalizer (anyone when it names none), and by anyone from one day after it became eligible.

RPC cost: one dry run. Plus the vault's package lookup (see ISuiVaultRef.originalPackageId).

Parameters

Returns

Promise<ISuiClaimWithdrawalTransaction>

The unsigned transaction, the shares it burns, the dry run's payout, and the minimum it enforces.

Throws

UpshiftValidationError for malformed input, unknown contract IDs, or a request that no longer exists.

Throws

UpshiftVaultAbortError when the vault would reject it, e.g. not_eligible_yet, request_expired or insufficient_liquidity.

Throws

UpshiftNetworkError when every Sui endpoint fails.

Example

const [pending] = await sdk.sui.getWithdrawalRequests({ ...vault, owner: account.address });
const { transaction } = await sdk.sui.claimWithdrawal({
  ...vault, request: pending.request, sender: account.address,
});

executeTransaction()

executeTransaction(signed): Promise<string>

Execute a wallet-signed transaction on the configured network and wait until it is indexed. Not needed when the wallet executes the transaction itself (e.g. dApp Kit's signAndExecuteTransaction).

Side effect on failure: a failed instant redemption is reported to that vault's curator with its digest (fire-and-forget).

Parameters

Returns

Promise<string>

The transaction digest.

Throws

UpshiftVaultAbortError when the vault aborted it on chain.

Throws

UpshiftSDKError (UNKNOWN) when it failed otherwise.

Throws

UpshiftTransactionError when it executed but was not indexed in time.

Throws

UpshiftNetworkError when every Sui endpoint fails.

getWithdrawalRequests()

getWithdrawalRequests(params): Promise<ISuiWithdrawalRequest[]>

A wallet's pending withdrawal requests on a vault, on the configured network, oldest first. Finds every request made through the SDK however old; claimed and cancelled requests are left out.

RPC cost: one object read for a wallet that has made up to 23 requests on the vault (most wallets), one more per further 25. Plus the vault's package lookup (see ISuiVaultRef.originalPackageId).

Parameters

Returns

Promise<ISuiWithdrawalRequest[]>

The pending requests, with shares, payout, and the times they become claimable and expire; empty when there are none.

Throws

UpshiftValidationError for malformed input, or a vault ID that is not an Upshift vault of a known or configured deployment.

Throws

UpshiftNetworkError when every Sui endpoint fails.

Example

const pending = await sdk.sui.getWithdrawalRequests({
  vaultId, assetCoinType, shareCoinType, owner: account.address,
});
const now = Date.now();
const claimable = pending.filter(
  (r) => r.eligibleAtMs <= now && (r.expiresAtMs === null || now < r.expiresAtMs),
);

isSuiAddress()

isSuiAddress(address): boolean

Check whether a string is a Sui address or object ID (0x + 64 hex chars).

Parameters

Returns

boolean

true for the long, 64-hex-digit form only.

isSuiVault()

isSuiVault(chainId): boolean

Check whether a chain ID is Sui's (-2).

Parameters

Returns

boolean

true only for -2.

vaultCancelRedeemRequest()

vaultCancelRedeemRequest(params): Promise<ISuiCancelRedeemRequestTransaction>

Build an unsigned cancellation of a pending withdrawal request on the configured network; the escrowed shares go back to the sender. Allowed at any time while the request exists, also while the vault is paused. Only the wallet that made the request may cancel it.

RPC cost: one dry run. Plus the vault's package lookup (see ISuiVaultRef.originalPackageId).

Parameters

Returns

Promise<ISuiCancelRedeemRequestTransaction>

The unsigned transaction and the shares it returns.

Throws

UpshiftValidationError for malformed input, unknown contract IDs, or a request that no longer exists.

Throws

UpshiftVaultAbortError when the vault would reject it, e.g. not_request_owner.

Throws

UpshiftNetworkError when every Sui endpoint fails.

Example

const { transaction } = await sdk.sui.vaultCancelRedeemRequest({
  vaultId, assetCoinType, shareCoinType, request, sender: account.address,
});

vaultDeposit()

vaultDeposit(params): Promise<ISuiDepositTransaction>

Build an unsigned deposit on the configured network: charge the management fee, deposit with a minimum share amount, send the shares to the sender. Dry-runs it first, so a vault that would reject it fails here.

RPC cost: one dry run (plus the coin lookup it needs). Plus the vault's package lookup (see ISuiVaultRef.originalPackageId).

Parameters

Returns

Promise<ISuiDepositTransaction>

The unsigned transaction for the sender's wallet, the shares the dry run minted, and the minimum it enforces.

Throws

UpshiftValidationError for malformed input, unknown contract IDs, or a transaction that cannot be built.

Throws

UpshiftVaultAbortError when the vault would reject it.

Throws

UpshiftNetworkError when every Sui endpoint fails.

Example

const { transaction } = await sdk.sui.vaultDeposit({
  vaultId: vault.address,
  assetCoinType: vault.depositAssets[0].address,
  shareCoinType: vault.receipt.address,
  amount: 1_000_000n,
  sender: account.address,
});
const digest = await sdk.sui.executeTransaction(
  await dAppKit.signTransaction({ transaction }),
);

vaultRedeem()

vaultRedeem(params): Promise<ISuiRedeemTransaction>

Build an unsigned instant redemption on the configured network: charge the management fee, redeem shares with a minimum net asset amount, send the assets to the sender. Dry-runs it first; a vault with a withdrawal queue attached fails with queue_attached.

Side effect on failure: a redemption the vault rejects is reported to that vault's curator (fire-and-forget; see monitoring.curatorAlerts).

RPC cost: one dry run (plus the coin lookup it needs). Plus the vault's package lookup (see ISuiVaultRef.originalPackageId).

Parameters

Returns

Promise<ISuiRedeemTransaction>

The unsigned transaction, the dry run's gross and net assets, and the minimum it enforces.

Throws

UpshiftValidationError for malformed input, unknown contract IDs, or a transaction that cannot be built.

Throws

UpshiftVaultAbortError when the vault would reject it.

Throws

UpshiftNetworkError when every Sui endpoint fails.

vaultRequestRedeem()

vaultRequestRedeem(params): Promise<ISuiRequestRedeemTransaction>

Build an unsigned withdrawal request on the configured network, for a vault with a withdrawal queue attached (where instant redemption is off). Escrows the shares in a new request; dry-runs it first, so a vault that would reject it fails here.

The request is priced when it is claimed. Once the vault's cooldown has run, claim it with SuiAdapter.claimWithdrawal; cancel it at any time with SuiAdapter.vaultCancelRedeemRequest. List a wallet's requests with SuiAdapter.getWithdrawalRequests.

RPC cost: one object read for a wallet with up to 23 earlier requests on the vault (one more per further 25), then one dry run. Plus the vault's package lookup (see ISuiVaultRef.originalPackageId).

Parameters

Returns

Promise<ISuiRequestRedeemTransaction>

The unsigned transaction, the request ID, the request's object ID (request) for claiming or cancelling, and expectedAssets at today's price.

Throws

UpshiftValidationError for malformed input, unknown contract IDs, or a transaction that cannot be built.

Throws

UpshiftVaultAbortError when the vault would reject it, e.g. queue_not_attached (redeem instantly instead) or paused.

Throws

UpshiftNetworkError when every Sui endpoint fails.

Example

const { transaction, request } = await sdk.sui.vaultRequestRedeem({
  vaultId: vault.address,
  assetCoinType: vault.depositAssets[0].address,
  shareCoinType: vault.receipt.address,
  shares: 1_000_000n,
  sender: account.address,
});
await sdk.sui.executeTransaction(await dAppKit.signTransaction({ transaction }));

Interfaces

ISuiAdapterVault

A Sui vault as the adapter methods take it; the network is the adapter's. From an IVault: vaultId is address, assetCoinType is depositAssets[0].address, shareCoinType is receipt.address.

Properties

Variables

Sui

const Sui: object

Sui helpers by area: chain identity (utils), constants, the gRPC client with failover (client), move-call targets (targets), vault reads (getters) and deposit / instant-redeem builders (actions).

Type Declaration

References

default

Renames and re-exports SuiAdapter