ALL CHANGES

.env.example

@@ -0,0 +1,3 @@
+RPC_URL=http://127.0.0.1:5050
+ADDRESS=0x000000000000000000000000000000000000000000000000000000000000000
+PRIVATE_KEY=0x000000000000000000000000000000000000000000000000000000000000000

.eslintrc.json

@@ -0,0 +1,12 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "extends": ["plugin:@typescript-eslint/recommended"],
+  "env": {
+    "node": true
+  },
+  "ignorePatterns": ["dist", "cairo"]
+}

.github/workflows/cairo-ci.yml

@@ -0,0 +1,26 @@
+name: Cairo CI
+
+on: push
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Step 1 - Check out main branch
+        uses: actions/checkout@v3
+      - name: Step 2 - Getting scarb
+        uses: software-mansion/[email protected]
+      - name: Step 3 - Setting up snfoundry
+        uses: foundry-rs/setup-snfoundry@v3
+      - name: Step 4 - Running tests
+        run: scarb test
+
+  format:
+    runs-on:  ubuntu-latest
+    steps:
+      - name: Step 1 - Check out main branch
+        uses: actions/checkout@v3
+      - name: Step 2 - Getting scarb
+        uses: software-mansion/[email protected]
+      - name: Step 3 - Checking format
+        run: scarb fmt --check

.github/workflows/integration-ci.yml

@@ -0,0 +1,64 @@
+name: Integration CI
+
+on: push
+
+jobs:
+  integration-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out main branch
+        uses: actions/checkout@v3
+
+      - name: Setup Scarb
+        uses: software-mansion/[email protected]
+
+      - name: Install project
+        run: yarn install --frozen-lockfile
+
+      - name: Start devnet in background
+        run: scarb run start-devnet
+
+      - name: Run integration tests
+        run: scarb --release build && tsc && yarn mocha tests-integration/*.test.ts --forbid-only --forbid-pending
+
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Step 1 - Check out main branch
+        uses: actions/checkout@v3
+
+      - name: Step 2 - Install project
+        run: yarn install --frozen-lockfile
+
+      - name: Step 3 - Check correct formatting
+        run: yarn prettier --check .
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Step 1 - Check out main branch
+        uses: actions/checkout@v3
+
+      - name: Step 2 - Install project
+        run: yarn install --frozen-lockfile
+
+      - name: Step 3 - Check correct linting
+        run: yarn eslint .
+
+  gas-report:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out main branch
+        uses: actions/checkout@v3
+
+      - name: Setup Scarb
+        uses: software-mansion/[email protected]
+
+      - name: Install project
+        run: yarn install --frozen-lockfile
+
+      - name: Start devnet in background
+        run: scarb run start-devnet
+
+      - name: Gas report
+        run: scarb run profile --check

.gitignore

@@ -0,0 +1,46 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules
+jspm_packages
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+.next
+
+# Cairo
+target
+.snfoundry_cache/
+
+.env
+dist
+.DS_STORE

.mocharc.json

@@ -0,0 +1,7 @@
+{
+  "extensions": ["ts"],
+  "test": ["tests/**.ts"],
+  "node-option": ["loader=ts-node/esm"],
+  "slow": 5000,
+  "timeout": 300000
+}

.nvmrc

@@ -0,0 +1 @@
+18

.prettierignore

@@ -0,0 +1,8 @@
+cairo
+venv
+target
+deployments/artifacts
+dist
+.github
+tests-integration/fixtures
+starknet-devnet-rs

.prettierrc

@@ -0,0 +1,9 @@
+{
+  "arrowParens": "always",
+  "useTabs": false,
+  "trailingComma": "all",
+  "singleQuote": false,
+  "semi": true,
+  "printWidth": 120,
+  "plugins": ["prettier-plugin-organize-imports"]
+}

.tool-versions

@@ -0,0 +1,2 @@
+scarb 2.6.3
+starknet-foundry 0.24.0

Dockerfile

@@ -0,0 +1,8 @@
+# Use the base image
+FROM shardlabs/starknet-devnet-rs:bab781a018318df51adb20fc60716c8429ee89b0
+
+# Expose port 5050
+EXPOSE 5050
+
+# Set default command to run the container
+CMD ["--gas-price", "36000000000", "--data-gas-price", "1", "--timeout", "320", "--seed", "0", "--lite-mode", "--gas-price-strk", "36000000000", "--data-gas-price-strk", "1"]

README.md

@@ -0,0 +1,118 @@
+# Starknet Gifting
+
+The goal of this protocol is to allow sending tokens to a recipient without knowing their address. This is done using a non-custodial escrow contract. Since the escrow contract functions as an account, it can pay for its own transactions, meaning the recipient doesn't need funds to initiate the claim. This is ideal for onboarding new users who can claim a gift to a newly created and even undeployed account.
+
+## High level Flow
+
+1. The sender creates a key pair locally called **gift_key**.
+2. The sender deposits the tokens to be transferred, along with a small amount of fee token (ETH or STK) to cover the claim transaction, to the factory. The sender also specifies the **public key** as an identifier.
+3. The factory deploys an escrow account to which the gift amount is transferred along with the fee amount.
+4. The sender shares the **private key** with the recipient over an external channel such as text or email.
+5. The recipient can claim the tokens by transferring them from the escrow account to their account using the private key to sign the transaction.
+
+As the fee should be larger than the claiming transaction cost, there might be a small amount of fee token left. We will refer to this leftover amount as "dust".
+
+## Deposits
+
+Deposits follow the flow described in the first 3 steps above.
+
+![Sessions diagram](/docs/deposit_diagram.png)
+
+For more details please see the `deposit` function at [Deposit example](./lib/deposit.ts).
+
+## Claiming
+
+Claiming can be done in two ways:
+
+### Internal claim
+
+The recipient uses the private key to craft a transaction to claim the gift. The `fee_amount` will be used to cover the transaction fees, so the recipient only gets the `gift_amount`. The recipient doesn’t need to have any funds in their wallet or even a deployed wallet to claim the gift using this method.
+
+![Sessions diagram](/docs/internal_claim.png)
+
+Edge cases:
+
+- Insufficient `fee_amount`: Alternative options are "external claiming", waiting for transaction price to go down, or canceling the gift (see below).
+- Dust: `fee_amount` will usually be higher than the actual fee and there will be some amount left in the contract. The protocol owner can collect the dust later.
+- If the internal claim transaction fails for any reason, the account won't allow to submit another transaction. But the gift can be cancelled or claimed using the external method.
+
+For more details about how to trigger it please see the `claimInternal` function at [Claim Internal Example](./lib/claim.ts).
+
+### External claim
+
+It is also possible for someone else to pay for the claim fees. This can be useful if the funds deposited to pay for the claim transaction are not enough, or if someone wants to subsidize the claim.
+
+The receiver can use the private key sign a message containing the address receiving the address (and optionally some address that will receive the dust). Using this signature, anybody can execute a transaction to perform the claim. To do so, they should call `claim_external` on the escrow account (through the `execute_action` entrypoint).
+
+![Sessions diagram](/docs/external_claim.png)
+
+For more details please see the `claimExternal` function at [Claim External Example](./lib/claim.ts).
+
+## Cancelling Gifts
+
+Gifts can be cancelled by the sender provided that they have not been claimed yet. The sender will retrieve both the `gift_amount` and the `fee_amount` they deposited for that gift.
+
+For more details please see the `cancelGift` function at [Cancel example](./lib/claim.ts).
+
+## Operator
+
+This section outlines all the operations that the factory owner is allowed to perform.
+
+### Claim Dust
+
+The operator can claim the dust left in an escrow account. This action can only be done after a claim has been performed.
+
+### Pause deposits
+
+The owner has the capability to pause all deposits. However, it cannot prevent any claims from happening, nor can it prevent any cancellations.
+
+### Upgrade
+
+The protocol can be upgraded to add new functionality or fix issues however, it can only be upgraded after a 7 day timelock. This prevents the owner from upgrading to a malicious implementation, as users will have enough time to leave the protocol by either claiming or cancelling their gifts.
+
+Through an upgrade, the owner can make the protocol non upgradeable in the future.
+
+## Escrow account address calculation
+
+To compute the address of the escrow account, you can either call `get_escrow_address()` with the relevant arguments. Or you can do it off-chain using, for example, starknetJS.  
+The parameters are as follow:
+
+- Salt: 0
+- Class hash: the class hash of the escrow account
+- Constructor calldata: The constructor argument used to deploy the escrow account
+- Deployer address: The address of the factory
+
+# Development
+
+## Local development
+
+We recommend you to install scarb through ASDF. Please refer to [these instructions](https://docs.swmansion.com/scarb/download.html#install-via-asdf).  
+Thanks to the [.tool-versions file](./.tool-versions), you don't need to install a specific scarb or starknet foundry version. The correct one will be automatically downloaded and installed.
+
+##@ Test the contracts (Cairo)
+
+```
+scarb test
+```
+
+### Install the devnet (run in project root folder)
+
+You should have docker installed in your machine then you can start the devnet by running the following command:
+
+```shell
+scarb run start-devnet
+```
+
+### Install JS dependencies
+
+Install all packages:
+
+```shell
+yarn
+```
+
+Run all integration tests:
+
+```shell
+scarb run test-ts
+```

Scarb.lock

@@ -0,0 +1,54 @@
+# Code generated by scarb DO NOT EDIT.
+version = 1
+
+[[package]]
+name = "alexandria_data_structures"
+version = "0.2.0"
+source = "git+https://github.com/keep-starknet-strange/alexandria.git?rev=cairo-v2.6.0#946e6e2f9d390ad9f345882a352c0dd6f02ef3ad"
+dependencies = [
+ "alexandria_encoding",
+]
+
+[[package]]
+name = "alexandria_encoding"
+version = "0.1.0"
+source = "git+https://github.com/keep-starknet-strange/alexandria.git?rev=cairo-v2.6.0#946e6e2f9d390ad9f345882a352c0dd6f02ef3ad"
+dependencies = [
+ "alexandria_math",
+ "alexandria_numeric",
+]
+
+[[package]]
+name = "alexandria_math"
+version = "0.2.0"
+source = "git+https://github.com/keep-starknet-strange/alexandria.git?rev=cairo-v2.6.0#946e6e2f9d390ad9f345882a352c0dd6f02ef3ad"
+dependencies = [
+ "alexandria_data_structures",
+]
+
+[[package]]
+name = "alexandria_numeric"
+version = "0.1.0"
+source = "git+https://github.com/keep-starknet-strange/alexandria.git?rev=cairo-v2.6.0#946e6e2f9d390ad9f345882a352c0dd6f02ef3ad"
+dependencies = [
+ "alexandria_math",
+]
+
+[[package]]
+name = "argent_gifting"
+version = "0.1.0"
+dependencies = [
+ "alexandria_math",
+ "openzeppelin",
+ "snforge_std",
+]
+
+[[package]]
+name = "openzeppelin"
+version = "0.13.0"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts.git?tag=v0.13.0#978b4e75209da355667d8954d2450e32bd71fe49"
+
+[[package]]
+name = "snforge_std"
+version = "0.24.0"
+source = "git+https://github.com/foundry-rs/starknet-foundry?tag=v0.24.0#95e9fb09cb91b3c05295915179ee1b55bf923653"