add user agent and use case info to faucet json body (#572)

tests/integration/sugar/test_wallet.py

@@ -15,8 +15,12 @@
 time_of_last_hooks_faucet_call = 0
 
 
-def sync_generate_faucet_wallet_and_fund_again(self, client, faucet_host=None):
-    wallet = sync_generate_faucet_wallet(client, faucet_host=faucet_host)
+def sync_generate_faucet_wallet_and_fund_again(
+    self, client, faucet_host=None, usage_context="integration_test"
+):
+    wallet = sync_generate_faucet_wallet(
+        client, faucet_host=faucet_host, usage_context=usage_context
+    )
     result = client.request(
         AccountInfo(
             account=wallet.classic_address,
@@ -25,7 +29,9 @@ def sync_generate_faucet_wallet_and_fund_again(self, client, faucet_host=None):
     balance = int(result.result["account_data"]["Balance"])
     self.assertTrue(balance > 0)
 
-    new_wallet = sync_generate_faucet_wallet(client, wallet, faucet_host=faucet_host)
+    new_wallet = sync_generate_faucet_wallet(
+        client, wallet, faucet_host=faucet_host, usage_context="integration_test"
+    )
     new_result = client.request(
         AccountInfo(
             account=new_wallet.classic_address,
@@ -35,8 +41,12 @@ def sync_generate_faucet_wallet_and_fund_again(self, client, faucet_host=None):
     self.assertTrue(new_balance > balance)
 
 
-async def generate_faucet_wallet_and_fund_again(self, client, faucet_host=None):
-    wallet = await generate_faucet_wallet(client, faucet_host=faucet_host)
+async def generate_faucet_wallet_and_fund_again(
+    self, client, faucet_host=None, usage_context="integration_test"
+):
+    wallet = await generate_faucet_wallet(
+        client, faucet_host=faucet_host, usage_context=usage_context
+    )
     result = await client.request(
         AccountInfo(
             account=wallet.classic_address,
@@ -45,7 +55,9 @@ async def generate_faucet_wallet_and_fund_again(self, client, faucet_host=None):
     balance = int(result.result["account_data"]["Balance"])
     self.assertTrue(balance > 0)
 
-    new_wallet = await generate_faucet_wallet(client, wallet, faucet_host=faucet_host)
+    new_wallet = await generate_faucet_wallet(
+        client, wallet, faucet_host=faucet_host, usage_context=usage_context
+    )
     new_result = await client.request(
         AccountInfo(
             account=new_wallet.classic_address,
@@ -106,13 +118,19 @@ async def _parallel_test_generate_faucet_wallet_custom_host_async_websockets(sel
             "wss://s.devnet.rippletest.net:51233"
         ) as client:
             await generate_faucet_wallet_and_fund_again(
-                self, client, "faucet.devnet.rippletest.net"
+                self,
+                client,
+                "faucet.devnet.rippletest.net",
+                usage_context="integration_test",
             )
 
     async def _parallel_test_generate_faucet_wallet_custom_host_async_json_rpc(self):
         client = AsyncJsonRpcClient("https://s.devnet.rippletest.net:51234")
         await generate_faucet_wallet_and_fund_again(
-            self, client, "faucet.devnet.rippletest.net"
+            self,
+            client,
+            "faucet.devnet.rippletest.net",
+            usage_context="integration_test",
         )
 
     def _parallel_test_generate_faucet_wallet_custom_host_sync_websockets(self):
@@ -167,7 +185,9 @@ async def _parallel_test_generate_faucet_wallet_hooks_v3_testnet_async_websocket
             if time_since_last_hooks_call < 10:
                 time.sleep(11 - time_since_last_hooks_call)
 
-            wallet = await generate_faucet_wallet(client)
+            wallet = await generate_faucet_wallet(
+                client, usage_context="integration_test"
+            )
             time_of_last_hooks_faucet_call = time.time()
 
             result = await client.request(
@@ -205,7 +225,9 @@ async def test_fund_given_wallet_hooks_v3_testnet_async_websockets(self):
                 time.sleep(11 - time_since_last_hooks_call)
             time_of_last_hooks_faucet_call = time.time()
 
-            new_wallet = await generate_faucet_wallet(client, wallet)
+            new_wallet = await generate_faucet_wallet(
+                client, wallet, usage_context="integration_test"
+            )
             new_result = await client.request(
                 AccountInfo(
                     account=new_wallet.classic_address,

xrpl/asyncio/wallet/wallet_generation.py

@@ -34,6 +34,8 @@ async def generate_faucet_wallet(
     wallet: Optional[Wallet] = None,
     debug: bool = False,
     faucet_host: Optional[str] = None,
+    usage_context: Optional[str] = None,
+    user_agent: Optional[str] = "xrpl-py",
 ) -> Wallet:
     """
     Generates a random wallet and funds it using the XRPL Testnet Faucet.
@@ -44,6 +46,12 @@ async def generate_faucet_wallet(
         debug: Whether to print debug information as it creates the wallet.
         faucet_host: A custom host to use for funding a wallet. In environments other
             than devnet and testnet, this parameter is required.
+        usage_context: The intended use case for the funding request
+            (for example, testing). This information  will be included
+            in the json body of the HTTP request to the faucet.
+        user_agent: A string representing the user agent (software/ client used)
+            for the HTTP request. Default is "xrpl-py".
+
 
     Returns:
         A Wallet on the testnet that contains some amount of XRP.
@@ -69,7 +77,7 @@ async def generate_faucet_wallet(
     starting_balance = await _check_wallet_balance(address, client)
 
     # Ask the faucet to send funds to the given address
-    await _request_funding(faucet_url, address)
+    await _request_funding(faucet_url, address, usage_context, user_agent)
     # Wait for the faucet to fund our account or until timeout
     # Waits one second checks if balance has changed
     # If balance doesn't change it will attempt again until _TIMEOUT_SECONDS
@@ -143,9 +151,17 @@ async def _check_wallet_balance(address: str, client: Client) -> int:
         raise
 
 
-async def _request_funding(url: str, address: str) -> None:
+async def _request_funding(
+    url: str,
+    address: str,
+    usage_context: Optional[str] = None,
+    user_agent: Optional[str] = None,
+) -> None:
     async with httpx.AsyncClient() as http_client:
-        response = await http_client.post(url=url, json={"destination": address})
+        json_body = {"destination": address, "userAgent": user_agent}
+        if usage_context is not None:
+            json_body["usageContext"] = usage_context
+        response = await http_client.post(url=url, json=json_body)
     if not response.status_code == httpx.codes.OK:
         response.raise_for_status()
 

xrpl/wallet/wallet_generation.py

@@ -12,6 +12,7 @@ def generate_faucet_wallet(
     wallet: Optional[Wallet] = None,
     debug: bool = False,
     faucet_host: Optional[str] = None,
+    usage_context: Optional[str] = None,
 ) -> Wallet:
     """
     Generates a random wallet and funds it using the XRPL Testnet Faucet.
@@ -22,6 +23,9 @@ def generate_faucet_wallet(
         debug: Whether to print debug information as it creates the wallet.
         faucet_host: A custom host to use for funding a wallet. In environments other
             than devnet and testnet, this parameter is required.
+        usage_context: The intended use case for the funding request
+            (for example, testing). This information will be included in json body
+            of the HTTP request to the faucet.
 
     Returns:
         A Wallet on the testnet that contains some amount of XRP.
@@ -33,4 +37,6 @@ def generate_faucet_wallet(
 
     .. # noqa: DAR402 exception raised in private method
     """
-    return asyncio.run(async_generate_faucet_wallet(client, wallet, debug, faucet_host))
+    return asyncio.run(
+        async_generate_faucet_wallet(client, wallet, debug, faucet_host, usage_context)
+    )