\n\n# Sphere Protocol\n\nThis repository contains the open source code for Sphere's Lite Typescript SDK.\n\n# Documentation\n\n## Overview\n\nThis SDK enables you to create one-time payments for unit/credit based products, with the option of adding different pricing tiers (e.g., Basic, Developer, Enterprise), and the ability to pay in any currency.\n\nThere are additional utility functions to fetch quotes and create webhooks.\n\nWe also support both 'volume' and 'graduated' billing methods, if necessary. This [blog post](https://blog.fusebill.com/tiered-vs-volume-pricing-difference) explains what these mean.\n\n## Installation\n\n```bash\nnpm i @spherelabs/lite-sdk\n```\n\n## Integration\n\nAt a high-level, developers will:\n\n1. Create a product to describe the goods and services they are selling: including the cost, billing method, and pricing tiers if relevant.\n2. Create a button on your frontend to allow your customer to purchase your products.\n3. Create webhooks to receive payment events for your products.\n\n## Integration Guide\n\nWe will demonstrate the step-by-step flow for embedding the payments logic into a button.\n\n### 1. Setup\n\nCreate a script with the following:\n\n```typescript\nimport { Sphere } from '@spherelabs/lite-sdk';\n\nconst sphere = new Sphere({\n env: 'mainnet',\n rpcUrl: 'https://api.mainnet-beta.solana.com',\n signer: '3iJjsyYEDDhkvTNsnwJcVapXEv82Qqbh5BSCjZcamwwFLC9Gdw5rurQxtomLCEjwGHbWYk1p7yoihbQQGXeXsk1p',\n});\n\nvar product = await sphere.product.create({\n name: 'Service Credits',\n description: 'A product representing credits for your service',\n meta: {},\n images: ['http://localhost:8080/img1.png'],\n currency: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',\n taxRate: 0.01,\n billingMode: 'graduated',\n tiers: [\n {\n units: 1,\n price: 0.5,\n },\n {\n units: 3,\n price: 0.25,\n },\n {\n units: 5,\n price: 0.1,\n },\n ],\n});\nconsole.log(product.id);\n```\n\nKeep a note of your product's `id`. You will need to put this into your frontend.\n\n### 2. Frontend\n\nIn your React App, create the following \"product purchase\" `Button`:\n\n```typescript\nimport { useEffect, useState } from 'react';\nimport { Sphere } from '@spherelabs/lite-sdk';\nimport { useWallet } from '@solana/wallet-adapter-react';\n\nexport const Button = ({ units, id }: any) => {\n const reactWallet = useWallet();\n const [sphere, setSphere] = useState();\n const [txSig, setTxSig] = useState('');\n\n useEffect(() => {\n (async () => {\n if (reactWallet && reactWallet.connected) {\n try {\n const _sphere = new Sphere({\n env: 'mainnet',\n rpcUrl: 'https://solana-mainnet.g.alchemy.com/v2/UesFjy66kB4g4BEa1-JFNCEYIP_FxXvF',\n reactWallet,\n });\n setSphere(_sphere);\n await _sphere.prepareFrontend();\n } catch (error) {\n console.log(error);\n }\n }\n })();\n }, [reactWallet.connected]);\n\n const onClick = async () => {\n try {\n console.log(sphere);\n const _txSig = (await sphere?.product.purchase({\n id,\n units,\n })) as string;\n setTxSig(_txSig);\n } catch (error) {\n console.log(error);\n }\n };\n\n return (\n <>\n {txSig ? (\n
\n transactionSignature: \n \n {txSig}\n \n
\n ) : (\n \n )}\n \n );\n};\n```\n\nNow, you can put your button somewhere in your application:\n\n```typescript\n\n```\n\nUsers can click this button to purchase the product at a specified amount of units.\n\nWe have included a full [NextJS React App](https://github.com/Sphere-Laboratories/sphere-lite-client) to demonstrate this.\n\n### 3. Events\n\nSphere generates and stores purchase events every time your customers purchases a product. \n\n#### Event Payloads\n\nThe following is an example event body payload for product purchases with SPL tokens:\n\n```json\n{\n \"id\": \"event-a5c415c5-1d90-4dfe-99ee-c81538d61d2c\", \n \"product\": \"product-955d6030-f3e3-4aa1-a2cd-87eaab91a7c0\", \n \"transferType\": \"spl\", \n \"customer\": \"6VxGFK7NTv8tmRS2NvMNGAdqwkN5Q1b4X2qEk71Uf8N2\", \n \"merchant\": \"AEHY6aV66YoDMUbhnuXGPANyikooaQgm8spFAJro9AFV\", \n \"customerTokenAccount\": \"AxFuniPo7RaDgPH6Gizf4GZmLQFc4M5ipckeeZfkrPNn\", \n \"merchantTokenAccount\": \"34NsPzjUUMcnG8KAsuPhg6EqeLkmYTpJhpbUb9SRaBiJ\", \n \"currency\": \"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\", \n \"amount\": 10, \n \"fee\": 0.03, \n \"units\": 10, \n \"fromCurrency\": \"4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R\",\n \"txSig\": \"3ozMCwVProD2iksCAMNnfzdN5jGveEYfGjzKZw3UQmZQFPgyt39w2FuN2PPvtgbV2bzpanzss4zonPjKAbdy8etk\",\n \"created\": \"2023-02-08T02:51:54.405Z\"\n}\n```\n\nThe following is an example event body payload for product purchases with native SOL:\n\n\n```json\n{\n \"id\": \"event-a5c415c5-1d90-4dfe-99ee-c81538d61d2c\", \n \"product\": \"product-955d6030-f3e3-4aa1-a2cd-87eaab91a7c0\", \n \"transferType\": \"sol\", \n \"customer\": \"6VxGFK7NTv8tmRS2NvMNGAdqwkN5Q1b4X2qEk71Uf8N2\", \n \"merchant\": \"AEHY6aV66YoDMUbhnuXGPANyikooaQgm8spFAJro9AFV\", \n \"customerTokenAccount\": \"\", \n \"merchantTokenAccount\": \"\", \n \"currency\": \"So11111111111111111111111111111111111111111\", \n \"amount\": 10, \n \"fee\": 0.03, \n \"units\": 10, \n \"fromCurrency\": \"4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R\",\n \"txSig\": \"3ozMCwVProD2iksCAMNnfzdN5jGveEYfGjzKZw3UQmZQFPgyt39w2FuN2PPvtgbV2bzpanzss4zonPjKAbdy8etk\",\n \"created\": \"2023-02-08T02:51:54.405Z\"\n}\n```\n\n#### Retrieving Events\n\n\nWe have included several functions to retrieve your events. \n\nTo get all ids for your events, execute:\n\n```typescript\nconst ids: string[] = await sphere.event.getIds()\n```\n\nTo get all events associated to a given customer's publickey: \n\n```typescript\nconst events = await sphere.event.listByCustomer(\"OPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v\")\n```\nTo get all events associated to your infrastructure:\n\n```typescript\nconst events = await sphere.event.list()\n```\n\n\n### 4. Webhooks\n\nTo propagate purchase events to your API, you may use webhooks. To create a webhook execute the following:\n\n```typescript\nvar webhook = await sphere.webhook.create({\n name: 'Example Product Payments Webhook',\n description: 'Ingests product payment events',\n topics: ['sphere.events.product.purchase'],\n url: 'http://localhost:3000',\n});\n```\n\nWe support events of a single topic: `sphere.events.product.purchase`. These events are emitted on purchase of a product by one of your customers.\n\nEvents will be sent to your API at most 30 seconds after they have been confirmed onchain. If your API is unavaliable Sphere will attempt to deliver events 10 times with 1 second backoff period.\n\nYou may only create one webhook per signer. That is to say that, each merchant has at most 1 associated webhook.\n\n#### Signing Secrets\n\nWebhooks contain a signing secret which you may use to authenticate requests.\n\n```typescript\nconst signingSecret: string = webhook.secret;\n```\n\nPOST requests made to your API will contain this secret in the `Authorization` field of the request headers.\n\n\nYou may want to alter or disable your webhook when not in-use. To update your webhook:\n\n```typescript\nvar webhook = await sphere.webhook.update({\n name: 'Example Product Payments Webhook',\n description: 'Ingests product payment events',\n topics: ['sphere.events.product.purchase'],\n active: false,\n url: 'http://localhost:3000',\n});\n```\n\n#### 5. Development\n\nTo test your webhooks locally we recommend using a reverse proxy such as [ngrok](https://ngrok.com) to create a secure tunnel between a publically exposed endpoint and your API.\n\n## Swaps\n\nWe support Token Swaps via [Jupiter](https://jup.ag/) for product purchases. Hence, your customers can pay in the currency of their choice.\n\nTo include a swap in a product purchase, select the `fromCurrency` that the customer is paying in, which they can specify on your frontend. We should note that the merchant will receive the `currency` originally specified on creation of the product.\n\n```typescript\nconst txSig = await sphere.product.purchase({\n id: product.id,\n units: 2,\n swap: {\n fromCurrency: '4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R',\n },\n});\n```\n\nWhen using the swap feature, you may wish to display price quotes to your users given the price structure of your product (e.g., the number of units they want to buy and the currency they wish to pay in). To get a quote in the `fromCurrency` for a given amount of units:\n\n```typescript\nconst quote = await sphere.product.quote({\n id: product.id,\n fromCurrency: '4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R',\n units: 5,\n});\n```\n\n## Billing Modes\n\n### Graduated\n\nConsider the following graduated tier pricing structure:\n \nUnits [0-100] have a price per unit of 1\n \nUnits [101-250] have a price per unit of 2\n \nUnits [251+] have a price per unit of 3\n \n\nSo if the customer uses 300 units, the total will be: 100(1) + 150(2) + 50(3) = 550.\n\nThis tier structure will have the following array encoding:\n\n```typescript\nconst tiers = [\n {\n price: 1,\n units: 100,\n },\n {\n price: 2,\n units: 150,\n },\n {\n price: 3,\n units: 250,\n },\n];\n```\n\n### Volume\n\nConsider the following volume tiered pricing structure:\n \nUnits [0-100] have a price per unit of 1\n \nUnits [101-250] have a price per unit of 2\n \nUnits [251+] have a price per unit of 3\n \n\nSo if the customer uses 300 units, the total will be: 3(300) = 900. Alternatively, if they use 50 units, the total will be 50(1) = 50.\n\nThis tier structure will have the following array encoding:\n\n```typescript\nconst tiers = [\n {\n price: 1,\n units: 0,\n },\n {\n price: 2,\n units: 100,\n },\n {\n price: 3,\n units: 250,\n },\n];\n```\n\nNotice that for volume based billing, the units specified indicate the point at which the given price kicks in (e.g., after the first 100 units, the price becomes 2 instead of 1). This is unlike graduated billing, where the units specify the amount of units that can be consumed at a given price point (e.g., the first 100 units are allocated the price 1, and the next 150 are allocated price 2). In other words, **graduated billing defines units by an upper limit per tier,** whereas **volume based billing defines units by a lower bound per tier.** The reason for this difference is because in volume based billing, the pricing is set by the most recent tier. Hence, without using a lower limit, it would be unclear how many units to specify for the final tier.\n\nTo illustrate, if volume based billing used the same upper limit method as graduated:\n\n```typescript\nconst tiers = [\n {\n price: 1,\n units: 100\n },\n {\n price: 2,\n units: 250\n },\n {\n price: 3,\n units: ?\n },\n]\n```\n\nHence, the last tier's units would be undefined. This is why we use a lower limit for this billing method.\n\n## Fees\n\nSphere charges a fee of 0.3% for all transfers using our infrastructure.\n\n## License\n\nSphere Protocol is licensed under [MIT LICENSE](./LICENSE).\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in Sphere SDK by you, as defined in the MIT license, shall be\nlicensed as above, without any additional terms or conditions.\n","readmeFilename":"README.md"}
![\"Sphere\"](\"https://avatars.githubusercontent.com/u/109333730?s=200&v=4\")
\n \n ![\"Docs\"](\"https://img.shields.io/badge/docs-tutorials-aquamarine\"){kind=icon}
![\"License\"](\"https://img.shields.io/github/license/git-scm/git-scm.com?color=aquamarine\")