feat: grant spent amounts (#3757)

* feat: add grant spent amount table (#3389)

* feat: add grant spent amount table

* fix: change interval start/end string to timestamp

* feat: fix filename, update op grant table

* fix: rm erroneously added migration to tsconfig

* feat: calculate grant spent amounts from new table (#3412)

* feat: calculate grant spent amounts from new table

* chore: linting

* fix: revise grant spent amounts calc to track interval

* fix: throw better error, dont inti interval amounts unless they exist

* fix: linter, wip commented out code

* refactor(backend): rename interval statuses

* fix: ensure correct amount (interval/total) is used for grant spent amount

* test(backend): grant spent amounts

* fix(backend): make logic more typesafe, avoid having to defend w/ internal server error

* test(backend): legacy grant calculations

* test(backend): classify payment interval fn

* test(backend): rm commented-out classify payment interval case

* refactor(backend): improve semantics of interval helper fn

* test(backend): add non-interval cases to create op

* Apply suggestions from code review

Co-authored-by: Max Kurapov <max@interledger.org>

* refactor: simplifiy interval calc

* chore: rm unused imports

* refactor: validate grant payment logic

* refactor: improve grant spent amount calc type safety

* refactor: improve grant spent amount calc type safety

* fix: missing trx

* chore: handle bad interval state

* chore: rm some superfluous comments

* chore: format

---------

Co-authored-by: Max Kurapov <max@interledger.org>

* feat: handle grant spent amount calculation on payment completion (#3674)

* feat: calculate grant spent amounts from new table

* chore: linting

* fix: revise grant spent amounts calc to track interval

* fix: throw better error, dont inti interval amounts unless they exist

* fix: linter, wip commented out code

* refactor(backend): rename interval statuses

* fix: ensure correct amount (interval/total) is used for grant spent amount

* test(backend): grant spent amounts

* fix(backend): make logic more typesafe, avoid having to defend w/ internal server error

* test(backend): legacy grant calculations

* test(backend): classify payment interval fn

* test(backend): rm commented-out classify payment interval case

* refactor(backend): improve semantics of interval helper fn

* test(backend): add non-interval cases to create op

* Apply suggestions from code review

Co-authored-by: Max Kurapov <max@interledger.org>

* feat: partially handled grant spent amount scenarios on settle

* feat: handle non-interval partial settleamount cases

* test(backend): failure grant spent amount case for sucessive payment

* test(backend): some grant calc interval cases

* test(backend): counting grant payments across interval boundaries

* chore(backend): rm commented out test

* test(backend): new grant spent amount on payment completion

* test(backend): improve interval grant calc test to show summation

* test(backend): failure edge case

* chore(backend): rm comment

* chore(backend): fix lint errors

* chore(backend): rm debug logs

* test(backend): fix failing

* Update packages/backend/src/open_payments/payment/outgoing/lifecycle.ts

Co-authored-by: Max Kurapov <max@interledger.org>

* fix(backend): rm extra spent amount record check

* feat(backend): return debit amount from .pay

* test(backend): failing test for grant spent amount bug

- if 2 payments are create then 2 payments are processed,
it assocaites the wrong spent amount with the wrong payment

* fix(backend): grant spent amounts calc race conditions

- partially implemented fix (missing interval stuff),
not fully validated by tests yet

* test(backend): grant calc race condition

* fix(backend): grant spent amount race conditions with failure

* chore(backend): format

* test(backend): add failing interval race condition test

* fix(backend): interval boundary/race condition edge case

- edge case is when there are create/complete race conditions around interval boundaries

* test(backend): improve edge case test

- ensures we are testing that the latest interval amount is
used as the base for interval amounts, not just the payment
in the interval being completed

* fix(backend): dont query for latest interval payment unecunnecessarily

- not necessary if we are within the interval of the payment being completed

* fix(backend): type mismatch

* test(backend): payment retries do not add additional spent record

* fix(backend): use correct debit
amount for spent amount recalc

* fix(backend): set correct payment state on
grant spent amount updates

* refactor(backend): dedupe revert/handle grant spent amounts

- turned duplicated logic into shared functions
- example fn where revert/update is all in one,
but felt it was more complicated

* chore: rm unused fn

* test(backend): fix ilp pay return expectations

* refactor(backend): move revert/update grant spent amounts to op service

* chore: rm unused import

* fix: handle grant spent amounts on payment cancellation

* chore: cleanup commented out code

* chore: rm submodule added in error

* chore(backend): add error logs

* fix(backend): explicit grant spent amount formation, more test assertions

* refactor(backend): only return receive amt from .pay

* fix(backend): build error

---------

Co-authored-by: Max Kurapov <max@interledger.org>

* fix: test to use tenantid

* fix: update lifecycle tests for mt

* feat: use new open payments spec version

* fix: failing lifecycle tests

* feat: add /GET outgoing-payment-grant route (#3756)

* feat: add /GET outgoing-payment-grant route

* fix: change null state return to return null

* fix: rm old comments

* fix: add get grant spent amount service tests

* fix: add get grant spent amount controller tests

* fix(backend): linter

* fix(backend): tenanted path

* fix: dont require identifier in outgoing payment access item introspection

* feat(backend): rm unecessary check

* test(auth): add test

* test(backend): add middleware test

* refactor(backend): cleanup grant spent amount retrieval

* chore: fix lint

* test(backend): fix grant id check

* test(backend): simplify logic, return 0 amount when able

* refactor(backend): token introspection middleware

- make 2nd introspection middleware for
new route instead of generalizing exisitng middleware

* test(backend): rm no longer needed test

* fix: rm unused import

* Update packages/backend/src/open_payments/auth/middleware.ts

Co-authored-by: Max Kurapov <max@interledger.org>

* fix: return 403 for non create grant for spent amounts

used to return null spent amounts

* fix: add logs, use luxon interval method

* fix: scope of else block

* Update packages/backend/src/open_payments/auth/middleware.ts

Co-authored-by: Max Kurapov <max@interledger.org>

* chore: fix name

* feat: test for new middleware/shared fn

* chore: make action required

---------

Co-authored-by: Max Kurapov <max@interledger.org>

* fix: import

* chore: fix typo in bruno folder

* fix: calculate legacy path in get spent amounts

* refactor: simplifiy get grant spent amounts logic

* fix: migrate legacy payments

* fix: use trx

* test(backend): ensure middleware next is called

* fix(backend): fix potential precision loss

* feat: add metric to unexpected state (that doesnt error)

* ci: debug

* ci: revert debug

---------

Co-authored-by: Max Kurapov <max@interledger.org>

Author: BlairCurrey

bruno/collections/Rafiki/Examples/Vailidating Wallet Address Ownership with Open Payments/folder.bru

@@ -1,4 +1,4 @@
 meta {
-  name: Vailidating Wallet Address Ownership with Open Payments
+  name: Validating Wallet Address Ownership with Open Payments
   seq: 6
 }

bruno/collections/Rafiki/Open Payments APIs/Outgoing Payment Grant/Get Outgoing Payment Grant.bru

@@ -0,0 +1,33 @@
+meta {
+  name: Get Outgoing Payment Grant
+  type: http
+  seq: 1
+}
+
+get {
+  url: {{senderOpenPaymentsHost}}/outgoing-payment-grant
+  body: json
+  auth: none
+}
+
+headers {
+  Authorization: GNAP {{accessToken}}
+}
+
+script:pre-request {
+  const scripts = require('./scripts');
+  
+  scripts.addHostHeader();
+  
+  await scripts.addSignatureHeaders();
+}
+
+tests {
+  test("Status code is 201", function() {
+    expect(res.getStatus()).to.equal(200);
+  });
+}
+
+docs {
+  Uses GNAP access token to determine the grant.
+}

open-payments-specifications

@@ -296,6 +296,27 @@ describe('Access utilities', (): void => {
     ).toBe(false)
   })
 
+  test('access comparison does not fail if no request identifier', async (): Promise<void> => {
+    const grantAccessItemSuperAction = await Access.query(trx).insertAndFetch({
+      grantId: grant.id,
+      type: AccessType.IncomingPayment,
+      actions: [AccessAction.ReadAll],
+      identifier
+    })
+
+    const requestAccessItem: AccessItem = {
+      type: 'incoming-payment',
+      actions: [AccessAction.ReadAll]
+    }
+
+    expect(
+      compareRequestAndGrantAccessItems(
+        requestAccessItem,
+        toOpenPaymentsAccess(grantAccessItemSuperAction)
+      )
+    ).toBe(true)
+  })
+
   test('access comparison fails if type mismatch', async (): Promise<void> => {
     const grantAccessItemSuperAction = await Access.query(trx).insertAndFetch({
       grantId: grant.id,

packages/auth/src/access/utils.test.ts

@@ -57,6 +57,7 @@ export function compareRequestAndGrantAccessItems(
 
   if (
     grantAccessIdentifier &&
+    requestAccessIdentifier &&
     requestAccessIdentifier !== grantAccessIdentifier
   ) {
     return false

packages/auth/src/access/utils.ts

@@ -0,0 +1,41 @@
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.up = function (knex) {
+  return knex.schema
+    .createTable('outgoingPaymentGrantSpentAmounts', function (table) {
+      table.uuid('id').notNullable().primary()
+      table.string('grantId').notNullable()
+      table.foreign('grantId').references('outgoingPaymentGrants.id')
+      table.uuid('outgoingPaymentId').notNullable()
+      table.foreign('outgoingPaymentId').references('outgoingPayments.id')
+      table.integer('receiveAmountScale').notNullable()
+      table.string('receiveAmountCode').notNullable()
+      table.bigInteger('paymentReceiveAmountValue').notNullable()
+      table.bigInteger('intervalReceiveAmountValue').nullable()
+      table.bigInteger('grantTotalReceiveAmountValue').notNullable()
+      table.integer('debitAmountScale').notNullable()
+      table.string('debitAmountCode').notNullable()
+      table.bigInteger('paymentDebitAmountValue').notNullable()
+      table.bigInteger('intervalDebitAmountValue').nullable()
+      table.bigInteger('grantTotalDebitAmountValue').notNullable()
+      table.string('paymentState').notNullable()
+      table.timestamp('intervalStart').nullable()
+      table.timestamp('intervalEnd').nullable()
+      table.timestamp('createdAt').defaultTo(knex.fn.now())
+    })
+    .then(() => {
+      return knex.raw(
+        'CREATE INDEX outgoingPaymentGrantSpentAmounts_grantId_createdAt_desc_idx ON "outgoingPaymentGrantSpentAmounts" ("grantId", "createdAt" DESC)'
+      )
+    })
+}
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = function (knex) {
+  return knex.schema.dropTableIfExists('outgoingPaymentGrantSpentAmounts')
+}

packages/backend/migrations/20250409173617_add_outgoing_payment_grant_spent_amounts_table.js

@@ -0,0 +1,19 @@
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.up = function (knex) {
+  return knex.schema.alterTable('outgoingPaymentGrants', function (table) {
+    table.string('interval').nullable()
+  })
+}
+
+/**
+ * @param { import("knex").Knex } knex
+ * @returns { Promise<void> }
+ */
+exports.down = function (knex) {
+  return knex.schema.alterTable('outgoingPaymentGrants', function (table) {
+    table.dropColumn('interval')
+  })
+}

packages/backend/migrations/20250410162417_add_interval_op_grant_table.js

@@ -30,7 +30,8 @@ import {
   httpsigMiddleware,
   Grant,
   RequestAction,
-  authenticatedStatusMiddleware
+  authenticatedStatusMiddleware,
+  createOutgoingPaymentGrantTokenIntrospectionMiddleware
 } from './open_payments/auth/middleware'
 import { RatesService } from './rates/service'
 import { createSpspMiddleware } from './payment-method/ilp/spsp/middleware'
@@ -134,13 +135,16 @@ export type AppRequest<ParamsT extends string = string> = Omit<
   params: Record<ParamsT, string>
 }
 
-export interface WalletAddressUrlContext extends AppContext {
-  walletAddressUrl: string
+export interface IntrospectionContext extends AppContext {
   grant?: Grant
   client?: string
   accessAction?: AccessAction
 }
 
+export interface WalletAddressUrlContext extends IntrospectionContext {
+  walletAddressUrl: string
+}
+
 export interface WalletAddressContext extends WalletAddressUrlContext {
   walletAddress: WalletAddress
 }
@@ -715,6 +719,16 @@ export class App {
       outgoingPaymentRoutes.get
     )
 
+    // GET /outgoing-payment-grant
+    // Get grant spent amounts (scoped to interval, if any) from grant
+    // with outgoing payment create access
+    router.get(
+      '/:tenantId/outgoing-payment-grant',
+      // Expects token used for outgoing payment payment creation
+      createOutgoingPaymentGrantTokenIntrospectionMiddleware(),
+      outgoingPaymentRoutes.getGrantSpentAmounts
+    )
+
     // GET /quotes/{id}
     // Read quote
     router.get<DefaultState, SignedSubresourceContext>(