add userAgent and usageContext to faucet transactions (#2309)

packages/xrpl/snippets/src/multisigning.ts

@@ -15,9 +15,15 @@ async function multisigning(): Promise<void> {
    * In practice, users generally will not have all keys in one spot,
    * hence, users need to implement a way to get signatures.
    */
-  const { wallet: wallet1 } = await client.fundWallet()
+  const { wallet: wallet1 } = await client.fundWallet(null, {
-  const { wallet: wallet2 } = await client.fundWallet()
+    usageContext: 'code snippets',
-  const { wallet: walletMaster } = await client.fundWallet()
+  })
+  const { wallet: wallet2 } = await client.fundWallet(null, {
+    usageContext: 'code snippets',
+  })
+  const { wallet: walletMaster } = await client.fundWallet(null, {
+    usageContext: 'code snippets',
+  })
   const signerListSet: SignerListSet = {
     TransactionType: 'SignerListSet',
     Account: walletMaster.classicAddress,

packages/xrpl/snippets/src/partialPayment.ts

@@ -7,8 +7,12 @@ async function partialPayment(): Promise<void> {
   await client.connect()
 
   // creating wallets as prerequisite
-  const { wallet: wallet1 } = await client.fundWallet()
+  const { wallet: wallet1 } = await client.fundWallet(null, {
-  const { wallet: wallet2 } = await client.fundWallet()
+    usageContext: 'code snippets',
+  })
+  const { wallet: wallet2 } = await client.fundWallet(null, {
+    usageContext: 'code snippets',
+  })
 
   // create a trustline to issue an IOU `FOO` and set limit on it.
   const trust_set_tx: TrustSet = {

packages/xrpl/snippets/src/paths.ts

@@ -5,7 +5,9 @@ const client = new Client('wss://s.altnet.rippletest.net:51233')
 async function createTxWithPaths(): Promise<void> {
   await client.connect()
 
-  const { wallet } = await client.fundWallet()
+  const { wallet } = await client.fundWallet(null, {
+    usageContext: 'code snippets',
+  })
   const destination_account = 'rKT4JX4cCof6LcDYRz8o3rGRu7qxzZ2Zwj'
   const destination_amount = {
     value: '0.001',

packages/xrpl/snippets/src/reliableTransactionSubmission.ts

@@ -45,8 +45,12 @@ async function sendReliableTx(): Promise<void> {
   await client.connect()
 
   // creating wallets as prerequisite
-  const { wallet: wallet1 } = await client.fundWallet()
+  const { wallet: wallet1 } = await client.fundWallet(null, {
-  const { wallet: wallet2 } = await client.fundWallet()
+    usageContext: 'code snippets',
+  })
+  const { wallet: wallet2 } = await client.fundWallet(null, {
+    usageContext: 'code snippets',
+  })
 
   console.log('Balances of wallets before Payment tx')
   console.log(

packages/xrpl/snippets/src/sendEscrow.ts

@@ -15,8 +15,12 @@ async function sendEscrow(): Promise<void> {
   await client.connect()
 
   // creating wallets as prerequisite
-  const { wallet: wallet1 } = await client.fundWallet()
+  const { wallet: wallet1 } = await client.fundWallet(null, {
-  const { wallet: wallet2 } = await client.fundWallet()
+    usageContext: 'code snippets',
+  })
+  const { wallet: wallet2 } = await client.fundWallet(null, {
+    usageContext: 'code snippets',
+  })
 
   console.log('Balances of wallets before Escrow tx was created:')
   console.log(

packages/xrpl/snippets/src/setRegularKey.ts

@@ -8,9 +8,15 @@ const client = new Client('wss://s.altnet.rippletest.net:51233')
  */
 async function setRegularKey(): Promise<void> {
   await client.connect()
-  const { wallet: wallet1 } = await client.fundWallet()
+  const { wallet: wallet1 } = await client.fundWallet(null, {
-  const { wallet: wallet2 } = await client.fundWallet()
+    usageContext: 'code snippets',
-  const { wallet: regularKeyWallet } = await client.fundWallet()
+  })
+  const { wallet: wallet2 } = await client.fundWallet(null, {
+    usageContext: 'code snippets',
+  })
+  const { wallet: regularKeyWallet } = await client.fundWallet(null, {
+    usageContext: 'code snippets',
+  })
 
   console.log('Balances before payment')
   console.log(await client.getXrpBalance(wallet1.classicAddress))

packages/xrpl/src/Wallet/fundWallet.ts

@@ -79,6 +79,8 @@ const MAX_ATTEMPTS = 20
  * Ex: client.fundWallet(null,{'faucet.altnet.rippletest.net', '/accounts'})
  * specifies a request to 'faucet.altnet.rippletest.net/accounts' to fund a new wallet.
  * @param options.amount - A custom amount to fund, if undefined or null, the default amount will be 1000.
+ * @param options.usageContext - An optional field to indicate the use case context of the faucet transaction
+ * Ex: integration test, code snippets.
  * @returns A Wallet on the Testnet or Devnet that contains some amount of XRP,
  * and that wallet's balance in XRP.
  * @throws When either Client isn't connected or unable to fund wallet address.
@@ -91,6 +93,7 @@ async function fundWallet(
     faucetHost?: string
     faucetPath?: string
     amount?: string
+    usageContext?: string
   },
 ): Promise<{
   wallet: Wallet
@@ -112,6 +115,8 @@ async function fundWallet(
       JSON.stringify({
         destination: walletToFund.classicAddress,
         xrpAmount: options?.amount,
+        userAgent: 'xrpl.js',
+        usageContext: options?.usageContext,
       }),
     ),
   )

packages/xrpl/test/integration/fundWallet.test.ts

@@ -19,6 +19,7 @@ async function generate_faucet_wallet_and_fund_again(
   const { wallet, balance } = await api.fundWallet(null, {
     faucetHost,
     faucetPath,
+    usageContext: 'integration-test',
   })
   assert.notEqual(wallet, undefined)
   assert(isValidClassicAddress(wallet.classicAddress))
@@ -34,6 +35,7 @@ async function generate_faucet_wallet_and_fund_again(
   const { balance: newBalance } = await api.fundWallet(wallet, {
     faucetHost,
     faucetPath,
+    usageContext: 'integration-test',
   })
 
   const afterSent = await api.request({
@@ -97,7 +99,9 @@ describe('fundWallet', function () {
 
       await api.connect()
 
-      const { wallet, balance } = await api.fundWallet()
+      const { wallet, balance } = await api.fundWallet(null, {
+        usageContext: 'integration-test',
+      })
 
       assert.notEqual(wallet, undefined)
       assert(isValidClassicAddress(wallet.classicAddress))
@@ -138,7 +142,10 @@ describe('fundWallet', function () {
       const api = new Client('wss://s.altnet.rippletest.net:51233')
 
       await api.connect()
-      const { wallet, balance } = await api.fundWallet(null, { amount: '2000' })
+      const { wallet, balance } = await api.fundWallet(null, {
+        amount: '2000',
+        usageContext: 'integration-test',
+      })
       assert.equal(balance, '2000')
       assert.notEqual(wallet, undefined)
       assert(isValidClassicAddress(wallet.classicAddress))

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

@@ -20,7 +20,9 @@ describe('NFTokenMint', function () {
       const client = new Client('wss://s.altnet.rippletest.net:51233/')
       await client.connect()
 
-      const { wallet, balance: _balance } = await client.fundWallet()
+      const { wallet, balance: _balance } = await client.fundWallet(null, {
+        usageContext: 'integration-test',
+      })
 
       const tx: NFTokenMint = {
         TransactionType: 'NFTokenMint',