Skip to content

Commit e67b248

Browse files
Smartdevs17Smartdevs17
authored
Merge pull request #168 from activatedkc/docs/add-contract-documentation
docs: Add smart contract documentation
2 parents d5ed621 + 1d9f182 commit e67b248

File tree

1 file changed

+194
-0
lines changed

1 file changed

+194
-0
lines changed

‎docs/contracts.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# AgenticPay Smart Contract Documentation
2+
3+
The `AgenticPayContract` is a Soroban-based smart contract designed to facilitate secure payments between clients and freelancers using an escrow mechanism. It ensures funds are held securely and only released upon delivery and approval of work.
4+
5+
## Data Types
6+
7+
### `ProjectStatus` (Enum)
8+
Represents the current lifecycle state of a project.
9+
10+
- `Created`: Project has been initialized but not yet funded.
11+
- `Funded`: Escrow contains the required funds for the project.
12+
- `InProgress`: Freelancer has started working on the project.
13+
- `WorkSubmitted`: Freelancer has submitted the completion reference (e.g., GitHub repo).
14+
- `Verified`: Submitted work has been automatically or manually verified.
15+
- `Completed`: Work approved, funds released, and project finalized.
16+
- `Disputed`: A party has raised a dispute regarding the work or payment.
17+
- `Cancelled`: Project was terminated (e.g., due to deadline expiration or mutual agreement).
18+
19+
### `Project` (Struct)
20+
Main data structure storing project details.
21+
22+
- `id`: Unique identifier (u64).
23+
- `client`: Address of the project creator.
24+
- `freelancer`: Address of the assigned freelancer.
25+
- `amount`: Target budget for the project (i128).
26+
- `deposited`: Current escrow balance (i128).
27+
- `status`: Current state of the project (`ProjectStatus`).
28+
- `github_repo`: Reference to the project workspace or submitted repository.
29+
- `description`: Project description or scope of work.
30+
- `created_at`: Unix timestamp of project creation.
31+
- `deadline`: Unix timestamp for the project completion deadline (0 means no deadline).
32+
33+
### `ProjectInput` (Struct)
34+
Helper struct for batch creation of projects.
35+
36+
- `freelancer`: Address of the freelancer to be assigned.
37+
- `amount`: Project budget.
38+
- `description`: Project description.
39+
- `github_repo`: Workspace reference.
40+
41+
## Public Functions
42+
43+
### `initialize(env: Env, admin: Address)`
44+
Initializes the contract with an administrator address. This address is used for dispute resolution and administrative metadata management.
45+
46+
- **Parameters**:
47+
- `admin`: The address to be set as the contract administrator.
48+
- **Permissions**: Requires authorization from the provided `admin` address.
49+
- **Returns**: None.
50+
51+
### `create_project(env: Env, client: Address, freelancer: Address, amount: i128, description: String, github_repo: String, deadline: u64) -> u64`
52+
Creates a new project and returns its unique ID.
53+
54+
- **Parameters**:
55+
- `client`: The address of the client creating the project.
56+
- `freelancer`: The address of the freelancer assigned to the project.
57+
- `amount`: The budget amount for the project.
58+
- `description`: A brief description of the project.
59+
- `github_repo`: The GitHub repository associated with the project.
60+
- `deadline`: Unix timestamp for the project deadline.
61+
- **Permissions**: Requires authorization from the `client` address.
62+
- **Returns**: `u64` (The ID of the newly created project).
63+
64+
### `batch_create_projects(env: Env, client: Address, projects: Vec<ProjectInput>) -> Vec<u64>`
65+
Creates multiple projects in a single optimized transaction.
66+
67+
- **Parameters**:
68+
- `client`: The address of the client creating the projects.
69+
- `projects`: A vector of `ProjectInput` structs.
70+
- **Permissions**: Requires authorization from the `client` address.
71+
- **Returns**: `Vec<u64>` (A list of IDs for the newly created projects).
72+
73+
### `fund_project(env: Env, project_id: u64, client: Address, amount: i128)`
74+
Deposits funds into a project's escrow. If the total deposited matches or exceeds the project amount, the status transitions to `Funded`.
75+
76+
- **Parameters**:
77+
- `project_id`: The ID of the project to fund.
78+
- `client`: The address of the client funding the project.
79+
- `amount`: The amount to deposit.
80+
- **Permissions**: Requires authorization from the `client` address. The project must be in `Created` status.
81+
- **Returns**: None.
82+
83+
### `submit_work(env: Env, project_id: u64, freelancer: Address, github_repo: String)`
84+
Submits work for a project, typically by providing a GitHub repository URL.
85+
86+
- **Parameters**:
87+
- `project_id`: The ID of the project.
88+
- `freelancer`: The address of the freelancer submitting the work.
89+
- `github_repo`: The URL of the repository containing the work.
90+
- **Permissions**: Requires authorization from the assigned `freelancer`. The project must be in `Funded` or `InProgress` status.
91+
- **Returns**: None.
92+
93+
### `approve_work(env: Env, project_id: u64, client: Address)`
94+
Approves the submitted work, releases the escrowed funds to the freelancer, and marks the project as `Completed`.
95+
96+
- **Parameters**:
97+
- `project_id`: The ID of the project to approve.
98+
- `client`: The address of the client approving the work.
99+
- **Permissions**: Requires authorization from the project `client`. The project must be in `WorkSubmitted` or `Verified` status.
100+
- **Returns**: None.
101+
102+
### `raise_dispute(env: Env, project_id: u64, caller: Address)`
103+
Raises a dispute on a project, shifting it to the `Disputed` status for administrative resolution.
104+
105+
- **Parameters**:
106+
- `project_id`: The ID of the project.
107+
- `caller`: The address of the party raising the dispute.
108+
- **Permissions**: Requires authorization from either the `client` or the `freelancer`.
109+
- **Returns**: None.
110+
111+
### `resolve_dispute(env: Env, project_id: u64, admin: Address, release_to_freelancer: bool)`
112+
Resolves an active dispute, either releasing funds to the freelancer or refunding them to the client.
113+
114+
- **Parameters**:
115+
- `project_id`: The ID of the project.
116+
- `admin`: The administrator address.
117+
- `release_to_freelancer`: If true, funds are released to the freelancer; otherwise, they are refunded to the client.
118+
- **Permissions**: Requires authorization from the stored `admin` address. Project must be in `Disputed` status.
119+
- **Returns**: None.
120+
121+
### `check_deadline(env: Env, project_id: u64) -> bool`
122+
Checks if a project has passed its deadline. If expired and not in a terminal state, the project is automatically cancelled and funds are marked for refund.
123+
124+
- **Parameters**:
125+
- `project_id`: The ID of the project to check.
126+
- **Returns**: `bool` (True if the project was automatically cancelled).
127+
128+
### `get_project(env: Env, project_id: u64) -> Project`
129+
Retrieves the details of a specific project.
130+
131+
- **Parameters**:
132+
- `project_id`: The ID of the project.
133+
- **Returns**: The `Project` struct containing project state.
134+
135+
### `get_project_count(env: Env) -> u64`
136+
Returns the total number of projects created.
137+
138+
- **Returns**: `u64`.
139+
140+
### `set_metadata(env: Env, admin: Address, key: String, value: String)`
141+
Stores an arbitrary metadata key-value pair at the contract level.
142+
143+
- **Parameters**:
144+
- `admin`: The administrator address.
145+
- `key`: The metadata key.
146+
- `value`: The metadata value.
147+
- **Permissions**: Requires administrator authorization.
148+
- **Returns**: None.
149+
150+
### `get_metadata(env: Env, key: String) -> Option<String>`
151+
Retrieves metadata associated with a specific key.
152+
153+
- **Parameters**:
154+
- `key`: The metadata key.
155+
- **Returns**: `Option<String>` containing the value if found.
156+
157+
### `remove_metadata(env: Env, admin: Address, key: String)`
158+
Deletes a metadata entry.
159+
160+
- **Parameters**:
161+
- `admin`: The administrator address.
162+
- `key`: The metadata key.
163+
- **Permissions**: Requires administrator authorization.
164+
- **Returns**: None.
165+
166+
### `upgrade(env: Env, admin: Address, new_wasm_hash: BytesN<32>)`
167+
Upgrades the contract logic to a new WASM binary while preserving all storage.
168+
169+
- **Parameters**:
170+
- `admin`: The administrator address.
171+
- `new_wasm_hash`: The SHA-256 hash of the new contract WASM.
172+
- **Permissions**: Requires administrator authorization.
173+
- **Returns**: None.
174+
175+
### `version(env: Env) -> u32`
176+
Returns the current implementation version of the contract.
177+
178+
- **Returns**: `u32` (Current: 1).
179+
180+
## Workflow Examples
181+
182+
### Standard Flow
183+
1. **Creation**: Client calls `create_project` to define scope and assignee.
184+
2. **Funding**: Client calls `fund_project` to lock funds in escrow.
185+
3. **Submission**: Freelancer calls `submit_work` with proof of delivery.
186+
4. **Completion**: Client calls `approve_work` to release funds.
187+
188+
### Dispute Flow
189+
1. **Conflict**: Either party calls `raise_dispute` if expectations are not met.
190+
2. **Mediation**: Admin reviews and calls `resolve_dispute` to finalize payment or refund.
191+
192+
### Automatic Deadline Expiration
193+
1. **Timeout**: If the `deadline` is set and passed, any user can trigger `check_deadline`.
194+
2. **Cancellation**: The contract automatically cancels the project and authorizes a refund if the deadline is missed.

0 commit comments

Comments
 (0)