Clawback

packages/ripple-binary-codec/src/enums/definitions.json

@@ -2343,6 +2343,7 @@
     "NFTokenCreateOffer": 27,
     "NFTokenCancelOffer": 28,
     "NFTokenAcceptOffer": 29,
+    "Clawback": 30,
     "EnableAmendment": 100,
     "SetFee": 101,
     "UNLModify": 102

packages/ripple-binary-codec/test/definitions.test.js

@@ -21,7 +21,7 @@ describe('encode and decode using new types as a parameter', function () {
     // Normally this would be generated directly from rippled with something like `server_definitions`.
     // Added here to make it easier to see what is actually changing in the definitions.json file.
     const definitions = JSON.parse(JSON.stringify(normalDefinitionsJson))
-    definitions.TRANSACTION_TYPES['NewTestTransaction'] = 30
+    definitions.TRANSACTION_TYPES['NewTestTransaction'] = 75
 
     const newDefs = new XrplDefinitions(definitions)
 

packages/xrpl/src/models/ledger/AccountRoot.ts

@@ -142,6 +142,10 @@ export interface AccountRootFlagsInterface {
    * Disallow incoming Trustlines from other accounts.
    */
   lsfDisallowIncomingTrustline?: boolean
+  /**
+   * This address can claw back issued currencies. Once enabled, cannot be disabled.
+   */
+  lsfAllowClawback?: boolean
 }
 
 export enum AccountRootFlags {
@@ -198,4 +202,8 @@ export enum AccountRootFlags {
    * Disallow incoming Trustlines from other accounts.
    */
   lsfDisallowIncomingTrustline = 0x20000000,
+  /**
+   * This address can claw back issued currencies. Once enabled, cannot be disabled.
+   */
+  lsfAllowClawback = 0x80000000,
 }

packages/xrpl/src/models/methods/accountInfo.ts

@@ -127,6 +127,10 @@ export interface AccountInfoAccountFlags {
    * Requires incoming payments to specify a Destination Tag.
    */
   requireDestinationTag: boolean
+  /**
+   * This address can claw back issued currencies. Once enabled, cannot be disabled.
+   */
+  allowClawback: boolean
 }
 
 /**

packages/xrpl/src/models/transactions/accountSet.ts

@@ -56,6 +56,8 @@ export enum AccountSetAsfFlags {
   asfDisallowIncomingPayChan = 14,
   /** Disallow other accounts from creating incoming Trustlines */
   asfDisallowIncomingTrustline = 15,
+  /** Permanently gain the ability to claw back issued funds */
+  asfAllowClawback = 16,
 }
 
 /**

packages/xrpl/src/models/transactions/clawback.ts

@@ -0,0 +1,41 @@
+import { ValidationError } from '../../errors'
+import { IssuedCurrencyAmount } from '../common'
+
+import { BaseTransaction, validateBaseTransaction, isAmount } from './common'
+
+/**
+ * The Clawback transaction is used by the token issuer to claw back
+ * issued tokens from a holder.
+ */
+export interface Clawback extends BaseTransaction {
+  TransactionType: 'Clawback'
+  /**
+   * Indicates the AccountID that submitted this transaction. The account MUST
+   * be the issuer of the currency.
+   */
+  Account: string
+  /**
+   * The amount of currency to deliver, and it must be non-XRP. The nested field
+   * names MUST be lower-case. The `issuer` field MUST be the holder's address,
+   * whom to be clawed back.
+   */
+  Amount: IssuedCurrencyAmount
+}
+
+/**
+ * Verify the form and type of an Clawback at runtime.
+ *
+ * @param tx - An Clawback Transaction.
+ * @throws When the Clawback is Malformed.
+ */
+export function validateClawback(tx: Record<string, unknown>): void {
+  validateBaseTransaction(tx)
+
+  if (tx.Amount == null) {
+    throw new ValidationError('Clawback: missing field Amount')
+  }
+
+  if (!isAmount(tx.Amount)) {
+    throw new ValidationError('Clawback: invalid Amount')
+  }
+}

packages/xrpl/src/models/transactions/index.ts

@@ -49,3 +49,4 @@ export { SignerListSet } from './signerListSet'
 export { TicketCreate } from './ticketCreate'
 export { TrustSetFlagsInterface, TrustSetFlags, TrustSet } from './trustSet'
 export { UNLModify } from './UNLModify'
+export { Clawback } from './clawback'

packages/xrpl/src/models/transactions/transaction.ts

@@ -11,6 +11,7 @@ import { AccountSet, validateAccountSet } from './accountSet'
 import { CheckCancel, validateCheckCancel } from './checkCancel'
 import { CheckCash, validateCheckCash } from './checkCash'
 import { CheckCreate, validateCheckCreate } from './checkCreate'
+import { Clawback, validateClawback } from './clawback'
 import { isIssuedCurrency } from './common'
 import { DepositPreauth, validateDepositPreauth } from './depositPreauth'
 import { EscrowCancel, validateEscrowCancel } from './escrowCancel'
@@ -60,6 +61,7 @@ export type Transaction =
   | CheckCancel
   | CheckCash
   | CheckCreate
+  | Clawback
   | DepositPreauth
   | EscrowCancel
   | EscrowCreate
@@ -177,6 +179,10 @@ export function validate(transaction: Record<string, unknown>): void {
       validateCheckCreate(tx)
       break
 
+    case 'Clawback':
+      validateClawback(tx)
+      break
+
     case 'DepositPreauth':
       validateDepositPreauth(tx)
       break

packages/xrpl/test/integration/transactions/clawback.test.ts

@@ -0,0 +1,98 @@
+import { assert } from 'chai'
+
+import {
+  AccountSet,
+  AccountSetAsfFlags,
+  TrustSet,
+  Payment,
+  Clawback,
+} from '../../../src'
+import serverUrl from '../serverUrl'
+import {
+  setupClient,
+  teardownClient,
+  type XrplIntegrationTestContext,
+} from '../setup'
+import { generateFundedWallet, testTransaction } from '../utils'
+
+// how long before each test case times out
+const TIMEOUT = 20000
+
+describe('Clawback', function () {
+  let testContext: XrplIntegrationTestContext
+
+  beforeEach(async () => {
+    testContext = await setupClient(serverUrl)
+  })
+  afterEach(async () => teardownClient(testContext))
+
+  it(
+    'base',
+    async () => {
+      const wallet2 = await generateFundedWallet(testContext.client)
+
+      const setupAccountSetTx: AccountSet = {
+        TransactionType: 'AccountSet',
+        Account: testContext.wallet.classicAddress,
+        SetFlag: AccountSetAsfFlags.asfAllowClawback,
+      }
+      await testTransaction(
+        testContext.client,
+        setupAccountSetTx,
+        testContext.wallet,
+      )
+
+      const setupTrustSetTx: TrustSet = {
+        TransactionType: 'TrustSet',
+        Account: wallet2.classicAddress,
+        LimitAmount: {
+          currency: 'USD',
+          issuer: testContext.wallet.classicAddress,
+          value: '1000',
+        },
+      }
+      await testTransaction(testContext.client, setupTrustSetTx, wallet2)
+
+      const setupPaymentTx: Payment = {
+        TransactionType: 'Payment',
+        Account: testContext.wallet.classicAddress,
+        Destination: wallet2.classicAddress,
+        Amount: {
+          currency: 'USD',
+          issuer: testContext.wallet.classicAddress,
+          value: '1000',
+        },
+      }
+      await testTransaction(
+        testContext.client,
+        setupPaymentTx,
+        testContext.wallet,
+      )
+
+      // verify that line is created
+      const response1 = await testContext.client.request({
+        command: 'account_objects',
+        account: wallet2.classicAddress,
+        type: 'state',
+      })
+      assert.lengthOf(
+        response1.result.account_objects,
+        1,
+        'Should be exactly one line on the ledger',
+      )
+
+      // actual test - clawback
+      const tx: Clawback = {
+        TransactionType: 'Clawback',
+        Account: testContext.wallet.classicAddress,
+        Amount: {
+          currency: 'USD',
+          issuer: wallet2.classicAddress,
+          value: '1000',
+        },
+      }
+      await testTransaction(testContext.client, tx, testContext.wallet)
+    },
+    TIMEOUT,
+  )
+})

packages/xrpl/test/models/clawback.test.ts

@@ -0,0 +1,51 @@
+import { assert } from 'chai'
+
+import { validate, ValidationError } from '../../src'
+
+/**
+ * Clawback Transaction Verification Testing.
+ *
+ * Providing runtime verification testing for each specific transaction type.
+ */
+describe('Clawback', function () {
+  it(`verifies valid Clawback`, function () {
+    const validClawback = {
+      TransactionType: 'Clawback',
+      Amount: {
+        currency: 'DSH',
+        issuer: 'rcXY84C4g14iFp6taFXjjQGVeHqSCh9RX',
+        value: '43.11584856965009',
+      },
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+    } as any
+
+    assert.doesNotThrow(() => validate(validClawback))
+  })
+
+  it(`throws w/ missing Amount`, function () {
+    const missingAmount = {
+      TransactionType: 'Clawback',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+    } as any
+
+    assert.throws(
+      () => validate(missingAmount),
+      ValidationError,
+      'Clawback: missing field Amount',
+    )
+  })
+
+  it(`throws w/ invalid Amount`, function () {
+    const invalidAmount = {
+      TransactionType: 'Clawback',
+      Amount: 100000000,
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+    } as any
+
+    assert.throws(
+      () => validate(invalidAmount),
+      ValidationError,
+      'Clawback: invalid Amount',
+    )
+  })
+})

packages/xrpl/test/models/utils.test.ts

@@ -166,7 +166,8 @@ describe('Models Utils', function () {
         AccountRootFlags.lsfDisallowIncomingNFTokenOffer |
         AccountRootFlags.lsfDisallowIncomingCheck |
         AccountRootFlags.lsfDisallowIncomingPayChan |
-        AccountRootFlags.lsfDisallowIncomingTrustline
+        AccountRootFlags.lsfDisallowIncomingTrustline |
+        AccountRootFlags.lsfAllowClawback
 
       const parsed = parseAccountRootFlags(accountRootFlags)
 
@@ -183,7 +184,8 @@ describe('Models Utils', function () {
           parsed.lsfDisallowIncomingNFTokenOffer &&
           parsed.lsfDisallowIncomingCheck &&
           parsed.lsfDisallowIncomingPayChan &&
-          parsed.lsfDisallowIncomingTrustline,
+          parsed.lsfDisallowIncomingTrustline &&
+          parsed.lsfAllowClawback,
       )
     })
 
@@ -203,6 +205,7 @@ describe('Models Utils', function () {
       assert.isUndefined(parsed.lsfDisallowIncomingCheck)
       assert.isUndefined(parsed.lsfDisallowIncomingPayChan)
       assert.isUndefined(parsed.lsfDisallowIncomingTrustline)
+      assert.isUndefined(parsed.lsfAllowClawback)
     })
   })
 })