feat(delegated payments): init managing and using delegate payment approvals PE-6754

[fedellen]

This PR implements delegated payments into the Turbo SDK and CLI

here are CLI examples, create an approval to a valid SOL/ETH/POL/AR/KYVE address:

> node lib/esm/cli/cli.js create-approval --address 2cor8AZxm38uc9sVgGaXk4BU2EtB18FqwEq7ivwa7VUa --value 0.008 --wallet-file ../wallets/zarweave-keyfile-jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU_dereks.json
{
  "message": "Created delegated payment approval!",
  "approvalDataItemId": "pdXRmDue07mX77m7GcgAz2z0esym8H_2-hshs8H454k",
  "approvedAddress": "2cor8AZxm38uc9sVgGaXk4BU2EtB18FqwEq7ivwa7VUa",
  "approvedWincAmount": "8000000000",
  "creationDate": "2024-10-31T15:04:15.898Z",
  "payingAddress": "jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU",
  "usedWincAmount": "0"
}

controlled winc is reflected in balance command:

> node lib/esm/cli/cli.js balance --address jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU
Turbo Balance for Native Address "jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU"
Effective Credits: 1.9325555055
Credits Shared to Other Wallets: 0.016

list all given or received approvals:

> node lib/esm/cli/cli.js list-approvals --address jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU
{
  "message": "Delegated payment approvals found for native address 'jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU'",
  "givenApprovals": [
    {
      "approvalDataItemId": "mwgQ-TfeLoIzyR_C864RKaq2sZmDrx-xBFqcsbDwgDA",
      "approvedAddress": "2cor8AZxm38uc9sVgGaXk4BU2EtB18FqwEq7ivwa7VUa",
      "approvedWincAmount": "8000000000",
      "creationDate": "2024-10-31T14:55:46.889Z",
      "payingAddress": "jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU",
      "usedWincAmount": "0"
    },
    {
      "approvalDataItemId": "pdXRmDue07mX77m7GcgAz2z0esym8H_2-hshs8H454k",
      "approvedAddress": "2cor8AZxm38uc9sVgGaXk4BU2EtB18FqwEq7ivwa7VUa",
      "approvedWincAmount": "8000000000",
      "creationDate": "2024-10-31T15:04:15.898Z",
      "payingAddress": "jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU",
      "usedWincAmount": "0"
    }
  ],
  "receivedApprovals": []
}

revoke all active approvals to a given address:

> node lib/esm/cli/cli.js revoke-approvals --address 2cor8AZxm38uc9sVgGaXk4BU2EtB18FqwEq7ivwa7VUa --wallet-file ../wallets/zarweave-keyfile-jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU_dereks.json      
{
  "message": "Revoked delegated payment approvals!",
  "revokedApprovals": [
    {
      "approvalDataItemId": "mwgQ-TfeLoIzyR_C864RKaq2sZmDrx-xBFqcsbDwgDA",
      "approvedAddress": "2cor8AZxm38uc9sVgGaXk4BU2EtB18FqwEq7ivwa7VUa",
      "approvedWincAmount": "8000000000",
      "creationDate": "2024-10-31T14:55:46.889Z",
      "payingAddress": "jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU",
      "usedWincAmount": "0",
      "inactiveReason": "revoked",
      "inactiveDate": "2024-10-31T15:08:22.317Z",
      "revokeDataItemId": "rGSmUJmYALnMTdGF-V_nnwKLjxgMpqY4neNZByQSa_U"
    },
    {
      "approvalDataItemId": "pdXRmDue07mX77m7GcgAz2z0esym8H_2-hshs8H454k",
      "approvedAddress": "2cor8AZxm38uc9sVgGaXk4BU2EtB18FqwEq7ivwa7VUa",
      "approvedWincAmount": "8000000000",
      "creationDate": "2024-10-31T15:04:15.898Z",
      "payingAddress": "jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU",
      "usedWincAmount": "0",
      "inactiveReason": "revoked",
      "inactiveDate": "2024-10-31T15:08:22.317Z",
      "revokeDataItemId": "rGSmUJmYALnMTdGF-V_nnwKLjxgMpqY4neNZByQSa_U"
    }
  ]
}

using payment approvals, by default on upload the CLI will use any received approvals before the signer's balance. the SDK will NOT do so, but integrating apps can choose to do so. To override the paid-by behavior CLI users can supply --paid-by,

> node lib/esm/cli/cli.js upload-file -f ../uploads/460KB.txt --wallet-file ../wallets/sol.keypair.2cor8AZxm38uc9sVgGaXk4BU2EtB18FqwEq7ivwa7VUa.json --token solana --paid-by jaxl_dxqJ00gEgQazGASFXVRvO4h-Q0_vnaLtuOUoWU

or use one of two flags,

• --ignore-approvals will skip any check for approvals, using only the signer's balance
• --use-signer-balance-first will put the signer at the start of the paid-by list, and then put any received approvals after. this is a helper for using the end of a user's balance (dust)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.82%. Comparing base (5fb1856) to head (b060b78).
Report is 54 commits behind head on alpha.

Additional details and impacted files

@@            Coverage Diff             @@
##            alpha     #191      +/-   ##
==========================================
+ Coverage   93.26%   93.82%   +0.56%     
==========================================
  Files          25       25              
  Lines        3250     3483     +233     
  Branches      148      159      +11     
==========================================
+ Hits         3031     3268     +237     
+ Misses        219      215       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[dtfiedler]

🎉 This PR is included in version 1.20.0-alpha.1 🎉

The release is available on:

• npm package (@alpha dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[dtfiedler]

🎉 This PR is included in version 1.20.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀