feat(delegates): add instant delegate withdrawal for a fee

ar-io · Oct 23, 2024 · 4b4cb8f · 4b4cb8f
1 parent 1e52daf
commit 4b4cb8f
Show file tree

Hide file tree

Showing 3 changed files with 79 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -44,7 +44,8 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
     - [`leaveNetwork()`](#leavenetwork)
     - [`updateGatewaySettings(gatewaySettings)`](#updategatewaysettingsgatewaysettings)
     - [`increaseDelegateStake({ target, qty })`](#increasedelegatestake-target-qty-)
-    - [`decreaseDelegateStake({ target, qty })`](#decreasedelegatestake-target-qty-)
+    - [`decreaseDelegateStake({ target, qty, instant })`](#decreasedelegatestake-target-qty-instant-)
+    - [`instantDelegateWithdrawal({ target, vaultId })`](#instantdelegatewithdrawal-target-vaultid-)
     - [`increaseOperatorStake({ qty })`](#increaseoperatorstake-qty-)
     - [`decreaseOperatorStake({ qty })`](#decreaseoperatorstake-qty-)
     - [`saveObservations({ reportTxId, failedGateways })`](#saveobservations-reporttxid-failedgateways-)
@@ -941,9 +942,9 @@ const { id: txId } = await io.increaseDelegateStake(
 );
 ```
 
-#### `decreaseDelegateStake({ target, qty })`
+#### `decreaseDelegateStake({ target, qty, instant })`
 
-Decreases the callers stake on the target gateway.
+Decreases the callers stake on the target gateway. Can instantly decrease stake by setting instant to `true`.
 
 _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
 
@@ -960,6 +961,39 @@ const { id: txId } = await io.decreaseDelegateStake(
 );
 ```
 
+Pay the early withdrawal fee and withdraw instantly.
+
+```typescript
+const io = IO.init({ signer: new ArweaveSigner(jwk) });
+const { id: txId } = await io.decreaseDelegateStake({
+  target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
+  qty: new IOToken(100).toMIO(),
+  instant: true, // Immediately withdraw this stake and pay the instant withdrawal fee
+});
+```
+
+#### `instantDelegateWithdrawal({ target, vaultId })`
+
+Instantly withdraws vaulted delegate tokens at the cost of the early withdrawal fee.
+
+_Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
+
+```typescript
+const io = IO.init({ signer: new ArweaveSigner(jwk) });
+const { id: txId } = await io.instantDelegateWithdrawal(
+  {
+    // gateway address where delegate vault exists
+    target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
+    // delegated vault id to cancel
+    vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
+  },
+  // optional additional tags
+  {
+    tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
+  },
+);
+```
+
 #### `increaseOperatorStake({ qty })`
 
 Increases the callers operator stake. Must be executed with a wallet registered as a gateway operator.

diff --git a/src/common/io.ts b/src/common/io.ts
@@ -824,6 +824,39 @@ export class IOWriteable extends IOReadable implements AoIOWrite {
     params: {
       target: string;
       decreaseQty: number | mIOToken;
+      instant: boolean;
+    },
+    options?: WriteOptions,
+  ): Promise<AoMessageResult> {
+    const { tags = [] } = options || {};
+    if (params.instant == true) {
+      return this.process.send({
+        signer: this.signer,
+        tags: [
+          ...tags,
+          { name: 'Action', value: 'Decrease-Delegate-Stake' },
+          { name: 'Target', value: params.target },
+          { name: 'Quantity', value: params.decreaseQty.valueOf().toString() },
+          { name: 'Instant', value: 'true' },
+        ],
+      });
+    } else {
+      return this.process.send({
+        signer: this.signer,
+        tags: [
+          ...tags,
+          { name: 'Action', value: 'Decrease-Delegate-Stake' },
+          { name: 'Target', value: params.target },
+          { name: 'Quantity', value: params.decreaseQty.valueOf().toString() },
+        ],
+      });
+    }
+  }
+
+  async instantDelegateWithdrawal(
+    params: {
+      target: string;
+      vaultId: string;
     },
     options?: WriteOptions,
   ): Promise<AoMessageResult> {
@@ -834,7 +867,7 @@ export class IOWriteable extends IOReadable implements AoIOWrite {
         ...tags,
         { name: 'Action', value: 'Decrease-Delegate-Stake' },
         { name: 'Target', value: params.target },
-        { name: 'Quantity', value: params.decreaseQty.valueOf().toString() },
+        { name: 'Vault-Id', value: params.vaultId },
       ],
     });
   }

diff --git a/src/types/io.ts b/src/types/io.ts
@@ -402,6 +402,14 @@ export interface AoIOWrite extends AoIORead {
     params: {
       target: WalletAddress;
       decreaseQty: number | mIOToken;
+      instant: true;
+    },
+    options?: WriteOptions,
+  ): Promise<AoMessageResult>;
+  instantDelegateWithdrawal(
+    params: {
+      target: WalletAddress;
+      vaultId: string;
     },
     options?: WriteOptions,
   ): Promise<AoMessageResult>;