feat: NFT support (#1829)

* add NFTokenBurn and NFTokenMint

* add NFTokenCreateOffer

* add NFTokenCancelOffer

* add NFTokenAcceptOffer

* add requests and responses

* make a beta 2.1.0

* rename TokenIDs to TokenOffers

* add validations and fixup docs

* add tests

* add missing error codes to binary codec

* adds history changes

packages/xrpl/test/models/NFTokenAcceptOffer.ts

@@ -0,0 +1,178 @@
+import { assert } from 'chai'
+import { validate, ValidationError } from 'xrpl-local'
+
+const BUY_OFFER =
+  'AED08CC1F50DD5F23A1948AF86153A3F3B7593E5EC77D65A02BB1B29E05AB6AF'
+const SELL_OFFER =
+  'AED08CC1F50DD5F23A1948AF86153A3F3B7593E5EC77D65A02BB1B29E05AB6AE'
+
+/**
+ * NFTokenAcceptOffer Transaction Verification Testing.
+ *
+ * Providing runtime verification testing for each specific transaction type.
+ */
+describe('NFTokenAcceptOffer', function () {
+  it(`verifies valid NFTokenAcceptOffer with BuyOffer`, function () {
+    const validNFTokenAcceptOffer = {
+      TransactionType: 'NFTokenAcceptOffer',
+      BuyOffer: BUY_OFFER,
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenAcceptOffer))
+  })
+
+  it(`verifies valid NFTokenAcceptOffer with SellOffer`, function () {
+    const validNFTokenAcceptOffer = {
+      TransactionType: 'NFTokenAcceptOffer',
+      SellOffer: SELL_OFFER,
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenAcceptOffer))
+  })
+
+  it(`throws w/ missing SellOffer and BuyOffer`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenAcceptOffer',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenAcceptOffer: must set either SellOffer or BuyOffer',
+    )
+  })
+
+  it(`throws w/ missing SellOffer and present BrokerFee`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenAcceptOffer',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      BuyOffer: BUY_OFFER,
+      BrokerFee: '1',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenAcceptOffer: both SellOffer and BuyOffer must be set if using brokered mode',
+    )
+  })
+
+  it(`throws w/ missing BuyOffer and present BrokerFee`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenAcceptOffer',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      SellOffer: SELL_OFFER,
+      BrokerFee: '1',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenAcceptOffer: both SellOffer and BuyOffer must be set if using brokered mode',
+    )
+  })
+
+  it(`verifies valid NFTokenAcceptOffer with both offers and no BrokerFee`, function () {
+    const validNFTokenAcceptOffer = {
+      TransactionType: 'NFTokenAcceptOffer',
+      SellOffer: SELL_OFFER,
+      BuyOffer: BUY_OFFER,
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenAcceptOffer))
+  })
+
+  it(`verifies valid NFTokenAcceptOffer with BrokerFee`, function () {
+    const validNFTokenAcceptOffer = {
+      TransactionType: 'NFTokenAcceptOffer',
+      SellOffer: SELL_OFFER,
+      BuyOffer: BUY_OFFER,
+      BrokerFee: '1',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenAcceptOffer))
+  })
+
+  it(`throws w/ BrokerFee === 0`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenAcceptOffer',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      SellOffer: SELL_OFFER,
+      BuyOffer: BUY_OFFER,
+      BrokerFee: '0',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenAcceptOffer: BrokerFee must be greater than 0; omit if there is no fee',
+    )
+  })
+
+  it(`throws w/ BrokerFee < 0`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenAcceptOffer',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      SellOffer: SELL_OFFER,
+      BuyOffer: BUY_OFFER,
+      BrokerFee: '-1',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenAcceptOffer: BrokerFee must be greater than 0; omit if there is no fee',
+    )
+  })
+
+  it(`throws w/ invalid BrokerFee`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenAcceptOffer',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      SellOffer: SELL_OFFER,
+      BuyOffer: BUY_OFFER,
+      BrokerFee: 1,
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenAcceptOffer: invalid BrokerFee',
+    )
+  })
+})

packages/xrpl/test/models/NFTokenBurn.ts

@@ -0,0 +1,41 @@
+import { assert } from 'chai'
+import { validate, ValidationError } from 'xrpl-local'
+
+const TOKEN_ID =
+  '00090032B5F762798A53D543A014CAF8B297CFF8F2F937E844B17C9E00000003'
+
+/**
+ * NFTokenBurn Transaction Verification Testing.
+ *
+ * Providing runtime verification testing for each specific transaction type.
+ */
+describe('NFTokenBurn', function () {
+  it(`verifies valid NFTokenBurn`, function () {
+    const validNFTokenBurn = {
+      TransactionType: 'NFTokenBurn',
+      TokenID: TOKEN_ID,
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenBurn))
+  })
+
+  it(`throws w/ missing TokenID`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenBurn',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenBurn: missing field TokenID',
+    )
+  })
+})

packages/xrpl/test/models/NFTokenCancelOffer.ts

@@ -0,0 +1,58 @@
+import { assert } from 'chai'
+import { validate, ValidationError } from 'xrpl-local'
+
+const BUY_OFFER =
+  'AED08CC1F50DD5F23A1948AF86153A3F3B7593E5EC77D65A02BB1B29E05AB6AF'
+
+/**
+ * NFTokenCancelOffer Transaction Verification Testing.
+ *
+ * Providing runtime verification testing for each specific transaction type.
+ */
+describe('NFTokenCancelOffer', function () {
+  it(`verifies valid NFTokenCancelOffer`, function () {
+    const validNFTokenCancelOffer = {
+      TransactionType: 'NFTokenCancelOffer',
+      TokenOffers: [BUY_OFFER],
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenCancelOffer))
+  })
+
+  it(`throws w/ missing TokenOffers`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCancelOffer',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCancelOffer: missing field TokenOffers',
+    )
+  })
+
+  it(`throws w/ empty TokenOffers`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCancelOffer',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      TokenOffers: [],
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: 2147483648,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCancelOffer: empty field TokenOffers',
+    )
+  })
+})

packages/xrpl/test/models/NFTokenCreateOffer.ts

@@ -0,0 +1,214 @@
+import { assert } from 'chai'
+import { validate, ValidationError, NFTokenCreateOfferFlags } from 'xrpl-local'
+
+const TOKEN_ID =
+  '00090032B5F762798A53D543A014CAF8B297CFF8F2F937E844B17C9E00000003'
+
+/**
+ * NFTokenCreateOffer Transaction Verification Testing.
+ *
+ * Providing runtime verification testing for each specific transaction type.
+ */
+describe('NFTokenCreateOffer', function () {
+  it(`verifies valid NFTokenCreateOffer buyside`, function () {
+    const validNFTokenCreateOffer = {
+      TransactionType: 'NFTokenCreateOffer',
+      TokenID: TOKEN_ID,
+      Amount: '1',
+      Owner: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Expiration: 1000,
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Destination: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenCreateOffer))
+  })
+
+  it(`verifies valid NFTokenCreateOffer sellside`, function () {
+    const validNFTokenCreateOffer = {
+      TransactionType: 'NFTokenCreateOffer',
+      TokenID: TOKEN_ID,
+      Amount: '1',
+      Flags: NFTokenCreateOfferFlags.tfSellToken,
+      Expiration: 1000,
+      Destination: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenCreateOffer))
+  })
+
+  it(`verifies w/ 0 Amount NFTokenCreateOffer sellside`, function () {
+    const validNFTokenCreateOffer = {
+      TransactionType: 'NFTokenCreateOffer',
+      TokenID: TOKEN_ID,
+      Amount: '0',
+      Flags: NFTokenCreateOfferFlags.tfSellToken,
+      Expiration: 1000,
+      Destination: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenCreateOffer))
+  })
+
+  it(`throws w/ Account === Owner`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCreateOffer',
+      TokenID: TOKEN_ID,
+      Amount: '1',
+      Expiration: 1000,
+      Owner: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCreateOffer: Owner and Account must not be equal',
+    )
+  })
+
+  it(`throws w/ Account === Destination`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCreateOffer',
+      TokenID: TOKEN_ID,
+      Amount: '1',
+      Flags: NFTokenCreateOfferFlags.tfSellToken,
+      Expiration: 1000,
+      Destination: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCreateOffer: Destination and Account must not be equal',
+    )
+  })
+
+  it(`throws w/out TokenID`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCreateOffer',
+      Amount: '1',
+      Owner: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXe',
+      Expiration: 1000,
+      Destination: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCreateOffer: missing field TokenID',
+    )
+  })
+
+  it(`throws w/ invalid Amount`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCreateOffer',
+      TokenID: TOKEN_ID,
+      Amount: 1,
+      Owner: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXe',
+      Expiration: 1000,
+      Destination: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCreateOffer: invalid Amount',
+    )
+  })
+
+  it(`throws w/ missing Amount`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCreateOffer',
+      Owner: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXe',
+      Expiration: 1000,
+      TokenID: TOKEN_ID,
+      Destination: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCreateOffer: invalid Amount',
+    )
+  })
+
+  it(`throws w/ Owner for sell offer`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCreateOffer',
+      Expiration: 1000,
+      Owner: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      TokenID: TOKEN_ID,
+      Flags: NFTokenCreateOfferFlags.tfSellToken,
+      Amount: '1',
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCreateOffer: Owner must not be present for sell offers',
+    )
+  })
+
+  it(`throws w/out Owner for buy offer`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCreateOffer',
+      Expiration: 1000,
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Amount: '1',
+      TokenID: TOKEN_ID,
+      Fee: '5000000',
+      Sequence: 2470665,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCreateOffer: Owner must be present for buy offers',
+    )
+  })
+
+  it(`throws w/ 0 Amount for buy offer`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenCreateOffer',
+      Expiration: 1000,
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Owner: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      Amount: '0',
+      Fee: '5000000',
+      TokenID: TOKEN_ID,
+      Sequence: 2470665,
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenCreateOffer: Amount must be greater than 0 for buy offers',
+    )
+  })
+})

packages/xrpl/test/models/NFTokenMint.ts

@@ -0,0 +1,69 @@
+import { assert } from 'chai'
+import {
+  convertStringToHex,
+  validate,
+  ValidationError,
+  NFTokenMintFlags,
+} from 'xrpl-local'
+
+/**
+ * NFTokenMint Transaction Verification Testing.
+ *
+ * Providing runtime verification testing for each specific transaction type.
+ */
+describe('NFTokenMint', function () {
+  it(`verifies valid NFTokenMint`, function () {
+    const validNFTokenMint = {
+      TransactionType: 'NFTokenMint',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: NFTokenMintFlags.tfTransferable,
+      TokenTaxon: 0,
+      Issuer: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      TransferFee: 1,
+      URI: convertStringToHex('http://xrpl.org'),
+    } as any
+
+    assert.doesNotThrow(() => validate(validNFTokenMint))
+  })
+
+  it(`throws w/ missing TokenTaxon`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenMint',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: NFTokenMintFlags.tfTransferable,
+      Issuer: 'r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ',
+      TransferFee: 1,
+      URI: convertStringToHex('http://xrpl.org'),
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenMint: missing field TokenTaxon',
+    )
+  })
+
+  it(`throws w/ Account === Issuer`, function () {
+    const invalid = {
+      TransactionType: 'NFTokenMint',
+      Account: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      Fee: '5000000',
+      Sequence: 2470665,
+      Flags: NFTokenMintFlags.tfTransferable,
+      Issuer: 'rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm',
+      TransferFee: 1,
+      TokenTaxon: 0,
+      URI: convertStringToHex('http://xrpl.org'),
+    } as any
+
+    assert.throws(
+      () => validate(invalid),
+      ValidationError,
+      'NFTokenMint: Issuer must not be equal to Account',
+    )
+  })
+})