From 39d13da7da32aae86486fce0bf5a790af99fcaea Mon Sep 17 00:00:00 2001 From: Quinn Purdy Date: Fri, 28 Mar 2025 16:17:01 -0400 Subject: [PATCH 1/2] Added ADR to explain marketplace + pay architecture. Additionally, added a github action to embed the mermaid diagram in the Readme --- .../workflows/mermaid-diagrams-in-readme.yml | 31 +++++++++++++++++++ README.md | 27 ++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 .github/workflows/mermaid-diagrams-in-readme.yml diff --git a/.github/workflows/mermaid-diagrams-in-readme.yml b/.github/workflows/mermaid-diagrams-in-readme.yml new file mode 100644 index 000000000..487c8bcec --- /dev/null +++ b/.github/workflows/mermaid-diagrams-in-readme.yml @@ -0,0 +1,31 @@ +name: Update README with Mermaid Diagram + +on: + push: + branches: + - master + workflow_dispatch: + +jobs: + update-readme: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Insert Mermaid Diagram into README + run: | + echo '```mermaid' > temp.md + cat Packages/Sequence-Unity/Sequence/SequenceSDK/Marketplace/ERG_CheckoutModal.mmd >> temp.md + echo '```' >> temp.md + awk '//{system("cat temp.md"); next}1' README.md > updated.md + mv updated.md README.md + rm temp.md + + - name: Commit and push if changed + run: | + git config --global user.name "github-actions" + git config --global user.email "actions@github.com" + git add README.md + git diff --quiet && git diff --staged --quiet || git commit -m "Update README with latest Mermaid diagram" + git push diff --git a/README.md b/README.md index f20dbe206..19e65d375 100644 --- a/README.md +++ b/README.md @@ -191,6 +191,33 @@ To create a `ColorScheme` scriptable object, go to `Assets > Create > Sequence > Please add any ADRs below. In the future, it may be worthwhile to move these into separate files, but for now since there are few ADRs, the README should suffice. Please use [Michael Nygard's template for ADRs](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md) +### ADR 6 - Marketplace and Pay Ecosystem +March 28, 2025 - author: Quinn Purdy + +#### Status +Approved + +#### Context +We are adding a new suite of monetization-focused features to the Unity SDK. This ADR aims to explain the overall architecture of how these features have been implemented and why that architecture was chosen. + +#### Decision + +The overall payment ecosystem looks like this. + + + +#### Consequences + +Let's examine each layer of abstraction to understand some of the decision making here. + +First, and perhaps most obvious, are our base level abstractions: `ISwap`, `IMarketplaceReader`, and `ICheckout`. These interfaces and their implementations are the most basic integrations of the Sequence Marketplace and Swap APIs, segmented by functionality (swap, marketplace reading, and marketplace writing/checkout respectively). Higher-level abstractions rely upon the interfaces, not concrete implementations, to allow for unit testing of higher-level abstractions via injection of mocked implementations. While I don't expect that other concrete implementations are likely, this remains an option. + +You may notice that we have an `ISardineCheckout` but we don't have a similar interface for the Transak provider. This is due to some legacy code providing TransakOnRamp functionality; to make the changes more digestible to maintainers and advanced consumers of the SDK, we've opted to keep Transak changes more minimal and keep OnRamp and NftCheckout functionality separate. However, please keep in mind that we can, rather easily, introduce a similar interface should the need arise. + +Currently, the SDK integrates two different payment service providers, Transak and Sardine. These payment service providers provide a number of services including customer KYC, credit card payment processing + chargeback risk, and execution of smart contract code in a permissioned context with confirmation of payment; these services are exposed to Sequence in the form of cryptocurrency on-ramping and nft checkout products, allowing users to purchase cryptocurrencies + ERC20s and ERC721/ERC1155 collectibles respectively. An important insight is that both of these payment service providers have different integrations with different logic and have different supported regions (e.g. countries) and functionalities. For this reason, we introduced the `SequencePay` implementation and the `IFiatPay` interface. `SequencePay` is an implementation of the `IFiatPay` interface, as are `SardineFiatPay`, `TransakFiatPay`, and `UnsupportedPay`, but with some additional logic built in; `SequencePay` contains an `IFiatPayFactory` dependency (similar to above, we use an interface dependency for easy mocking) that, as implemented by `FiatPayFactory`, will determine which payment service provider(s), if any, support the desired functionality requested by the user by leveraging Sequence APIs and then will return the appropriate `IFiatPay` implementation for `SequencePay` to use as it's implementation. In addition to providing ease of use for integrators (as they don't need to worry about which payment service providers will work for a given user and operation), this architecture also makes it easy for us to add and remove payment service providers by simply providing an `IFiatPay` integration to the SDK and adding it to the `FiatPayFactory` creation logic (and upding the Sequence APIs accordingly, but this is outside of the scope of our SDK and can be thought of as a 'black box'). + +Perhaps the most unobvious part of the architecture is our highest-level of abstraction, specifically, you may wonder why `IFiatCheckout` and `ICheckoutHelper` exist as separate interfaces to be leveraged by our `CheckoutPanel` and `CheckoutPage` UI. This is to provide further flexibility in the future. As an example, the `CheckoutPage` logic and UI, given a sufficient implementation of `ICheckoutHelper` supports having multiple types of collectibles in your checkout 'cart' at one time. While the payment service providers don't currently support this, we can support this with crypto-based checkout by extending `PrimarySaleCheckout` and/or `NftCheckout` to support multiple collectibles while adhering to the same interface by essentially looping each collectible, and checkout transaction, through an `IEnumerable` of some sort and submitting the generated `Transaction[]` as a batch using the Embedded Sequence Wallets. Splitting fiat-based payment and checkout logic into separate interfaces also fits snuggly into the existing product segmentations, and assemblies, of Sequence Pay and Sequence Marketplaces, following the basic concept Domain Driven Design. + ### ADR 5 - SDK as a Local Package July 19, 2024 - author: Quinn Purdy From e3846e2c35d451fb9bd390c709edb64468ed7d40 Mon Sep 17 00:00:00 2001 From: Quinn Purdy Date: Fri, 28 Mar 2025 16:21:26 -0400 Subject: [PATCH 2/2] Embed the mermaid diagram directly into the ADR since it is timestamped --- .../workflows/mermaid-diagrams-in-readme.yml | 31 --------- README.md | 63 ++++++++++++++++++- 2 files changed, 62 insertions(+), 32 deletions(-) delete mode 100644 .github/workflows/mermaid-diagrams-in-readme.yml diff --git a/.github/workflows/mermaid-diagrams-in-readme.yml b/.github/workflows/mermaid-diagrams-in-readme.yml deleted file mode 100644 index 487c8bcec..000000000 --- a/.github/workflows/mermaid-diagrams-in-readme.yml +++ /dev/null @@ -1,31 +0,0 @@ -name: Update README with Mermaid Diagram - -on: - push: - branches: - - master - workflow_dispatch: - -jobs: - update-readme: - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@v3 - - - name: Insert Mermaid Diagram into README - run: | - echo '```mermaid' > temp.md - cat Packages/Sequence-Unity/Sequence/SequenceSDK/Marketplace/ERG_CheckoutModal.mmd >> temp.md - echo '```' >> temp.md - awk '//{system("cat temp.md"); next}1' README.md > updated.md - mv updated.md README.md - rm temp.md - - - name: Commit and push if changed - run: | - git config --global user.name "github-actions" - git config --global user.email "actions@github.com" - git add README.md - git diff --quiet && git diff --staged --quiet || git commit -m "Update README with latest Mermaid diagram" - git push diff --git a/README.md b/README.md index 19e65d375..a92bd4211 100644 --- a/README.md +++ b/README.md @@ -204,7 +204,68 @@ We are adding a new suite of monetization-focused features to the Unity SDK. Thi The overall payment ecosystem looks like this. - +```mermaid +graph TD + %% Define nodes and relationships + panel[CheckoutPanel] --> |has| modal + modal[CheckoutPage] --> |has| ch[ICheckoutHelper] + modal --> |has| fc[IFiatCheckout] + ch --> |implemented by| nc[NftCheckout] + ch --> |implemented by| psc[PrimarySaleCheckout] + nc --> |has| swap[ISwap] + nc --> |has| reader[IMarketplaceReader] + nc --> |has| checkout[ICheckout] + fc --> |implemented by| seqc[SequenceCheckout] + seqc --> |has| pay[SequencePay] + fp[IFiatPay] --> |implemented by| pay + pay --> |has| checkout + pay --> |has| fpf[IFiatPayFactory] + fpf --> |creates|fp + fp --> |implemented by| up[UnsupportedPay] + fp --> |implemented by| sfp[SardineFiatPay] + sfp --> |has| isc[ISardineCheckout] + isc --> |implemented by| sc[SardineCheckout] + fp --> |implemented by| tfp[TransakFiatPay] + tfp --> |has| tor[TransakOnRamp] + tfp --> |has| tnc[TransakNFTCheckout] + psc --> |has| pssft[ERC1155Sale] + psc --> |has| psnft[ERC721Sale] + fp --> |uses| pssft + fp --> |uses| psnft + psc --> |has| swap + + %% Subgraphs to group components + subgraph Marketplace + ch + nc + swap + reader + checkout + psc + end + subgraph Pay + fc + seqc + pay + fp + fpf + up + subgraph Transak + tfp + tor + tnc + end + subgraph Sardine + sfp + isc + sc + end + end + subgraph Ethereum/Contract + pssft + psnft + end +``` #### Consequences