feat(pg): deployment artifacts core logic

.changeset/loud-rings-wait.md

@@ -0,0 +1,8 @@
+---
+'@sphinx-labs/contracts': minor
+'@sphinx-labs/plugins': minor
+'@sphinx-labs/core': minor
+'@sphinx-labs/demo': minor
+---
+
+Add core logic for deployment artifacts

.eslintrc.js

@@ -23,7 +23,7 @@ module.exports = {
   ],
   overrides: [
     {
-      files: ['**/*.ts','**/*.tsx'],
+      files: ['**/*.ts', '**/*.tsx'],
       parser: '@typescript-eslint/parser',
       parserOptions: {
         project: './packages/**/tsconfig.json',
@@ -137,6 +137,16 @@ module.exports = {
     'no-new-func': 'error',
     'no-new-wrappers': 'error',
     'no-redeclare': 'error',
+    // Disallow BigInt literals: Ensures compatibility with JavaScript environments that do not
+    // support ES2020's BigInt literal syntax (e.g., 123n). This is important for maintaining
+    // broader support across various runtime environments, including older Node.js versions.
+    'no-restricted-syntax': [
+      'error',
+      {
+        selector: 'Literal[bigint]',
+        message: 'BigInt literals are not allowed.',
+      },
+    ],
     'no-return-await': 'error',
     'no-sequences': 'error',
     'no-sparse-arrays': 'error',

README.md

@@ -63,9 +63,8 @@ Sphinx is currently invite-only. [Request access on our website.](https://sphinx
 ## Coming Soon
 
 - Use existing Gnosis Safes with Sphinx.
-- Download deployment artifacts from the DevOps platform.
-- Pay for deployments with USDC on the DevOps platform.
-- Deploy from the CLI on networks that the DevOps platform doesn't support.
+- Pay for deployments with USDC on the DevOps Platform.
+- Deploy from the CLI on networks that the DevOps Platform doesn't support.
 
 Please feel free to reach out to us in our [Discord](https://discord.gg/7Gc3DK33Np) to request a feature!
 

docs/architecture-overview.md

@@ -60,7 +60,7 @@ graph LR
 
 This Merkle tree contains a deployment on two chains. There are three transactions to execute on each chain.
 
-You'll notice that the "Approve" leaves contain an "executor" field. The executor is an address with sole permission to execute the deployment. The executor will be Sphinx's backend if you use the DevOps platform.
+You'll notice that the "Approve" leaves contain an "executor" field. The executor is an address with sole permission to execute the deployment. The executor will be Sphinx's backend if you use the DevOps Platform.
 
 You'll also notice that each Merkle leaf has an `index`. The Merkle leaves must be executed in ascending order according to their indexes on any given chain.
 

docs/ci-proposals.md

@@ -18,7 +18,7 @@ We'll use GitHub Actions as the CI platform in this guide. You can still follow
 6. [Create the proposal workflow](#6-create-the-proposal-workflow)
 7. [Configure secret variables](#7-configure-secret-variables)
 8. [Test your integration](#8-test-your-integration)
-9. [Production Deployments](#9-production-deployments)
+9. [Production deployments](#9-production-deployments)
 
 ## 1. Prerequisites
 
@@ -83,7 +83,7 @@ jobs:
       - name: Install Dependencies
         run: yarn --frozen-lockfile
       - name: Dry Run
-        run: npx sphinx propose <path/to/your/script.s.sol> --dry-run --testnets
+        run: npx sphinx propose <path/to/your/script.s.sol> --dry-run --networks testnets
 ```
 
 Here is a list of things you may need to change in the template:
@@ -122,7 +122,7 @@ jobs:
       - name: Install Dependencies
         run: yarn --frozen-lockfile
       - name: Propose
-        run: npx sphinx propose <path/to/your/script.s.sol> --confirm --testnets
+        run: npx sphinx propose <path/to/your/script.s.sol> --confirm --networks testnets
 ```
 
 Here is a list of things you may need to change in the template:
@@ -137,14 +137,15 @@ Here is a list of things you may need to change in the template:
 You must add a few variables as secrets in your CI process. If you're not sure how to add secrets, [see here for a guide by GitHub on storing secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
 
 Here is the list of secrets to add:
-- `SPHINX_API_KEY`: You can find this in the Sphinx UI after registering your organization.
+- `SPHINX_API_KEY`: After registering your organization, you can find this in the Sphinx UI under "Options" -> "API Credentials"
 - RPC node provider API keys for all target networks. Node providers like Alchemy generally use one API key across all networks they support.
 
 ## 8. Test your integration
 
-Push your branch to GitHub, open a PR, and merge it after the dry run succeeds. Then, you go to the [Sphinx UI](https://www.sphinx.dev) to approve your deployment.
+Push your branch to GitHub, open a PR, and merge it after the dry run succeeds. Then, go to the [Sphinx UI](https://www.sphinx.dev) to approve your deployment.
 
-## 9. Production Deployments
-In this guide, we've configured the CI process to deploy against test networks. If you want to go straight to production, you can switch the `--testnets` flag with the `--mainnets` flag in both templates.
+## 9. Production deployments
 
-In practice, you may want something different depending on your workflow. For a more robust setup, we recommend using a `develop` branch and triggering testnet deployments when merging to that branch. We recommend using a separate workflow that triggers deployments on production networks when you merge from your `develop` branch to `main`.
+In this guide, we've configured the CI process to deploy against test networks. When you're ready to deploy in production, simply update the `sphinx propose` command to include `--networks mainnets` instead of `--networks testnets`. Make sure you update both templates.
+
+In practice, we recommend triggering testnet deployments when merging to your development branch, and triggering production deployments when you merge from your development branch to your main branch.

docs/cli-deployments.md

@@ -1,9 +1,9 @@
 # Deploy from the CLI
 
-Sphinx has a CLI command for executing deployments from your local machine without using the DevOps platform. There are two main reasons to use it:
+Sphinx has a CLI command for executing deployments from your local machine without using the DevOps Platform. There are two main reasons to use it:
 
 1. Deploy on Anvil. Sphinx will broadcast the deployment even if you aren't one of the Gnosis Safe owners.
-2. Deploy on live networks. This can be useful if you'd like to deploy a Gnosis Safe and generate deployment artifacts. Since you aren't using the DevOps platform, you'll need native gas tokens for the deployment, and you'll need to verify your contracts on Etherscan. Note that you can only deploy from the CLI on live networks if you're the only owner of the Gnosis Safe.
+2. Deploy on live networks. This can be useful if you'd like to deploy a Gnosis Safe and generate deployment artifacts. Since you aren't using the DevOps Platform, you'll need native gas tokens for the deployment, and you'll need an Etherscan API key to verify your contracts. Note that you can only deploy from the CLI on live networks if you're the only owner of the Gnosis Safe.
 
 You can execute a Forge script on a network using the `deploy` command.
 
@@ -24,5 +24,5 @@ The following steps will occur when you run this command:
 1. The command will simulate the deployment by invoking the script's `run()` function on a fork of the specified network. It will collect the broadcasted transactions.
 2. Sphinx will display the collected transactions in a preview, which you'll be prompted to confirm. You can skip the preview by including a `--confirm` flag when you run the command.
 3. Foundry will broadcast the transactions on the target network through your Gnosis Safe.
-4. Sphinx will write deployment artifacts to the file path: `./deployments/anvil-<chain_id>/<ContractName>.json`.
+4. Sphinx will write deployment artifacts to your file system. See the [Deployment Artifacts](https://github.com/sphinx-labs/sphinx/blob/main/docs/deployment-artifacts.md) guide for more information.
 5. (Optional): You can verify contracts on Etherscan by including a `--verify` flag.

docs/cli-existing-project.md

@@ -2,13 +2,13 @@
 
 In this guide, you'll integrate Sphinx with your existing Foundry project. Then, you'll deploy your project on a few testnets.
 
-Deployments are a three-step process with the DevOps platform:
+Deployments are a three-step process with the DevOps Platform:
 
-1. **Propose**: Initiate the deployment from your command line or CI process by submitting the transactions to Sphinx's backend.
-2. **Approve**: Your Gnosis Safe owner(s) approve the deployment by signing a single meta transaction in the Sphinx UI.
+1. **Propose**: Initiate the deployment by submitting it to Sphinx's backend from your command line or CI process.
+2. **Approve**: Your Gnosis Safe owner(s) approve the deployment in the Sphinx UI by signing the deployment's unique identifier with a meta transaction. This unique identifier is the root of a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree), which contains all the transaction data for the deployment across every chain.
 3. **Execute**: Sphinx's backend trustlessly executes the deployment through your Gnosis Safe.
 
-In this guide, you'll propose the deployment on the command line then approve it in the Sphinx UI.
+In this guide, you'll propose the deployment on the command line and then approve it in the Sphinx UI.
 
 ## Table of Contents
 
@@ -138,7 +138,7 @@ Remove any `vm.startBroadcast` and `vm.broadcast` calls from your deployment scr
 
 ### e. Handle new sender address
 
-When using Sphinx, your deployment will be executed from your Gnosis Safe. In other words, the `msg.sender` of your transactions will be your Gnosis Safe. You may need to make updates to your script if it relies on a particular sender address. If you need to access your Gnosis Safe address, you can fetch it in your script using `sphinxSafe()`.
+When using Sphinx, your deployment will be executed from your Gnosis Safe. In other words, the `msg.sender` of your transactions will be your Gnosis Safe. You may need to update your script if it relies on a particular sender address. If you need to access your Gnosis Safe address, you can fetch it in your script using `sphinxSafe()`.
 
 For example, you may need to:
 - Update hardcoded contract addresses
@@ -158,7 +158,7 @@ sphinxConfig.testnets = [
   Network.optimism_sepolia,
   Network.arbitrum_sepolia
 ];
-sphinxConfig.projectName = "My First Project";
+sphinxConfig.projectName = "My_First_Project";
 sphinxConfig.threshold = 1;
 ```
 
@@ -198,7 +198,6 @@ arbitrum_sepolia = "https://arb-sepolia.g.alchemy.com/v2/${RPC_API_KEY}"
 Update your `foundry.toml` file to include a few settings required by Sphinx. We recommend putting them in `[profile.default]`.
 
 ```
-ffi = true
 build_info = true
 extra_output = ['storageLayout']
 fs_permissions = [{ access = "read-write", path = "./"}]
@@ -213,18 +212,18 @@ If you can't get your test suite to pass, we're more than happy to help! Reach o
 
 ## 11. Propose on testnets
 
-Copy and paste one of the following commands to propose your deployment with the DevOps platform. Make sure to replace `<path/to/your/script.s.sol>` with the path to your Forge script.
+Copy and paste one of the following commands to propose your deployment with the DevOps Platform. Make sure to replace `<path/to/your/Script.s.sol>` with the path to your Forge script.
 
 Using Yarn or npm:
 
 ```
-npx sphinx propose <path/to/your/script.s.sol> --testnets
+npx sphinx propose <path/to/your/Script.s.sol> --networks testnets
 ```
 
 Using pnpm:
 
 ```
-pnpm sphinx propose <path/to/your/script.s.sol> --testnets
+pnpm sphinx propose <path/to/your/Script.s.sol> --networks testnets
 ```
 
 Here are the steps that occur when you run this command:

docs/cli-propose.md

@@ -17,34 +17,41 @@ The following steps occur when this command is run:
 3. **Relay**: Sphinx submits the deployment to the Sphinx UI, where the user will approve it.
 
 ## Usage
-```bash
-npx sphinx propose <scriptPath> [--testnets|--mainnets] [--confirm] [--dry-run] [--silent] [--tc <targetContract>]
+
+Using `npx`:
+
+```
+npx sphinx propose <SCRIPT_PATH> --networks <testnets|mainnets> [options]
+```
+
+Using `pnpm`:
+
+```
+pnpm sphinx propose <SCRIPT_PATH> --networks <testnets|mainnets> [options]
 ```
 
 ### Parameters
-- `<scriptPath>`: **Required**. The path to the Forge script file to propose.
+- `<SCRIPT_PATH>`: **Required**. The path to the Forge script file to propose.
 
 ### Options
-- `--testnets`: (boolean) Propose on the 'sphinxConfig.testnets' in the script. You are required to either specify this flag or `--mainnets`.
-- `--mainnets`: (boolean) Propose on the 'sphinxConfig.mainnets' in the script. You are required to either specify this flag or `--testnets`.
-- `--confirm`: (boolean) Confirm the proposal without previewing it.
-- `--dry-run`: (boolean) Dry run the proposal without sending it to Sphinx's backend.
-- `--silent`: (boolean) Silence the output except for error messages. If you specify this flag, you must confirm the proposal by specifying the `--confirm` flag because `--silent` silences the deployment preview.
-- `--target-contract <targetContract>`: (string) The name of the contract in the script. Necessary when the script contains multiple contracts.
-  - Shorthand: `--tc <targetContract>`
+- `--networks <testnets|mainnets>`: **Required**. Choose between proposing on the test networks (`sphinxConfig.testnets`) or the production networks (`sphinxConfig.mainnets`) in your script.
+- `--confirm`: **Optional**. Optionally confirm the proposal without previewing it. Useful for automating proposals.
+- `--dry-run`: **Optional**. Perform a trial run without sending data to Sphinx's backend. Useful for testing and validation.
+- `--silent`: **Optional**. Suppress output to display only error messages. Combine with `--confirm` for silent, confirmed deployments.
+- `--target-contract <TARGET_CONTRACT>`: **Optional**. Specify a contract in multi-contract scripts. Alias: `--tc <TARGET_CONTRACT>`.
 
 ## Examples
 1. Propose a deployment on testnets using a script located at `./path/to/script.s.sol`:
    ```bash
-   npx sphinx propose ./path/to/script.s.sol --testnets
+   npx sphinx propose ./path/to/script.s.sol --networks testnets
    ```
 
 2. Dry run a proposal on production networks using a script located at `./path/to/script.s.sol`:
    ```bash
-   npx sphinx propose ./path/to/script.s.sol --mainnets --dry-run
+   npx sphinx propose ./path/to/script.s.sol --networks mainnets --dry-run
    ```
 
 3. Propose a script at `./path/to/script.s.sol` on production networks, skipping the deployment preview:
    ```bash
-   npx sphinx propose ./path/to/script.s.sol --mainnets --confirm
+   npx sphinx propose ./path/to/script.s.sol --networks mainnets --confirm
    ```

docs/cli-quickstart.md

@@ -1,11 +1,11 @@
 # Getting Started in a New Repository
 
-This guide will introduce you to Sphinx's Foundry plugin and DevOps platform by walking you through a sample multi-chain deployment.
+This guide will introduce you to Sphinx's Foundry plugin and DevOps Platform by walking you through a sample multi-chain deployment.
 
-Deployments are a three-step process with the DevOps platform:
+Deployments are a three-step process with the DevOps Platform:
 
-1. **Propose**: Initiate the deployment from your command line or CI process by submitting the transactions to Sphinx's backend.
-2. **Approve**: Your Gnosis Safe owner(s) approve the deployment by signing a single meta transaction in the Sphinx UI.
+1. **Propose**: Initiate the deployment by submitting it to Sphinx's backend from your command line or CI process.
+2. **Approve**: Your Gnosis Safe owner(s) approve the deployment in the Sphinx UI by signing the deployment's unique identifier with a meta transaction. This unique identifier is the root of a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree), which contains all the transaction data for the deployment across every chain.
 3. **Execute**: Sphinx's backend trustlessly executes the deployment through your Gnosis Safe.
 
 In this guide, you'll create a sample project, propose it on the command line, and then approve it in the Sphinx UI.
@@ -77,9 +77,9 @@ pnpm sphinx init --org-id <SPHINX_ORG_ID> --sphinx-api-key <API_KEY> --alchemy-a
 ```
 
 Command line argument descriptions:
-* `--org-id <SPHINX_ORG_ID>`: Your organization ID from the Sphinx UI.
-* `--sphinx-api-key <API_KEY>`: Your API key from the Sphinx UI.
-* `--alchemy-api-key <API_KEY>`: Your Alchemy API key.
+* `--org-id <SPHINX_ORG_ID>`: Your organization ID from the Sphinx UI (under "Options" -> "API Credentials").
+* `--sphinx-api-key <API_KEY>`: Your API key from the Sphinx UI (under "Options" -> "API Credentials").
+* `--alchemy-api-key <API_KEY>`: Your Alchemy API Key.
 * `--owner <YOUR_ADDRESS>`: The address of an account you own on live networks.
 * `--foundryup`: An optional flag that runs `foundryup` to update Foundry. We recommend using the latest Foundry version with Sphinx.
 * `--pnpm`: An optional flag that creates remappings for pnpm.
@@ -100,18 +100,18 @@ forge test
 
 ## 6. Propose on testnets
 
-Copy and paste one of the following commands to propose your deployment with the DevOps platform.
+Copy and paste one of the following commands to propose your deployment with the DevOps Platform.
 
 Using Yarn or npm:
 
 ```
-npx sphinx propose script/HelloSphinx.s.sol --testnets
+npx sphinx propose script/HelloSphinx.s.sol --networks testnets
 ```
 
 Using pnpm:
 
 ```
-pnpm sphinx propose script/HelloSphinx.s.sol --testnets
+pnpm sphinx propose script/HelloSphinx.s.sol --networks testnets
 ```
 
 Here are the steps that occur when you run this command:

docs/configuration-options.md

@@ -14,9 +14,9 @@ function setUp() public {
 - [Configuration Options](#configuration-options)
   - [`address[] owners`](#address-owners)
   - [`uint256 threshold`](#uint256-threshold)
+  - [`string projectName`](#string-projectname)
   - [`uint256 saltNonce`](#uint256-saltnonce)
 - [DevOps Platform Options](#devops-platform-options)
-  - [`string projectName`](#string-projectname)
   - [`string orgId`](#string-orgid)
   - [`Network[] mainnets`](#network-mainnets)
   - [`Network[] testnets`](#network-testnets)
@@ -37,27 +37,27 @@ sphinxConfig.threshold = 1;
 
 The number of owners required to approve transactions.
 
-### `uint256 saltNonce`
-
-A nonce which is one of the inputs that determines the address of a Gnosis Safe. Changing this to a new value will cause a new Gnosis Safe to be deployed. Defaults to `0`.
-
-## DevOps Platform Options
-
 ### `string projectName`
 
 ```
-sphinxConfig.projectName = "My Project";
+sphinxConfig.projectName = "My_Project";
 ```
 
-The name of your project, which will appear in the Sphinx UI.
+The name of your project, which is the top-level directory for your [deployment artifacts](https://github.com/sphinx-labs/sphinx/blob/main/docs/deployment-artifacts.md).
+
+### `uint256 saltNonce`
+
+An optional nonce which is one of the inputs that determines the `CREATE2` address of a Gnosis Safe. Changing this to a new value will cause a Gnosis Safe to be deployed at a new address. Defaults to `0`.
+
+## DevOps Platform Options
 
 ### `string orgId`
 
 ```
 sphinxConfig.orgId = "abcd-1234";
 ```
 
-Your organization ID from the Sphinx UI. This is a public field, so you don't need to keep it secret.
+Your organization ID from the Sphinx UI (under "Options" -> "API Credentials"). This is a public field, so you don't need to keep it secret.
 
 ### `Network[] mainnets`